summaryrefslogtreecommitdiffstats
path: root/src/include/usr/devicefw/driverif.H
blob: 064a11d28b1db8d5f7712a96ff5734ae12bd8d5f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
/* IBM_PROLOG_BEGIN_TAG                                                   */
/* This is an automatically generated prolog.                             */
/*                                                                        */
/* $Source: src/include/usr/devicefw/driverif.H $                         */
/*                                                                        */
/* OpenPOWER HostBoot Project                                             */
/*                                                                        */
/* Contributors Listed Below - COPYRIGHT 2011,2016                        */
/* [+] International Business Machines Corp.                              */
/*                                                                        */
/*                                                                        */
/* Licensed under the Apache License, Version 2.0 (the "License");        */
/* you may not use this file except in compliance with the License.       */
/* You may obtain a copy of the License at                                */
/*                                                                        */
/*     http://www.apache.org/licenses/LICENSE-2.0                         */
/*                                                                        */
/* Unless required by applicable law or agreed to in writing, software    */
/* distributed under the License is distributed on an "AS IS" BASIS,      */
/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or        */
/* implied. See the License for the specific language governing           */
/* permissions and limitations under the License.                         */
/*                                                                        */
/* IBM_PROLOG_END_TAG                                                     */
/** @file driverif.H
 *  @brief Provides the device driver interfaces for performing device access
 *         and enabling routing registration.
 *
 *  @note These interfaces should only be used by device drivers.  User code
 *        wanting to perform device operations should use userif.H instead.
 */
#ifndef __DEVICEFW_DRIVERIF
#define __DEVICEFW_DRIVERIF

#ifndef PARSER

#include <devicefw/userif.H>
#include <stdarg.h>
#include <builtins.h>
#include <targeting/common/targetservice.H>

#endif // not PARSER

namespace DeviceFW
{
    /** @enum AccessType_DriverOnly
     *  @brief Access types to be used internally by drivers for routing
     *         requests to other drivers.
     */
    enum AccessType_DriverOnly
    {
        XSCOM                   = LAST_ACCESS_TYPE,
        I2C,
        FSISCOM,
        IBSCOM,
        HOSTI2C,
        FSI_I2C,
        SBEFIFOSCOM,

        LAST_DRIVER_ACCESS_TYPE
    };

    /** @enum OperationType
     *  @brief Set of operations which can be registered for.
     */
    enum OperationType
    {
        READ = 0,
        WRITE,

        LAST_OP_TYPE,
        FIRST_OP_TYPE = READ

    };

    /** @enum DriverSpecial
     *  @brief Special Wildcard enum that can be used for drivers to do
     *         routing registrations.
     */
    enum DriverSpecial
    {
        WILDCARD = -1,
    };

#ifndef PARSER
    /** Construct the device addressing parameters for FSISCOM device ops.
     *  @param[in] i_address - FSISCOM address to operate on.
     */
    #define DEVICE_FSISCOM_ADDRESS(i_address) \
        DeviceFW::FSISCOM, static_cast<uint64_t>((i_address))

    /** Construct the device addressing parameters for XSCOM device ops.
     *  @param[in] i_address - XSCom address to operate on.
     */
    #define DEVICE_XSCOM_ADDRESS(i_address) \
        DeviceFW::XSCOM, static_cast<uint64_t>((i_address))

    /** Construct the device addressing parameters for IBSCOM (inband scom)
     *  device ops.
     *  @param[in] i_address - IBSCOM address to operate on.
     */
    #define DEVICE_IBSCOM_ADDRESS(i_address) \
        DeviceFW::IBSCOM, static_cast<uint64_t>((i_address))

    /**
     * @brief Macro that handles the I2C parameters
     */
    #define DEVICE_I2C_PARMS(port, engine, devAddr, offset_len, offset)\
        static_cast<uint64_t>( port ),\
        static_cast<uint64_t>( engine ),\
        static_cast<uint64_t>( devAddr ),\
        static_cast<uint64_t>( offset_len ),\
        static_cast<uint8_t*>( offset )

    /**
     * Construct the device addressing parameters for the I2C device ops.
     * @param[in] i_port - Which port to use from the I2C master.
     * @param[in] i_engine - Which I2C master engine to use.
     * @param[in] i_devAddr - The device address on a given engine/port.
     * @note '0' and 'NULL' added to line up with other DeviceFW::I2C
     */
    #define DEVICE_I2C_ADDRESS( i_port, i_engine, i_devAddr )\
        DeviceFW::I2C, DEVICE_I2C_PARMS(i_port, i_engine, i_devAddr, 0, NULL)

    /**
     * Construct the device addressing parameters for the I2C-offset device ops.
     * @param[in] i_port - Which port to use from the I2C master.
     * @param[in] i_engine - Which I2C master engine to use.
     * @param[in] i_devAddr - The device address on a given engine/port.
     * @param[in] i_offset_len - Length of offset (in bytes)
     * @param[in] i_offset - Offset into I2C device
     */
    #define DEVICE_I2C_ADDRESS_OFFSET( i_port, i_engine, i_devAddr, i_offset_len, i_offset)\
        DeviceFW::I2C,  DEVICE_I2C_PARMS(i_port, i_engine, i_devAddr, i_offset_len, i_offset)


    /**
     * Construct the device addressing parameters for locking the page
     * attribute of an I2C master target
     *
     * @param[in] i_port - Which port to use from the I2C master.
     * @param[in] i_engine - Which I2C master engine to use.
     * @param[in] i_shouldLock - bool to determine whether we are
     *                           attempting to lock or unlock the page.
     * @param[in] i_desired_page - The EEPROM page we want to switch to
     *                             iff a page switch is needed.
     * @param[in] i_lockMutex - bool to determine whether we actually
     *             want to lock the page mutex or not. This bool allows
     *             us to switch pages mid read without hitting a deadlock.
     */
#define DEVICE_I2C_CONTROL_PAGE_OP( i_port, i_engine, i_shouldLock, i_desired_page, i_lockMutex )\
            DeviceFW::I2C,\
            static_cast<uint64_t>(i_port),\
            static_cast<uint64_t>(i_engine),\
            0xffffffff,\
            static_cast<uint64_t>(i_shouldLock),\
            static_cast<uint64_t>(i_desiredPage),\
            static_cast<uint64_t>(i_lockMutex)


    /**
     * Construct the device addressing parameters for the Host I2C device ops.
     * @param[in] i_port - Which port to use from the I2C master.
     * @param[in] i_engine - Which I2C master engine to use.
     * @param[in] i_devAddr - The device address on a given engine/port.
     * @note '0' and 'NULL' added to line up with other DeviceFW::I2C
     */
    #define DEVICE_HOSTI2C_ADDRESS( i_port, i_engine, i_devAddr )\
        DeviceFW::HOSTI2C, DEVICE_I2C_PARMS(i_port, i_engine, i_devAddr, 0, NULL)

    /**
     * Construct the device addressing parameters for the Host I2C-offset device ops.
     * @param[in] i_port - Which port to use from the I2C master.
     * @param[in] i_engine - Which I2C master engine to use.
     * @param[in] i_devAddr - The device address on a given engine/port.
     * @param[in] i_offset_len - Length of offset (in bytes)
     * @param[in] i_offset - Offset into I2C device
     */
    #define DEVICE_HOSTI2C_ADDRESS_OFFSET( i_port, i_engine, i_devAddr, i_offset_len, i_offset)\
        DeviceFW::HOSTI2C, DEVICE_I2C_PARMS(i_port, i_engine, i_devAddr, i_offset_len, i_offset)

    /**
     * Construct the device addressing parameters for the FSI I2C device ops.
     * @param[in] i_port - Which port to use from the I2C master.
     * @param[in] i_engine - Which I2C master engine to use.
     * @param[in] i_devAddr - The device address on a given engine/port.
     * @note '0' and 'NULL' added to line up with other DeviceFW::I2C
     */
    #define DEVICE_FSI_I2C_ADDRESS( i_port, i_engine, i_devAddr )\
        DeviceFW::FSI_I2C, DEVICE_I2C_PARMS(i_port, i_engine, i_devAddr, 0, NULL)

    /**
     * Construct the device addressing parameters for the FSI I2C-offset device ops.
     * @param[in] i_port - Which port to use from the I2C master.
     * @param[in] i_engine - Which I2C master engine to use.
     * @param[in] i_devAddr - The device address on a given engine/port.
     * @param[in] i_offset_len - Length of offset (in bytes)
     * @param[in] i_offset - Offset into I2C device
     */
    #define DEVICE_FSI_I2C_ADDRESS_OFFSET( i_port, i_engine, i_devAddr, i_offset_len, i_offset)\
        DeviceFW::FSI_I2C, DEVICE_I2C_PARMS(i_port, i_engine, i_devAddr, i_offset_len, i_offset)

    /** Construct the device addressing parameters for the SBE FIFO Scom
     *  device ops.
     *  @param[in] i_address - scom address to operate on.
     */
    #define DEVICE_SBEFIFOSCOM_ADDRESS(i_address) \
        DeviceFW::SBEFIFOSCOM, static_cast<uint64_t>((i_address))

    /** @class InvalidParameterType
     *  @brief Unused type to cause compiler fails for invalid template types.
     *
     *  Forward Declaration of type that is never actually used anywhere.
     *
     *  Assists in making more developer friendly compiler fails when a
     *  template function is called for which there is no specialization and
     *  the default template function should never be used.  This is used for
     *  allowing function calls that take multiple enum types but still provide
     *  type-safety above a int-parameter.
     */
    class InvalidParameterType;

    /** @typedef deviceOp_t
     *  @brief Function prototype for registered device-driver operations.
     */
    typedef errlHndl_t(*deviceOp_t)(OperationType,
                                    TARGETING::Target*,
                                    void*, size_t&,
                                    int64_t, va_list);

    /**
     *  @brief Register a device driver routing function with the framework.
     *
     *  @param[in] i_opType - Enumeration specifying the operation this
     *                        driver performs. (Read, Write, Wildcard)
     *  @param[in] i_accessType - Enumeration specifying the access type this
     *                            driver performs. (SCOM, XSCOM, PNOR, etc.)
     *  @param[in] i_targetType - Enumeration specifying the target type this
     *                            driver performs. (Proc, MC, Wildcard, etc.)
     *  @param[in] i_regRoute - The function being registered.
     *
     *  This function call be called to register a device driver routing
     *  function with the framework.  If it is desired to always register a
     *  device driver when the module associated with that driver is loaded,
     *  the DEVICE_REGISTER_ROUTE macro can be used.
     *
     *  <PRE>
     *  Example usage:
     *          // High-level address manipulation routing function.
     *          deviceRegisterRoute(WILDCARD,
     *                              SCOM,
     *                              TYPE_CORE,
     *                              &scomAdjustCoreAddresses);
     *
     *          // Low-level (internal) XSCOM read operation.
     *          deviceRegisterRoute(READ,
     *                              XSCOM,
     *                              TYPE_PROC,
     *                              &xscomPerformRead);
     *  </PRE>
     *
     * @note Valid OpType are OperatorType enum or WILDCARD.
     * @note Valid TargType are TargetType enum or WILDCARD.
     * @note Valid AccType are AccessType or AccessType_DriverOnly; WILDCARD is
     *       not permitted.
     *
     * @note Any unsupported enumeration type will result in a compile error
     *       referencing a InvalidParameterType class.
     */
    template <typename OpType, typename AccType, typename TargType>
    void deviceRegisterRoute(OpType i_opType,
                             AccType i_accessType,
                             TargType i_targetType,
                             deviceOp_t i_regRoute)
    {
        return InvalidParameterType(); // Cause a compile fail if not one of
                                       // the explicit template specializations.
    }

        /** Assistance macro for stringification. */
    #define __DEVICE_REGISTER_ROUTE_XYZ(X,Y,Z) X##Y##Z
        /** Assistance macro for stringification. */
    #define __DEVICE_REGISTER_ROUTE_MAKENAME(X,Y,Z) \
                    __DEVICE_REGISTER_ROUTE_XYZ(X,Y,Z)

    /**
     *  @brief Create a static constructed registration of a device driver
     *         function when a module is loaded.
     *
     *  Parameters are the same as DeviceFW::deviceRegisterRoute, except the
     *  route function should be passed by name as opposed to pointer.
     *
     *  If the route function is in a namespace, then this definition must
     *  also be placed into that namespace.
     */
    #define DEVICE_REGISTER_ROUTE(i_opType, i_accessType, \
                                  i_targetType, i_regRoute) \
        class __DEVICE_REGISTER_ROUTE_MAKENAME(DeviceRouteRegistrator_, \
                                               i_regRoute, __LINE__) \
        { \
            public: \
                __DEVICE_REGISTER_ROUTE_MAKENAME(DeviceRouteRegistrator_, \
                                                 i_regRoute, __LINE__)() \
                { \
                    DeviceFW::deviceRegisterRoute(i_opType, i_accessType, \
                                                  i_targetType, &i_regRoute); \
                } \
        }; \
        __DEVICE_REGISTER_ROUTE_MAKENAME(DeviceRouteRegistrator_, \
                                         i_regRoute, __LINE__) \
            __DEVICE_REGISTER_ROUTE_MAKENAME(DeviceRouteRegistrator_instance_, \
                                             i_regRoute, __LINE__);

    /**
     *  @brief Perform a device operation by routing through the framework and
     *         calling the appropriate registered operation.
     *
     *  @param[in] i_opType - Operation request (READ vs WRITE).
     *  @param[in] i_target - Target to perform operation on.
     *  @param[in,out] io_buffer - Data buffer for operation.
     *  @param[in,out] io_buflen - Length of buffer / result size.
     *  @param[in] i_accessType - Type of hardware access method to perform.
     *
     *  This function has similar behavior as the user-visible deviceRead and
     *  deviceWrite functions and is meant as a method for device drivers to
     *  perform accesses which may be only visible to internal drivers.
     */
    template <typename AccType>
    errlHndl_t deviceOp(OperationType i_opType,
                        TARGETING::Target* i_target,
                        void* io_buffer, size_t& io_buflen,
                        AccType i_accessType, ...)
    {
        return InvalidParameterType(); // Cause a compile fail if not one of
                                       // the explicit template specializations.
    }

    /**
     *  @brief Perform a device operation by routing through the framework and
     *         calling the appropriate registered operation.
     *
     *  @param[in] i_opType - Operation request (READ vs WRITE).
     *  @param[in] i_target - Target to perform operation on.
     *  @param[in,out] io_buffer - Data buffer for operation.
     *  @param[in,out] io_buflen - Length of buffer / result size.
     *  @param[in] i_accessType - Type of hardware access method to perform.
     *  @param[in] i_args - va_list of parameters for device operation.
     *
     *  This function has similar behavior as the user-visible deviceRead and
     *  deviceWrite functions and is meant as a method for device drivers to
     *  perform accesses which may be only visible to internal drivers.
     */
    template <typename AccType>
    errlHndl_t deviceOpValist(OperationType i_opType,
                        TARGETING::Target* i_target,
                        void* io_buffer, size_t& io_buflen,
                        AccType i_accessType, va_list i_args)
    {
        return InvalidParameterType(); // Cause a compile fail if not one of
                                       // the explicit template specializations.
    }

    // --- Below are template specializations to aid in type-safety. ---

    // deviceRegisterRoute:
    //          OpType - OperationType or WILDCARD
    //          TargType - TargetType or WILDCARD
    //          AccType - AccessType, AccessType_DriverOnly (no WILDCARD).

    template <>
    void deviceRegisterRoute<>(OperationType i_opType,
                               AccessType i_accessType,
                               TARGETING::TYPE i_targetType,
                               deviceOp_t i_regRoute);
    template <>
    void deviceRegisterRoute<>(OperationType i_opType,
                               AccessType_DriverOnly i_accessType,
                               TARGETING::TYPE i_targetType,
                               deviceOp_t i_regRoute);
    template <>
    void deviceRegisterRoute<>(OperationType i_opType,
                               AccessType i_accessType,
                               DriverSpecial i_targetType,
                               deviceOp_t i_regRoute);
    template <>
    void deviceRegisterRoute<>(OperationType i_opType,
                               AccessType_DriverOnly i_accessType,
                               DriverSpecial i_targetType,
                               deviceOp_t i_regRoute);
    template <>
    void deviceRegisterRoute<>(DriverSpecial i_opType,
                               AccessType i_accessType,
                               TARGETING::TYPE i_targetType,
                               deviceOp_t i_regRoute);
    template <>
    void deviceRegisterRoute<>(DriverSpecial i_opType,
                               AccessType_DriverOnly i_accessType,
                               TARGETING::TYPE i_targetType,
                               deviceOp_t i_regRoute);
    template <>
    void deviceRegisterRoute<>(DriverSpecial i_opType,
                               AccessType i_accessType,
                               DriverSpecial i_targetType,
                               deviceOp_t i_regRoute);
    template <>
    void deviceRegisterRoute<>(DriverSpecial i_opType,
                               AccessType_DriverOnly i_accessType,
                               DriverSpecial i_targetType,
                               deviceOp_t i_regRoute);

    // deviceOp:
    //          OpType - OperationType only.
    //          TargType - TargetType only.
    //          AccType - AccessType, AccessType_DriverOnly (no WILDCARD).
    template <>
    errlHndl_t deviceOp<>(OperationType i_opType,
                          TARGETING::Target* i_target,
                          void* io_buffer, size_t& io_buflen,
                          AccessType i_accessType, ...);
    template <>
    errlHndl_t deviceOp<>(OperationType i_opType,
                          TARGETING::Target* i_target,
                          void* io_buffer, size_t& io_buflen,
                          AccessType_DriverOnly i_accessType, ...);

    // deviceOpValist:
    //          OpType - OperationType only.
    //          TargType - TargetType only.
    //          AccType - AccessType, AccessType_DriverOnly (no WILDCARD).
    //          args - va_list of parameters
    template <>
    errlHndl_t deviceOpValist<>(OperationType i_opType,
                          TARGETING::Target* i_target,
                          void* io_buffer, size_t& io_buflen,
                          AccessType i_accessType, va_list i_args);
    template <>
    errlHndl_t deviceOpValist<>(OperationType i_opType,
                          TARGETING::Target* i_target,
                          void* io_buffer, size_t& io_buflen,
                          AccessType_DriverOnly i_accessType, va_list i_args);
#endif // not PARSER
};

#endif
OpenPOWER on IntegriCloud