source: rtems/cpukit/include/drvmgr/drvmgr.h @ 2afb22b

5
Last change on this file since 2afb22b was 2afb22b, checked in by Chris Johns <chrisj@…>, on Dec 23, 2017 at 7:18:56 AM

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 37.6 KB
Line 
1/* Driver Manager Interface.
2 *
3 * COPYRIGHT (c) 2009 Cobham Gaisler AB.
4 *
5 * The license and distribution terms for this file may be
6 * found in the file LICENSE in this distribution or at
7 * http://www.rtems.org/license/LICENSE.
8 */
9
10#ifndef _DRIVER_MANAGER_H_
11#define _DRIVER_MANAGER_H_
12
13#include <rtems.h>
14#include <drvmgr/drvmgr_list.h>
15#include <stdint.h>
16#include <rtems/score/basedefs.h>
17#include <rtems/score/smpimpl.h>
18
19#ifdef __cplusplus
20extern "C" {
21#endif
22
23/*** Configure Driver manager ***/
24
25/* Define the number of initialization levels of device drivers */
26#define DRVMGR_LEVEL_MAX 4
27
28/* Default to use semahpores for protection. Initialization works without
29 * locks and after initialization too if devices are not removed.
30 */
31#ifndef DRVMGR_USE_LOCKS
32#define DRVMGR_USE_LOCKS 1
33#endif
34
35struct drvmgr_dev;      /* Device */
36struct drvmgr_bus;      /* Bus */
37struct drvmgr_drv;      /* Driver */
38
39/*** List Interface shortcuts ***/
40#define BUS_LIST_HEAD(list) LIST_HEAD(list, struct drvmgr_bus)
41#define BUS_LIST_TAIL(list) LIST_TAIL(list, struct drvmgr_bus)
42#define DEV_LIST_HEAD(list) LIST_HEAD(list, struct drvmgr_dev)
43#define DEV_LIST_TAIL(list) LIST_TAIL(list, struct drvmgr_dev)
44#define DRV_LIST_HEAD(list) LIST_HEAD(list, struct drvmgr_drv)
45#define DRV_LIST_TAIL(list) LIST_TAIL(list, struct drvmgr_drv)
46
47/*** Bus indentification ***/
48#define DRVMGR_BUS_TYPE_NONE 0          /* Not a valid bus */
49#define DRVMGR_BUS_TYPE_ROOT 1          /* Hard coded bus */
50#define DRVMGR_BUS_TYPE_PCI 2           /* PCI bus */
51#define DRVMGR_BUS_TYPE_AMBAPP 3        /* AMBA Plug & Play bus */
52#define DRVMGR_BUS_TYPE_LEON2_AMBA 4    /* LEON2 hardcoded bus */
53#define DRVMGR_BUS_TYPE_AMBAPP_DIST 5   /* Distibuted AMBA Plug & Play bus accessed using a communication interface */
54#define DRVMGR_BUS_TYPE_SPW_RMAP 6      /* SpaceWire Network bus */
55#define DRVMGR_BUS_TYPE_AMBAPP_RMAP 7   /* SpaceWire RMAP accessed AMBA Plug & Play bus */
56
57enum {
58        DRVMGR_OBJ_NONE = 0,
59        DRVMGR_OBJ_DRV = 1,
60        DRVMGR_OBJ_BUS = 2,
61        DRVMGR_OBJ_DEV = 3,
62};
63
64/*** Driver indentification ***
65 *
66 * 64-bit identification integer definition
67 *  * Bus ID 8-bit [7..0]
68 *  * Reserved 8-bit field [63..56]
69 *  * Device ID specific for bus type 48-bit [55..8]  (Different buses have
70 *    different unique identifications for hardware/driver.)
71 *
72 * ID Rules
73 *  * A root bus driver must always have device ID set to 0. There can only by
74 *    one root bus driver for a certain bus type.
75 *  * A Driver ID must identify a unique hardware core
76 *
77 */
78
79/* Bus ID Mask */
80#define DRIVER_ID_BUS_MASK 0x00000000000000FFULL
81
82/* Reserved Mask for future use */
83#define DRIVER_ID_RSV_MASK 0xFF00000000000000ULL
84
85/* Reserved Mask for future use */
86#define DRIVER_ID_DEV_MASK 0x00FFFFFFFFFFFF00ULL
87
88/* Set Bus ID Mask. */
89#define DRIVER_ID(busid, devid) ((unsigned long long) \
90        ((((unsigned long long)(devid) << 8) & DRIVER_ID_DEV_MASK) | \
91         ((unsigned long long)(busid) & DRIVER_ID_BUS_MASK)))
92
93/* Get IDs */
94#define DRIVER_BUSID_GET(id)    ((unsigned long long)(id) & DRIVER_ID_BUS_MASK)
95#define DRIVER_DEVID_GET(id)    (((unsigned long long)(id) & DRIVER_ID_DEV_MASK) >> 8)
96
97#define DRIVER_ROOTBUS_ID(bus_type)     DRIVER_ID(bus_type, 0)
98
99/*** Root Bus drivers ***/
100
101/* Generic Hard coded Root bus: Driver ID */
102#define DRIVER_ROOT_ID          DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_ROOT)
103
104/* PCI Plug & Play bus: Driver ID */
105#define DRIVER_PCIBUS_ID        DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_PCI)
106
107/* AMBA Plug & Play bus: Driver ID */
108#define DRIVER_GRLIB_AMBAPP_ID  DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_AMBAPP)
109
110/* AMBA Hard coded bus: Driver ID */
111#define DRIVER_LEON2_AMBA_ID    DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_LEON2_AMBA)
112
113/* Distributed AMBA Plug & Play bus: Driver ID */
114#define DRIVER_AMBAPP_DIST_ID   DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_AMBAPP_DIST)
115
116/*! Bus parameters used by driver interface functions to aquire information
117 * about bus. All Bus drivers should implement the operation 'get_params' so
118 * that the driver interface routines can access bus dependent information in
119 * an non-dependent way.
120 */
121struct drvmgr_bus_params {
122        char            *dev_prefix;            /*!< Optional name prefix */
123};
124
125/* Interrupt Service Routine (ISR) */
126typedef void (*drvmgr_isr)(void *arg);
127
128/*! Bus operations */
129struct drvmgr_bus_ops {
130        /* Functions used internally within driver manager */
131        int     (*init[DRVMGR_LEVEL_MAX])(struct drvmgr_bus *);
132        int     (*remove)(struct drvmgr_bus *);
133        int     (*unite)(struct drvmgr_drv *, struct drvmgr_dev *);     /*!< Unite Hardware Device with Driver */
134
135        /* Functions called indirectly from drivers */
136        int     (*int_register)(struct drvmgr_dev *, int index, const char *info, drvmgr_isr isr, void *arg);
137        int     (*int_unregister)(struct drvmgr_dev *, int index, drvmgr_isr isr, void *arg);
138        int     (*int_clear)(struct drvmgr_dev *, int index);
139        int     (*int_mask)(struct drvmgr_dev *, int index);
140        int     (*int_unmask)(struct drvmgr_dev *, int index);
141#ifdef RTEMS_SMP
142        int     (*int_set_affinity)(struct drvmgr_dev *, int index,
143                                    const Processor_mask *cpus);
144#endif
145
146        /* Get Parameters */
147        int     (*get_params)(struct drvmgr_dev *, struct drvmgr_bus_params *);
148        /* Get Frequency of Bus */
149        int     (*get_freq)(struct drvmgr_dev*, int, unsigned int*);
150        /*! Function called to request information about a device. The bus
151         *  driver interpret the bus-specific information about the device.
152         */
153        void    (*get_info_dev)(struct drvmgr_dev *,
154                                void (*print)(void *p, char *str), void *p);
155};
156#define BUS_OPS_NUM (sizeof(struct drvmgr_bus_ops)/sizeof(void (*)(void)))
157
158struct drvmgr_func {
159        int funcid;
160        void *func;
161};
162#define DRVMGR_FUNC(_ID_, _FUNC_) {(int)(_ID_), (void *)(_FUNC_)}
163#define DRVMGR_FUNC_END {0, NULL}
164
165/*** Resource definitions ***
166 *
167 * Overview of structures:
168 *  All bus resources entries (_bus_res) are linked together per bus
169 *  (bus_info->reslist). One bus resource entry has a pointer to an array of
170 *  driver resources (_drv_res). One driver resouces is made out of an array
171 *  of keys (drvmgr_key). All keys belongs to the same driver and harwdare
172 *  device. Each key has a Name, Type ID and Data interpreted differently
173 *  depending on the Type ID (union drvmgr_key_value).
174 *
175 */
176
177/* Key Data Types */
178enum drvmgr_kt {
179        DRVMGR_KT_ANY = -1,
180        DRVMGR_KT_NONE = 0,
181        DRVMGR_KT_INT = 1,
182        DRVMGR_KT_STRING = 2,
183        DRVMGR_KT_POINTER = 3,
184};
185
186#define DRVMGR_KEY_EMPTY        {NULL, DRVMGR_KT_NONE, {0}}
187#define DRVMGR_RES_EMPTY        {0, 0, NULL}
188#define MMAP_EMPTY      {0, 0, 0}
189
190/*! Union of different values */
191union drvmgr_key_value {
192        unsigned int            i;      /*!< Key data type UNSIGNED INTEGER */
193        char                    *str;   /*!< Key data type STRING */
194        void                    *ptr;   /*!< Key data type ADDRESS/POINTER */
195};
196
197/* One key. One Value. Holding information relevant to the driver. */
198struct drvmgr_key {
199        char                    *key_name;      /* Name of key */
200        enum drvmgr_kt          key_type;       /* How to interpret key_value */
201        union drvmgr_key_value  key_value;      /* The value or pointer to value */
202};
203
204/*! Driver resource entry, Driver resources for a certain device instance,
205 *  containing a number of keys where each key hold the data of interest.
206 */
207struct drvmgr_drv_res {
208        uint64_t                drv_id;         /*!< Identifies the driver this resource is aiming */
209        int                     minor_bus;      /*!< Indentifies a specfic device */
210        struct drvmgr_key       *keys;          /*!< First key in key array, ended with KEY_EMPTY */
211};
212
213/*! Bus resource list node */
214struct drvmgr_bus_res {
215        struct drvmgr_bus_res   *next;          /*!< Next resource node in list */
216        struct drvmgr_drv_res   resource[];     /*!< Array of resources, one per device instance */
217};
218
219/*! MAP entry. Describes an linear address space translation. Untranslated
220 *  Start, Translated Start and length.
221 *
222 * Used by bus drivers to describe the address translation needed for
223 * the translation driver interface.
224 */
225struct drvmgr_map_entry {
226        char            *name;          /*!< Map Name */
227        unsigned int    size;           /*!< Size of map window */
228        char            *from_adr;      /*!< Start address of access window used
229                                         *   to reach into remote bus */
230        char            *to_adr;        /*!< Start address of remote system
231                                         *   address range */
232};
233#define DRVMGR_TRANSLATE_ONE2ONE        NULL
234#define DRVMGR_TRANSLATE_NO_BRIDGE      ((void *)1)  /* No bridge, error */
235
236/*! Bus information. Describes a bus. */
237struct drvmgr_bus {
238        int                     obj_type;       /*!< DRVMGR_OBJ_BUS */
239        unsigned char           bus_type;       /*!< Type of bus */
240        unsigned char           depth;          /*!< Bus level distance from root bus */
241        struct drvmgr_bus       *next;          /*!< Next Bus */
242        struct drvmgr_dev       *dev;           /*!< Bus device, the hardware... */
243        void                    *priv;          /*!< Private data structure used by BUS driver */
244        struct drvmgr_dev       *children;      /*!< Hardware devices on this bus */
245        struct drvmgr_bus_ops   *ops;           /*!< Bus operations supported by this bus driver */
246        struct drvmgr_func      *funcs;         /*!< Extra operations */
247        int                     dev_cnt;        /*!< Number of devices this bus has */
248        struct drvmgr_bus_res   *reslist;       /*!< Bus resources, head of a linked list of resources. */
249        struct drvmgr_map_entry *maps_up;       /*!< Map Translation, array of address spaces upstreams to CPU */
250        struct drvmgr_map_entry *maps_down;     /*!< Map Translation, array of address spaces downstreams to Hardware */
251
252        /* Bus status */
253        int                     level;          /*!< Initialization Level of Bus */
254        int                     state;          /*!< Init State of Bus, BUS_STATE_* */
255        int                     error;          /*!< Return code from bus->ops->initN() */
256};
257
258/* States of a bus */
259#define BUS_STATE_INIT_FAILED   0x00000001      /* Initialization Failed */
260#define BUS_STATE_LIST_INACTIVE 0x00001000      /* In inactive bus list */
261#define BUS_STATE_DEPEND_FAILED 0x00000004      /* Device init failed */
262
263/* States of a device */
264#define DEV_STATE_INIT_FAILED   0x00000001      /* Initialization Failed */
265#define DEV_STATE_INIT_DONE     0x00000002      /* All init levels completed */
266#define DEV_STATE_DEPEND_FAILED 0x00000004      /* Parent Bus init failed */
267#define DEV_STATE_UNITED        0x00000100      /* Device United with Device Driver */
268#define DEV_STATE_REMOVED       0x00000200      /* Device has been removed (unregistered) */
269#define DEV_STATE_IGNORED       0x00000400      /* Device was ignored according to user's request, the device
270                                                 * was never reported to it's driver (as expected).
271                                                 */
272#define DEV_STATE_LIST_INACTIVE 0x00001000      /* In inactive device list */
273
274/*! Device information */
275struct drvmgr_dev {
276        int                     obj_type;       /*!< DRVMGR_OBJ_DEV */
277        struct drvmgr_dev       *next;          /*!< Next device */
278        struct drvmgr_dev       *next_in_bus;   /*!< Next device on the same bus */
279        struct drvmgr_dev       *next_in_drv;   /*!< Next device using the same driver */
280
281        struct drvmgr_drv       *drv;           /*!< The driver owning this device */
282        struct drvmgr_bus       *parent;        /*!< Bus that this device resides on */
283        short                   minor_drv;      /*!< Device number within driver */
284        short                   minor_bus;      /*!< Device number on bus (for device separation) */
285        char                    *name;          /*!< Name of Device Hardware */
286        void                    *priv;          /*!< Pointer to driver private device structure */
287        void                    *businfo;       /*!< Host bus specific information */
288        struct drvmgr_bus       *bus;           /*!< Pointer to bus, set only if this is a bridge */
289
290        /* Device Status */
291        unsigned int            state;          /*!< State of device, see DEV_STATE_* */
292        int                     level;          /*!< Init Level */
293        int                     error;          /*!< Error state returned by driver */
294};
295
296/*! Driver operations, function pointers. */
297struct drvmgr_drv_ops {
298        int     (*init[DRVMGR_LEVEL_MAX])(struct drvmgr_dev *); /*! Function doing Init Stage 1 of a hardware device */
299        int     (*remove)(struct drvmgr_dev *); /*! Function called when device instance is to be removed */
300        int     (*info)(struct drvmgr_dev *, void (*print)(void *p, char *str), void *p, int, char *argv[]);/*! Function called to request information about a device or driver */
301};
302#define DRVMGR_OPS_NUM(x) (sizeof(x)/sizeof(void (*)(void)))
303
304/*! Device driver description */
305struct drvmgr_drv {
306        int                     obj_type;       /*!< DRVMGR_OBJ_DRV */
307        struct drvmgr_drv       *next;          /*!< Next Driver */
308        struct drvmgr_dev       *dev;           /*!< Devices using this driver */
309
310        uint64_t                drv_id;         /*!< Unique Driver ID */
311        char                    *name;          /*!< Name of Driver */
312        int                     bus_type;       /*!< Type of Bus this driver supports */
313        struct drvmgr_drv_ops   *ops;           /*!< Driver operations */
314        struct drvmgr_func      *funcs;         /*!< Extra Operations */
315        unsigned int            dev_cnt;        /*!< Number of devices in dev */
316        unsigned int            dev_priv_size;  /*!< If non-zero DRVMGR will allocate memory for dev->priv */
317};
318
319/*! Structure defines a function pointer called when driver manager is ready
320 *  for drivers to register themselfs. Used to select drivers available to the
321 *  driver manager.
322 */
323typedef void (*drvmgr_drv_reg_func)(void);
324
325/*** DRIVER | DEVICE | BUS FUNCTIONS ***/
326
327/* Return Codes */
328enum {
329        DRVMGR_OK = 0,          /* Sucess */
330        DRVMGR_NOMEM = 1,       /* Memory allocation error */
331        DRVMGR_EIO = 2,         /* I/O error */
332        DRVMGR_EINVAL = 3,      /* Invalid parameter */
333        DRVMGR_ENOSYS = 4,
334        DRVMGR_TIMEDOUT = 5,    /* Operation timeout error */
335        DRVMGR_EBUSY = 6,
336        DRVMGR_ENORES = 7,      /* Not enough resources */
337        DRVMGR_FAIL = -1        /* Unspecified failure */
338};
339
340/*! Initialize data structures of the driver management system.
341 *  Calls predefined register driver functions so that drivers can
342 *  register themselves.
343 */
344extern void _DRV_Manager_initialization(void);
345
346/*! Take all devices into init level 'level', all devices registered later
347 *  will directly be taken into this level as well, ensuring that all
348 *  registerd devices has been taken into the level.
349 *
350 */
351extern void _DRV_Manager_init_level(int level);
352
353/*! This function must be defined by the BSP when the driver manager is enabled
354 * and initialized during BSP initialization. The function is called after a
355 * init level is reached the first time by the driver manager.
356 */
357extern void bsp_driver_level_hook(int level);
358
359/*! Init driver manager all in one go, will call _DRV_Manager_initialization(),
360 *  then _DRV_Manager_init_level([1..DRVMGR_LEVEL_MAX]).
361 *  Typically called from Init task when user wants to initilize driver
362 *  manager after startup, otherwise not used.
363 */
364extern int drvmgr_init(void);
365
366/* Take registered buses and devices into the correct init level,
367 * this function is called from _init_level() so normally
368 * we don't need to call it directly.
369 */
370extern void drvmgr_init_update(void);
371
372/*! Register Root Bus device driver */
373extern int drvmgr_root_drv_register(struct drvmgr_drv *drv);
374
375/*! Register a driver */
376extern int drvmgr_drv_register(struct drvmgr_drv *drv);
377
378/*! Register a device */
379extern int drvmgr_dev_register(struct drvmgr_dev *dev);
380
381/*! Remove a device, and all its children devices if device is a bus device. The
382 *  device driver will be requested to remove the device and once gone from bus,
383 *  device and driver list the device is put into a inactive list for debugging
384 *  (this is optional by using remove argument).
385 *
386 * Removing the Root Bus Device is not supported.
387 *
388 * \param remove If non-zero the device will be deallocated, and not put into
389 *               the inacitve list.
390 */
391extern int drvmgr_dev_unregister(struct drvmgr_dev *dev);
392
393/*! Register a bus */
394extern int drvmgr_bus_register(struct drvmgr_bus *bus);
395
396/*! Unregister a bus */
397extern int drvmgr_bus_unregister(struct drvmgr_bus *bus);
398
399/*! Unregister all child devices of a bus.
400 *
401 * This function is called from the bus driver, from a "safe" state where
402 * devices will not be added or removed on this particular bus at this time
403 */
404extern int drvmgr_children_unregister(struct drvmgr_bus *bus);
405
406/* Separate a device from the driver it has been united with */
407extern int drvmgr_dev_drv_separate(struct drvmgr_dev *dev);
408
409/*! Allocate a device structure, if no memory available
410 *  rtems_error_fatal_occurred is called.
411 * The 'extra' argment tells how many bytes extra space is to be allocated after
412 * the device structure, this is typically used for "businfo" structures. The extra
413 * space is always aligned to a 4-byte boundary.
414 */
415extern int drvmgr_alloc_dev(struct drvmgr_dev **pdev, int extra);
416
417/*! Allocate a bus structure, if no memory available rtems_error_fatal_occurred
418 * is called.
419 * The 'extra' argment tells how many bytes extra space is to be allocated after
420 * the device structure, this is typically used for "businfo" structures. The
421 * extra space is always aligned to a 4-byte boundary.
422 */
423extern int drvmgr_alloc_bus(struct drvmgr_bus **pbus, int extra);
424
425/*** DRIVER RESOURCE FUNCTIONS ***/
426
427/*! Add resources to a bus, typically used by a bus driver.
428 *
429 * \param bus   The Bus to add the resources to.
430 * \param res   An array with Driver resources, all together are called bus
431 *              resources.
432 */
433extern void drvmgr_bus_res_add(struct drvmgr_bus *bus,
434                                        struct drvmgr_bus_res *bres);
435
436/*! Find all the resource keys for a device among all driver resources on a
437 *  bus. Typically used by a device driver to get configuration options.
438 *
439 * \param dev   Device to find resources for
440 * \param key   Location where the pointer to the driver resource array (drvmgr_drv_res->keys) is stored.
441 */
442extern int drvmgr_keys_get(struct drvmgr_dev *dev, struct drvmgr_key **keys);
443
444/*! Return the one key that matches key name from a driver keys array. The keys
445 *  can be obtained using drvmgr_keys_get().
446 *
447 * \param keys       An array of keys ended with DRVMGR_KEY_EMPTY to search among.
448 * \param key_name   Name of key to search for among the keys.
449 */
450extern struct drvmgr_key *drvmgr_key_get(struct drvmgr_key *keys, char *key_name);
451
452/*! Extract key value from the key in the keys array matching name and type.
453 *
454 *  This function calls drvmgr_keys_get to get the key requested (from key
455 *  name), then determines if the type is correct. A pointer to the key value
456 *  is returned.
457 *
458 *  \param keys       An array of keys ended with DRVMGR_KEY_EMPTY to search among.
459 *  \param key_name   Name of key to search for among the keys.
460 *  \param key_type   Data Type of value. INTEGER, ADDRESS, STRING.
461 *  \return           Returns NULL if no value found matching Key Name and Key
462 *                    Type.
463 */
464extern union drvmgr_key_value *drvmgr_key_val_get(
465        struct drvmgr_key *keys,
466        char *key_name,
467        enum drvmgr_kt key_type);
468
469/*! Get key value from the bus resources matching [device, key name, key type]
470 *  if no matching key is found NULL is returned.
471 *
472 * This is typically used by device drivers to find a particular device
473 * resource.
474 *
475 * \param dev         The device to search resource for.
476 * \param key_name    The key name to search for
477 * \param key_type    The key type expected.
478 * \return            Returns NULL if no value found matching Key Name and
479 *                    Key Type was found for device.
480 */
481extern union drvmgr_key_value *drvmgr_dev_key_get(
482        struct drvmgr_dev *dev,
483        char *key_name,
484        enum drvmgr_kt key_type);
485
486/*** DRIVER INTERACE USED TO REQUEST INFORMATION/SERVICES FROM BUS DRIVER ***/
487
488/*! Get parent bus */
489RTEMS_INLINE_ROUTINE struct drvmgr_bus *drvmgr_get_parent(
490        struct drvmgr_dev *dev)
491{
492        if (dev)
493                return dev->parent;
494        else
495                return NULL;
496}
497
498/*! Get Driver of device */
499RTEMS_INLINE_ROUTINE struct drvmgr_drv *drvmgr_get_drv(struct drvmgr_dev *dev)
500{
501        if (dev)
502                return dev->drv;
503        else
504                return NULL;
505}
506
507/*! Calls func() for every device found in the device tree, regardless of
508 * device state or if a driver is assigned. With the options argument the user
509 * can decide to do either a depth-first or a breadth-first search.
510 *
511 * If the function func() returns a non-zero value then for_each_dev will
512 * return imediatly with the same return value as func() returned.
513 *
514 * \param func       Function called on each device
515 * \param arg        Custom function argument
516 * \param options    Search Options, see DRVMGR_FED_*
517 *
518 */
519#define DRVMGR_FED_BF 1         /* Breadth-first search */
520#define DRVMGR_FED_DF 0         /* Depth first search */
521extern int drvmgr_for_each_dev(
522        int (*func)(struct drvmgr_dev *dev, void *arg),
523        void *arg,
524        int options);
525
526/*! Get Device pointer from Driver and Driver minor number
527 *
528 * \param drv         Driver the device is united with.
529 * \param minor       Driver minor number assigned to device.
530 * \param pdev        Location where the Device point will be stored.
531 * \return            Zero on success. -1 on failure, when device was not
532 *                    found in driver device list.
533 */
534extern int drvmgr_get_dev(
535        struct drvmgr_drv *drv,
536        int minor,
537        struct drvmgr_dev **pdev);
538
539/*! Get Bus frequency in Hertz. Frequency is stored into address of freq_hz.
540 *
541 * \param dev        The Device to get Bus frequency for.
542 * \param options    Bus-type specific options
543 * \param freq_hz    Location where Bus Frequency will be stored.
544 */
545extern int drvmgr_freq_get(
546        struct drvmgr_dev *dev,
547        int options,
548        unsigned int *freq_hz);
549
550/*! Return 0 if dev is not located on the root bus, 1 if on root bus */
551extern int drvmgr_on_rootbus(struct drvmgr_dev *dev);
552
553/*! Get device name prefix, this name can be used to register a unique name in
554 *  the bus->error filesystem or to get an idea where the device is located.
555 *
556 * \param dev         The Device to get the device Prefix for.
557 * \param dev_prefix  Location where the prefix will be stored.
558 */
559extern int drvmgr_get_dev_prefix(struct drvmgr_dev *dev, char *dev_prefix);
560
561/*! Register a shared interrupt handler. Since this service is shared among
562 *  interrupt drivers/handlers the handler[arg] must be installed before the
563 *  interrupt can be cleared or disabled. The handler is by default disabled
564 *  after registration.
565 *
566 *  \param index      Index is used to identify the IRQ number if hardware has
567 *                    multiple IRQ sources. Normally Index is set to 0 to
568 *                    indicated the first and only IRQ source.
569 *                    A negative index is interpreted as a absolute bus IRQ
570 *                    number.
571 *  \param isr        Interrupt Service Routine.
572 *  \param arg        Optional ISR argument.
573 */
574extern int drvmgr_interrupt_register(
575        struct drvmgr_dev *dev,
576        int index,
577        const char *info,
578        drvmgr_isr isr,
579        void *arg);
580
581/*! Unregister an interrupt handler. This also disables the interrupt before
582 *  unregistering the interrupt handler.
583 *  \param index      Index is used to identify the IRQ number if hardware has
584 *                    multiple IRQ sources. Normally Index is set to 0 to
585 *                    indicated the first and only IRQ source.
586 *                    A negative index is interpreted as a absolute bus IRQ
587 *                    number.
588 *  \param isr        Interrupt Service Routine, previously registered.
589 *  \param arg        Optional ISR argument, previously registered.
590 */
591extern int drvmgr_interrupt_unregister(
592        struct drvmgr_dev *dev,
593        int index,
594        drvmgr_isr isr,
595        void *arg);
596
597/*! Clear (ACK) pending interrupt
598 *
599 *  \param dev        Device to clear interrupt for.
600 *  \param index      Index is used to identify the IRQ number if hardware has multiple IRQ sources.
601 *                    Normally Index is set to 0 to indicated the first and only IRQ source.
602 *                    A negative index is interpreted as a absolute bus IRQ number.
603 *  \param isr        Interrupt Service Routine, previously registered.
604 *  \param arg        Optional ISR argument, previously registered.
605 */
606extern int drvmgr_interrupt_clear(
607        struct drvmgr_dev *dev,
608        int index);
609
610/*! Force unmasking/enableing an interrupt on the interrupt controller, this is not normally used,
611 *  if used the caller has masked/disabled the interrupt just before.
612 *
613 *  \param dev        Device to clear interrupt for.
614 *  \param index      Index is used to identify the IRQ number if hardware has multiple IRQ sources.
615 *                    Normally Index is set to 0 to indicated the first and only IRQ source.
616 *                    A negative index is interpreted as a absolute bus IRQ number.
617 *  \param isr        Interrupt Service Routine, previously registered.
618 *  \param arg        Optional ISR argument, previously registered.
619 */
620extern int drvmgr_interrupt_unmask(
621        struct drvmgr_dev *dev,
622        int index);
623
624/*! Force masking/disable an interrupt on the interrupt controller, this is not normally performed
625 *  since this will stop all other (shared) ISRs to be disabled until _unmask() is called.
626 *
627 *  \param dev        Device to mask interrupt for.
628 *  \param index      Index is used to identify the IRQ number if hardware has multiple IRQ sources.
629 *                    Normally Index is set to 0 to indicated the first and only IRQ source.
630 *                    A negative index is interpreted as a absolute bus IRQ number.
631 */
632extern int drvmgr_interrupt_mask(
633        struct drvmgr_dev *dev,
634        int index);
635
636/*! Force masking/disable an interrupt on the interrupt controller, this is not normally performed
637 *  since this will stop all other (shared) ISRs to be disabled until _unmask() is called.
638 *
639 *  \param dev        Device to mask interrupt for.
640 *  \param index      Index is used to identify the IRQ number if hardware has multiple IRQ sources.
641 *                    Normally Index is set to 0 to indicated the first and only IRQ source.
642 *                    A negative index is interpreted as a absolute bus IRQ number.
643 */
644#ifdef RTEMS_SMP
645extern int drvmgr_interrupt_set_affinity(
646        struct drvmgr_dev *dev,
647        int index,
648        const Processor_mask *cpus);
649#endif
650
651/*! drvmgr_translate() translation options */
652enum drvmgr_tr_opts {
653        /* Translate CPU RAM Address (input) to DMA unit accessible address
654         * (output), this is an upstreams translation in reverse order.
655         *
656         * Typical Usage:
657         * It is common to translate a CPU accessible RAM address to an
658         * address that DMA units can access over bridges.
659         */
660        CPUMEM_TO_DMA = 0x0,
661
662        /* Translate DMA Unit Accessible address mapped to CPU RAM (input) to
663         * CPU accessible address (output). This is an upstreams translation.
664         *
665         * Typical Usage (not often used):
666         * The DMA unit descriptors contain pointers to DMA buffers located at
667         * CPU RAM addresses that the DMA unit can access, the CPU processes
668         * the descriptors and want to access the data but a translation back
669         * to CPU address is required.
670         */
671        CPUMEM_FROM_DMA = 0x1,
672
673        /* Translate DMA Memory Address (input) to CPU accessible address
674         * (output), this is a downstreams translation in reverse order.
675         *
676         * Typical Usage:
677         * A PCI network card puts packets into its memory not doing DMA over
678         * PCI, in order for the CPU to access them the PCI address must be
679         * translated.
680         */
681        DMAMEM_TO_CPU = 0x2,
682
683        /* Translate CPU accessible address (input) mapped to DMA Memory Address
684         * to DMA Unit accessible address (output). This is a downstreams
685         * translation.
686         */
687        DMAMEM_FROM_CPU = 0x3,
688};
689#define DRVMGR_TR_REVERSE 0x1   /* do reverse translation direction order */
690#define DRVMGR_TR_PATH 0x2      /* 0x0=down-stream 0x2=up-stream address path */
691 
692/*! Translate an address on one bus to an address on another bus.
693 *
694 *  The device determines source or destination bus, the root bus is always
695 *  the other bus. It is assumed that the CPU is located on the root bus or
696 *  that it can access it without address translation (mapped 1:1). The CPU
697 *  is thus assumed to be located on level 0 top most in the bus hierarchy.
698 *
699 *  If no map is present in the bus driver src_address is translated 1:1
700 *  (just copied).
701 *
702 *  Addresses are typically converted up-streams from the DMA unit towards the
703 *  CPU (DMAMEM_TO_CPU) or down-streams towards DMA hardware from the CPU
704 *  (CPUMEM_TO_DMA) over one or multiple bridges depending on bus architecture.
705 *  See 'enum drvmgr_tr_opts' for other translation direction options.
706 *  For example:
707 *  Two common operations is to translate a CPU accessible RAM address to an
708 *  address that DMA units can access (dev=DMA-unit, CPUMEM_TO_DMA,
709 *  src_address=CPU-RAM-ADR) and to translate an address of a PCI resource for
710 *  example RAM mapped into a PCI BAR to an CPU accessible address
711 *  (dev=PCI-device, DMAMEM_TO_CPU, src_address=PCI-BAR-ADR).
712 *
713 *  Source address is translated and the result is put into *dst_address, if
714 *  the address is not accessible on the other bus -1 is returned.
715 *
716 *  \param dev             Device to translate addresses for
717 *  \param options         Tanslation direction options, see enum drvmgr_tr_opts
718 *  \param src_address     Address to translate
719 *  \param dst_address     Location where translated address is stored
720 *
721 *  Returns 0 if unable to translate. The remaining length from the given
722 *  address of the map is returned on success, for example if a map starts
723 *  at 0x40000000 of size 0x100000 the result will be 0x40000 if the address
724 *  was translated into 0x400C0000.
725 *  If dev is on root-bus no translation is performed 0xffffffff is returned
726 *  and src_address is stored in *dst_address.
727 */
728extern unsigned int drvmgr_translate(
729        struct drvmgr_dev *dev,
730        unsigned int options,
731        void *src_address,
732        void **dst_address);
733
734/* Translate addresses between buses, used internally to implement
735 * drvmgr_translate. Function is not limited to translate from/to root bus
736 * where CPU is resident, however buses must be on a straight path relative
737 * to each other (parent of parent of parent and so on).
738 *
739 * \param from         src_address is given for this bus
740 * \param to           src_address is translated to this bus
741 * \param reverse      Selects translation method, if map entries are used in
742 *                     the reverse order (map_up->to is used as map_up->from)
743 * \param src_address  Address to be translated
744 * \param dst_address  Translated address is stored here on success (return=0)
745 *
746 *  Returns 0 if unable to translate. The remaining length from the given
747 *  address of the map is returned on success and the result is stored into
748 *  *dst_address. For example if a map starts at 0x40000000 of size 0x100000
749 *  the result will be 0x40000 if the address was translated into 0x400C0000.
750 *  If dev is on root-bus no translation is performed 0xffffffff is returned.
751 *  and src_address is stored in *dst_address.
752 */
753extern unsigned int drvmgr_translate_bus(
754        struct drvmgr_bus *from,
755        struct drvmgr_bus *to,
756        int reverse,
757        void *src_address,
758        void **dst_address);
759
760/* Calls drvmgr_translate() to translate an address range and checks the result,
761 * a printout is generated if the check fails. All parameters are passed on to
762 * drvmgr_translate() except for size, see paramters of drvmgr_translate().
763 *
764 * If size=0 only the starting address is not checked.
765 *
766 * If mapping failes a non-zero result is returned.
767 */
768extern int drvmgr_translate_check(
769        struct drvmgr_dev *dev,
770        unsigned int options,
771        void *src_address,
772        void **dst_address,
773        unsigned int size);
774
775/*! Get function pointer from Device Driver or Bus Driver.
776 *
777 *  Returns 0 if function is available
778 */
779extern int drvmgr_func_get(void *obj, int funcid, void **func);
780
781/*! Lookup function and call it directly with the four optional arguments */
782extern int drvmgr_func_call(void *obj, int funcid, void *a, void *b, void *c, void *d);
783
784/* Builds a Function ID.
785 *
786 * Used to request optional functions by a bus or device driver
787 */
788#define DRVMGR_FUNCID(major, minor) ((((major) & 0xfff) << 20) | ((minor) & 0xfffff))
789#define DRVMGR_FUNCID_NONE 0
790#define DRVMGR_FUNCID_END DRVMGR_FUNCID(DRVMGR_FUNCID_NONE, 0)
791
792/* Major Function ID. Most significant 12-bits. */
793enum {
794        FUNCID_NONE             = 0x000,
795        FUNCID_RW               = 0x001, /* Read/Write functions */
796};
797
798/* Select Sub-Function Read/Write function by ID */
799#define RW_SIZE_1   0x00001    /* Access Size */
800#define RW_SIZE_2   0x00002
801#define RW_SIZE_4   0x00004
802#define RW_SIZE_8   0x00008
803#define RW_SIZE_ANY 0x00000
804#define RW_SIZE(id) ((unsigned int)(id) & 0xf)
805
806#define RW_DIR_ANY  0x00000   /* Access Direction */
807#define RW_READ     0x00000   /* Read */
808#define RW_WRITE    0x00010   /* Write */
809#define RW_SET      0x00020   /* Write with same value (memset) */
810#define RW_DIR(id)  (((unsigned int)(id) >> 4) & 0x3)
811
812#define RW_RAW      0x00000  /* Raw access - no swapping (machine default) */
813#define RW_LITTLE   0x00040  /* Little Endian */
814#define RW_BIG      0x00080  /* Big Endian */
815#define RW_ENDIAN(id) (((unsigned int)(id) >> 6) & 0x3)
816
817#define RW_TYPE_ANY 0x00000  /* Access type */
818#define RW_REG      0x00100
819#define RW_MEM      0x00200
820#define RW_MEMREG   0x00300
821#define RW_CFG      0x00400
822#define RW_TYPE(id) (((unsigned int)(id) >> 8) & 0xf)
823
824#define RW_ARG      0x01000 /* Optional Argument */
825#define RW_ERR      0x02000 /* Optional Error Handler */
826
827/* Build a Read/Write function ID */
828#define DRVMGR_RWFUNC(minor) DRVMGR_FUNCID(FUNCID_RW, minor)
829
830/* Argument to Read/Write functions, the "void *arg" pointer is returned by
831 * RW_ARG. If NULL is returned no argument is needed.
832 */
833struct drvmgr_rw_arg {
834        void *arg;
835        struct drvmgr_dev *dev;
836};
837
838/* Standard Read/Write function types */
839typedef uint8_t (*drvmgr_r8)(uint8_t *srcadr);
840typedef uint16_t (*drvmgr_r16)(uint16_t *srcadr);
841typedef uint32_t (*drvmgr_r32)(uint32_t *srcadr);
842typedef uint64_t (*drvmgr_r64)(uint64_t *srcadr);
843typedef void (*drvmgr_w8)(uint8_t *dstadr, uint8_t data);
844typedef void (*drvmgr_w16)(uint16_t *dstadr, uint16_t data);
845typedef void (*drvmgr_w32)(uint32_t *dstadr, uint32_t data);
846typedef void (*drvmgr_w64)(uint64_t *dstadr, uint64_t data);
847/* READ/COPY a memory area located on bus into CPU memory.
848 * From 'src' (remote) to the destination 'dest' (local), n=number of bytes
849 */
850typedef int (*drvmgr_rmem)(void *dest, const void *src, int n);
851/* WRITE/COPY a user buffer located in CPU memory to a location on the bus.
852 * From 'src' (local) to the destination 'dest' (remote), n=number of bytes
853 */
854typedef int (*drvmgr_wmem)(void *dest, const void *src, int n);
855/* Set a memory area to the byte value given in c, see LIBC memset(). Memset is
856 * implemented by calling wmem() multiple times with a "large" buffer.
857 */
858typedef int (*drvmgr_memset)(void *dstadr, int c, size_t n);
859
860/* Read/Write function types with additional argument */
861typedef uint8_t (*drvmgr_r8_arg)(uint8_t *srcadr, void *a);
862typedef uint16_t (*drvmgr_r16_arg)(uint16_t *srcadr, void *a);
863typedef uint32_t (*drvmgr_r32_arg)(uint32_t *srcadr, void *a);
864typedef uint64_t (*drvmgr_r64_arg)(uint64_t *srcadr, void *a);
865typedef void (*drvmgr_w8_arg)(uint8_t *dstadr, uint8_t data, void *a);
866typedef void (*drvmgr_w16_arg)(uint16_t *dstadr, uint16_t data, void *a);
867typedef void (*drvmgr_w32_arg)(uint32_t *dstadr, uint32_t data, void *a);
868typedef void (*drvmgr_w64_arg)(uint64_t *dstadr, uint64_t data, void *a);
869typedef int (*drvmgr_rmem_arg)(void *dest, const void *src, int n, void *a);
870typedef int (*drvmgr_wmem_arg)(void *dest, const void *src, int n, void *a);
871typedef int (*drvmgr_memset_arg)(void *dstadr, int c, size_t n, void *a);
872
873/* Report an error to the parent bus of the device */
874typedef void (*drvmgr_rw_err)(struct drvmgr_rw_arg *a, struct drvmgr_bus *bus,
875                                int funcid, void *adr);
876
877/* Helper function for buses that implement the memset() over wmem() */
878extern void drvmgr_rw_memset(
879        void *dstadr,
880        int c,
881        size_t n,
882        void *a,
883        drvmgr_wmem_arg wmem
884        );
885
886/*** PRINT INFORMATION ABOUT DRIVER MANAGER ***/
887
888/*! Calls func() for every device found matching the search requirements of
889 * set_mask and clr_mask. Each bit set in set_mask must be set in the
890 * device state bit mask (dev->state), and Each bit in the clr_mask must
891 * be cleared in the device state bit mask (dev->state). There are three
892 * special cases:
893 *
894 * 1. If state_set_mask and state_clr_mask are zero the state bits are
895 *    ignored and all cores are treated as a match.
896 *
897 * 2. If state_set_mask is zero the function func will not be called due to
898 *    a bit being set in the state mask.
899 *
900 * 3. If state_clr_mask is zero the function func will not be called due to
901 *    a bit being cleared in the state mask.
902 *
903 * If the function func() returns a non-zero value then for_each_dev will
904 * return imediatly with the same return value as func() returned.
905 *
906 * \param devlist            The list to iterate though searching for devices.
907 * \param state_set_mask     Defines the bits that must be set in dev->state
908 * \param state_clr_mask     Defines the bits that must be cleared in dev->state
909 * \param func               Function called on each
910 *
911 */
912extern int drvmgr_for_each_listdev(
913        struct drvmgr_list *devlist,
914        unsigned int state_set_mask,
915        unsigned int state_clr_mask,
916        int (*func)(struct drvmgr_dev *dev, void *arg),
917        void *arg);
918
919/* Print all devices */
920#define PRINT_DEVS_FAILED       0x01    /* Failed during initialization */
921#define PRINT_DEVS_ASSIGNED     0x02    /* Driver assigned */
922#define PRINT_DEVS_UNASSIGNED   0x04    /* Driver not assigned */
923#define PRINT_DEVS_IGNORED      0x08    /* Device ignored on user's request */
924#define PRINT_DEVS_ALL          (PRINT_DEVS_FAILED | \
925                                PRINT_DEVS_ASSIGNED | \
926                                PRINT_DEVS_UNASSIGNED |\
927                                PRINT_DEVS_IGNORED)
928
929/*! Print number of devices, buses and drivers */
930extern void drvmgr_summary(void);
931
932/*! Print devices with certain condictions met according to 'options' */
933extern void drvmgr_print_devs(unsigned int options);
934
935/*! Print device/bus topology */
936extern void drvmgr_print_topo(void);
937
938/*! Print the memory usage
939 * Only accounts for data structures. Not for the text size.
940 */
941extern void drvmgr_print_mem(void);
942
943#define OPTION_DEV_GENINFO   0x00000001
944#define OPTION_DEV_BUSINFO   0x00000002
945#define OPTION_DEV_DRVINFO   0x00000004
946#define OPTION_DRV_DEVS      0x00000100
947#define OPTION_BUS_DEVS      0x00010000
948#define OPTION_RECURSIVE     0x01000000
949#define OPTION_INFO_ALL      0xffffffff
950
951/*! Print information about a driver manager object (device, driver, bus) */
952extern void drvmgr_info(void *id, unsigned int options);
953
954/*! Get information about a device */
955extern void drvmgr_info_dev(struct drvmgr_dev *dev, unsigned int options);
956
957/*! Get information about a bus */
958extern void drvmgr_info_bus(struct drvmgr_bus *bus, unsigned int options);
959
960/*! Get information about a driver */
961extern void drvmgr_info_drv(struct drvmgr_drv *drv, unsigned int options);
962
963/*! Get information about all devices on a bus */
964extern void drvmgr_info_devs_on_bus(struct drvmgr_bus *bus, unsigned int options);
965
966/*! Get information about all devices in the system (on all buses) */
967extern void drvmgr_info_devs(unsigned int options);
968
969/*! Get information about all drivers in the system */
970extern void drvmgr_info_drvs(unsigned int options);
971
972/*! Get information about all buses in the system */
973extern void drvmgr_info_buses(unsigned int options);
974
975/*! Get Driver by Driver ID */
976extern struct drvmgr_drv *drvmgr_drv_by_id(uint64_t id);
977
978/*! Get Driver by Driver Name */
979extern struct drvmgr_drv *drvmgr_drv_by_name(const char *name);
980
981/*! Get Device by Device Name */
982extern struct drvmgr_dev *drvmgr_dev_by_name(const char *name);
983
984#ifdef __cplusplus
985}
986#endif
987
988#endif
Note: See TracBrowser for help on using the repository browser.