drvmgr.h

Go to the documentation of this file.

/* SPDX-License-Identifier: BSD-2-Clause */

 
/*
 * COPYRIGHT (c) 2009 Cobham Gaisler AB.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
 
#ifndef _DRIVER_MANAGER_H_
#define _DRIVER_MANAGER_H_
 
#include <rtems.h>
#include <drvmgr/drvmgr_list.h>
#include <stdint.h>
#include <rtems/score/basedefs.h>
#include <rtems/score/smpimpl.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*** Configure Driver manager ***/
 
/* Define the number of initialization levels of device drivers */
#define DRVMGR_LEVEL_MAX 4
 
/* Default to use semahpores for protection. Initialization works without
 * locks and after initialization too if devices are not removed.
 */
#ifndef DRVMGR_USE_LOCKS
#define DRVMGR_USE_LOCKS 1
#endif
 
struct drvmgr_dev;  /* Device */
struct drvmgr_bus;  /* Bus */
struct drvmgr_drv;  /* Driver */
 
/*** List Interface shortcuts ***/
#define BUS_LIST_HEAD(list) LIST_HEAD(list, struct drvmgr_bus)
#define BUS_LIST_TAIL(list) LIST_TAIL(list, struct drvmgr_bus)
#define DEV_LIST_HEAD(list) LIST_HEAD(list, struct drvmgr_dev)
#define DEV_LIST_TAIL(list) LIST_TAIL(list, struct drvmgr_dev)
#define DRV_LIST_HEAD(list) LIST_HEAD(list, struct drvmgr_drv)
#define DRV_LIST_TAIL(list) LIST_TAIL(list, struct drvmgr_drv)
 
/*** Bus indentification ***/
#define DRVMGR_BUS_TYPE_NONE 0      /* Not a valid bus */
#define DRVMGR_BUS_TYPE_ROOT 1      /* Hard coded bus */
#define DRVMGR_BUS_TYPE_PCI 2       /* PCI bus */
#define DRVMGR_BUS_TYPE_AMBAPP 3    /* AMBA Plug & Play bus */
#define DRVMGR_BUS_TYPE_LEON2_AMBA 4    /* LEON2 hardcoded bus */
#define DRVMGR_BUS_TYPE_AMBAPP_DIST 5   /* Distibuted AMBA Plug & Play bus accessed using a communication interface */
#define DRVMGR_BUS_TYPE_SPW_RMAP 6  /* SpaceWire Network bus */
#define DRVMGR_BUS_TYPE_AMBAPP_RMAP 7   /* SpaceWire RMAP accessed AMBA Plug & Play bus */
 
enum {
    DRVMGR_OBJ_NONE = 0,
    DRVMGR_OBJ_DRV = 1,
    DRVMGR_OBJ_BUS = 2,
    DRVMGR_OBJ_DEV = 3,
};
 
/*** Driver indentification ***
 *
 * 64-bit identification integer definition
 *  * Bus ID 8-bit [7..0]
 *  * Reserved 8-bit field [63..56]
 *  * Device ID specific for bus type 48-bit [55..8]  (Different buses have
 *    different unique identifications for hardware/driver.)
 *
 * ID Rules
 *  * A root bus driver must always have device ID set to 0. There can only by
 *    one root bus driver for a certain bus type.
 *  * A Driver ID must identify a unique hardware core
 *
 */
 
/* Bus ID Mask */
#define DRIVER_ID_BUS_MASK 0x00000000000000FFULL
 
/* Reserved Mask for future use */
#define DRIVER_ID_RSV_MASK 0xFF00000000000000ULL
 
/* Reserved Mask for future use */
#define DRIVER_ID_DEV_MASK 0x00FFFFFFFFFFFF00ULL
 
/* Set Bus ID Mask. */
#define DRIVER_ID(busid, devid) ((unsigned long long) \
    ((((unsigned long long)(devid) << 8) & DRIVER_ID_DEV_MASK) | \
     ((unsigned long long)(busid) & DRIVER_ID_BUS_MASK)))
 
/* Get IDs */
#define DRIVER_BUSID_GET(id)    ((unsigned long long)(id) & DRIVER_ID_BUS_MASK)
#define DRIVER_DEVID_GET(id)    (((unsigned long long)(id) & DRIVER_ID_DEV_MASK) >> 8)
 
#define DRIVER_ROOTBUS_ID(bus_type) DRIVER_ID(bus_type, 0)
 
/*** Root Bus drivers ***/
 
/* Generic Hard coded Root bus: Driver ID */
#define DRIVER_ROOT_ID      DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_ROOT)
 
/* PCI Plug & Play bus: Driver ID */
#define DRIVER_PCIBUS_ID    DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_PCI)
 
/* AMBA Plug & Play bus: Driver ID */
#define DRIVER_GRLIB_AMBAPP_ID  DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_AMBAPP)
 
/* AMBA Hard coded bus: Driver ID */
#define DRIVER_LEON2_AMBA_ID    DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_LEON2_AMBA)
 
/* Distributed AMBA Plug & Play bus: Driver ID */
#define DRIVER_AMBAPP_DIST_ID   DRIVER_ROOTBUS_ID(DRVMGR_BUS_TYPE_AMBAPP_DIST)

struct drvmgr_bus_params {
    char        *dev_prefix;        
};
 
/* Interrupt Service Routine (ISR) */
typedef void (*drvmgr_isr)(void *arg);

struct drvmgr_bus_ops {
    /* Functions used internally within driver manager */
    int (*init[DRVMGR_LEVEL_MAX])(struct drvmgr_bus *);
    int (*remove)(struct drvmgr_bus *);
    int (*unite)(struct drvmgr_drv *, struct drvmgr_dev *); 
 
    /* Functions called indirectly from drivers */
    int (*int_register)(struct drvmgr_dev *, int index, const char *info, drvmgr_isr isr, void *arg);
    int (*int_unregister)(struct drvmgr_dev *, int index, drvmgr_isr isr, void *arg);
    int (*int_clear)(struct drvmgr_dev *, int index);
    int (*int_mask)(struct drvmgr_dev *, int index);
    int (*int_unmask)(struct drvmgr_dev *, int index);
#ifdef RTEMS_SMP
    int (*int_set_affinity)(struct drvmgr_dev *, int index,
                    const Processor_mask *cpus);
#endif
 
    /* Get Parameters */
    int (*get_params)(struct drvmgr_dev *, struct drvmgr_bus_params *);
    /* Get Frequency of Bus */
    int (*get_freq)(struct drvmgr_dev*, int, unsigned int*);
    void    (*get_info_dev)(struct drvmgr_dev *,
                void (*print)(void *p, char *str), void *p);
};
#define BUS_OPS_NUM (sizeof(struct drvmgr_bus_ops)/sizeof(void (*)(void)))
 
struct drvmgr_func {
    int funcid;
    void *func;
};
#define DRVMGR_FUNC(_ID_, _FUNC_) {(int)(_ID_), (void *)(_FUNC_)}
#define DRVMGR_FUNC_END {0, NULL}
 
/*** Resource definitions ***
 *
 * Overview of structures:
 *  All bus resources entries (_bus_res) are linked together per bus
 *  (bus_info->reslist). One bus resource entry has a pointer to an array of
 *  driver resources (_drv_res). One driver resouces is made out of an array
 *  of keys (drvmgr_key). All keys belongs to the same driver and harwdare
 *  device. Each key has a Name, Type ID and Data interpreted differently
 *  depending on the Type ID (union drvmgr_key_value).
 *
 */
 
/* Key Data Types */
enum drvmgr_kt {
    DRVMGR_KT_ANY = -1,
    DRVMGR_KT_NONE = 0,
    DRVMGR_KT_INT = 1,
    DRVMGR_KT_STRING = 2,
    DRVMGR_KT_POINTER = 3,
};
 
#define DRVMGR_KEY_EMPTY    {NULL, DRVMGR_KT_NONE, {0}}
#define DRVMGR_RES_EMPTY    {0, 0, NULL}
#define MMAP_EMPTY  {0, 0, 0}

union drvmgr_key_value {
    unsigned int        i;  
    char            *str;   
    void            *ptr;   
};
 
/* One key. One Value. Holding information relevant to the driver. */
struct drvmgr_key {
    char            *key_name;  /* Name of key */
    enum drvmgr_kt      key_type;   /* How to interpret key_value */
    union drvmgr_key_value  key_value;  /* The value or pointer to value */
};

struct drvmgr_drv_res {
    uint64_t        drv_id;     
    int         minor_bus;  
    struct drvmgr_key   *keys;      
};

struct drvmgr_bus_res {
    struct drvmgr_bus_res   *next;      
    struct drvmgr_drv_res   resource[]; 
};

struct drvmgr_map_entry {
    char        *name;      
    unsigned int    size;       
    char        *from_adr;  
    char        *to_adr;    
};
#define DRVMGR_TRANSLATE_ONE2ONE    NULL
#define DRVMGR_TRANSLATE_NO_BRIDGE  ((void *)1)  /* No bridge, error */

struct drvmgr_bus {
    int         obj_type;   
    unsigned char       bus_type;   
    unsigned char       depth;      
    struct drvmgr_bus   *next;      
    struct drvmgr_dev   *dev;       
    void            *priv;      
    struct drvmgr_dev   *children;  
    struct drvmgr_bus_ops   *ops;       
    struct drvmgr_func  *funcs;     
    int         dev_cnt;    
    struct drvmgr_bus_res   *reslist;   
    struct drvmgr_map_entry *maps_up;   
    struct drvmgr_map_entry *maps_down; 
 
    /* Bus status */
    int         level;      
    int         state;      
    int         error;      
};
 
/* States of a bus */
#define BUS_STATE_INIT_FAILED   0x00000001  /* Initialization Failed */
#define BUS_STATE_LIST_INACTIVE 0x00001000  /* In inactive bus list */
#define BUS_STATE_DEPEND_FAILED 0x00000004  /* Device init failed */
 
/* States of a device */
#define DEV_STATE_INIT_FAILED   0x00000001  /* Initialization Failed */
#define DEV_STATE_INIT_DONE 0x00000002  /* All init levels completed */
#define DEV_STATE_DEPEND_FAILED 0x00000004  /* Parent Bus init failed */
#define DEV_STATE_UNITED    0x00000100  /* Device United with Device Driver */
#define DEV_STATE_REMOVED   0x00000200  /* Device has been removed (unregistered) */
#define DEV_STATE_IGNORED   0x00000400  /* Device was ignored according to user's request, the device
                         * was never reported to it's driver (as expected).
                         */
#define DEV_STATE_LIST_INACTIVE 0x00001000  /* In inactive device list */

struct drvmgr_dev {
    int         obj_type;   
    struct drvmgr_dev   *next;      
    struct drvmgr_dev   *next_in_bus;   
    struct drvmgr_dev   *next_in_drv;   
 
    struct drvmgr_drv   *drv;       
    struct drvmgr_bus   *parent;    
    short           minor_drv;  
    short           minor_bus;  
    char            *name;      
    void            *priv;      
    void            *businfo;   
    struct drvmgr_bus   *bus;       
 
    /* Device Status */
    unsigned int        state;      
    int         level;      
    int         error;      
};

struct drvmgr_drv_ops {
    int (*init[DRVMGR_LEVEL_MAX])(struct drvmgr_dev *); 
    int (*remove)(struct drvmgr_dev *); 
    int (*info)(struct drvmgr_dev *, void (*print)(void *p, char *str), void *p, int, char *argv[]);
};
#define DRVMGR_OPS_NUM(x) (sizeof(x)/sizeof(void (*)(void)))

struct drvmgr_drv {
    int         obj_type;   
    struct drvmgr_drv   *next;      
    struct drvmgr_dev   *dev;       
 
    uint64_t        drv_id;     
    char            *name;      
    int         bus_type;   
    struct drvmgr_drv_ops   *ops;       
    struct drvmgr_func  *funcs;     
    unsigned int        dev_cnt;    
    unsigned int        dev_priv_size;  
};

typedef void (*drvmgr_drv_reg_func)(void);
 
/*** DRIVER | DEVICE | BUS FUNCTIONS ***/
 
/* Return Codes */
enum {
    DRVMGR_OK = 0,      /* Sucess */
    DRVMGR_NOMEM = 1,   /* Memory allocation error */
    DRVMGR_EIO = 2,     /* I/O error */
    DRVMGR_EINVAL = 3,  /* Invalid parameter */
    DRVMGR_ENOSYS = 4,
    DRVMGR_TIMEDOUT = 5,    /* Operation timeout error */
    DRVMGR_EBUSY = 6,
    DRVMGR_ENORES = 7,  /* Not enough resources */
    DRVMGR_FAIL = -1    /* Unspecified failure */
};

extern void _DRV_Manager_initialization(void);

extern void _DRV_Manager_init_level(int level);

extern int drvmgr_init(void);
 
/* Take registered buses and devices into the correct init level,
 * this function is called from _init_level() so normally
 * we don't need to call it directly.
 */
extern void drvmgr_init_update(void);

extern int drvmgr_root_drv_register(struct drvmgr_drv *drv);

extern int drvmgr_drv_register(struct drvmgr_drv *drv);

extern int drvmgr_dev_register(struct drvmgr_dev *dev);

extern int drvmgr_dev_unregister(struct drvmgr_dev *dev);

extern int drvmgr_bus_register(struct drvmgr_bus *bus);

extern int drvmgr_bus_unregister(struct drvmgr_bus *bus);

extern int drvmgr_children_unregister(struct drvmgr_bus *bus);
 
/* Separate a device from the driver it has been united with */
extern int drvmgr_dev_drv_separate(struct drvmgr_dev *dev);

extern int drvmgr_alloc_dev(struct drvmgr_dev **pdev, int extra);

extern int drvmgr_alloc_bus(struct drvmgr_bus **pbus, int extra);
 
/*** DRIVER RESOURCE FUNCTIONS ***/

extern void drvmgr_bus_res_add(struct drvmgr_bus *bus,
                    struct drvmgr_bus_res *bres);

extern int drvmgr_keys_get(struct drvmgr_dev *dev, struct drvmgr_key **keys);

extern struct drvmgr_key *drvmgr_key_get(struct drvmgr_key *keys, char *key_name);

extern union drvmgr_key_value *drvmgr_key_val_get(
    struct drvmgr_key *keys,
    char *key_name,
    enum drvmgr_kt key_type);

extern union drvmgr_key_value *drvmgr_dev_key_get(
    struct drvmgr_dev *dev,
    char *key_name,
    enum drvmgr_kt key_type);
 
/*** DRIVER INTERACE USED TO REQUEST INFORMATION/SERVICES FROM BUS DRIVER ***/

static inline struct drvmgr_bus *drvmgr_get_parent(
    struct drvmgr_dev *dev)
{
    if (dev)
        return dev->parent;
    else
        return NULL;
}

static inline struct drvmgr_drv *drvmgr_get_drv(struct drvmgr_dev *dev)
{
    if (dev)
        return dev->drv;
    else
        return NULL;
}

#define DRVMGR_FED_BF 1     /* Breadth-first search */
#define DRVMGR_FED_DF 0     /* Depth first search */
extern intptr_t drvmgr_for_each_dev(
    intptr_t (*func)(struct drvmgr_dev *dev, void *arg),
    void *arg,
    int options);

extern int drvmgr_get_dev(
    struct drvmgr_drv *drv,
    int minor,
    struct drvmgr_dev **pdev);

extern int drvmgr_freq_get(
    struct drvmgr_dev *dev,
    int options,
    unsigned int *freq_hz);

extern int drvmgr_on_rootbus(struct drvmgr_dev *dev);

extern int drvmgr_get_dev_prefix(struct drvmgr_dev *dev, char *dev_prefix);

extern int drvmgr_interrupt_register(
    struct drvmgr_dev *dev,
    int index,
    const char *info,
    drvmgr_isr isr,
    void *arg);

extern int drvmgr_interrupt_unregister(
    struct drvmgr_dev *dev,
    int index,
    drvmgr_isr isr,
    void *arg);

extern int drvmgr_interrupt_clear(
    struct drvmgr_dev *dev,
    int index);

extern int drvmgr_interrupt_unmask(
    struct drvmgr_dev *dev,
    int index);

extern int drvmgr_interrupt_mask(
    struct drvmgr_dev *dev,
    int index);

#ifdef RTEMS_SMP
extern int drvmgr_interrupt_set_affinity(
    struct drvmgr_dev *dev,
    int index,
    const Processor_mask *cpus);
#endif

enum drvmgr_tr_opts {
    /* Translate CPU RAM Address (input) to DMA unit accessible address
     * (output), this is an upstreams translation in reverse order.
     *
     * Typical Usage:
     * It is common to translate a CPU accessible RAM address to an
     * address that DMA units can access over bridges.
     */
    CPUMEM_TO_DMA = 0x0,
 
    /* Translate DMA Unit Accessible address mapped to CPU RAM (input) to
     * CPU accessible address (output). This is an upstreams translation.
     *
     * Typical Usage (not often used):
     * The DMA unit descriptors contain pointers to DMA buffers located at
     * CPU RAM addresses that the DMA unit can access, the CPU processes
     * the descriptors and want to access the data but a translation back
     * to CPU address is required.
     */
    CPUMEM_FROM_DMA = 0x1,
 
    /* Translate DMA Memory Address (input) to CPU accessible address
     * (output), this is a downstreams translation in reverse order.
     *
     * Typical Usage:
     * A PCI network card puts packets into its memory not doing DMA over
     * PCI, in order for the CPU to access them the PCI address must be
     * translated.
     */
    DMAMEM_TO_CPU = 0x2,
 
    /* Translate CPU accessible address (input) mapped to DMA Memory Address
     * to DMA Unit accessible address (output). This is a downstreams
     * translation.
     */
    DMAMEM_FROM_CPU = 0x3,
};
#define DRVMGR_TR_REVERSE 0x1   /* do reverse translation direction order */
#define DRVMGR_TR_PATH 0x2  /* 0x0=down-stream 0x2=up-stream address path */
 
extern unsigned int drvmgr_translate(
    struct drvmgr_dev *dev,
    unsigned int options,
    void *src_address,
    void **dst_address);
 
/* Translate addresses between buses, used internally to implement
 * drvmgr_translate. Function is not limited to translate from/to root bus
 * where CPU is resident, however buses must be on a straight path relative
 * to each other (parent of parent of parent and so on).
 *
 * \param from         src_address is given for this bus
 * \param to           src_address is translated to this bus
 * \param reverse      Selects translation method, if map entries are used in
 *                     the reverse order (map_up->to is used as map_up->from)
 * \param src_address  Address to be translated
 * \param dst_address  Translated address is stored here on success (return=0)
 *
 *  Returns 0 if unable to translate. The remaining length from the given
 *  address of the map is returned on success and the result is stored into
 *  *dst_address. For example if a map starts at 0x40000000 of size 0x100000
 *  the result will be 0x40000 if the address was translated into 0x400C0000.
 *  If dev is on root-bus no translation is performed 0xffffffff is returned.
 *  and src_address is stored in *dst_address.
 */
extern unsigned int drvmgr_translate_bus(
    struct drvmgr_bus *from,
    struct drvmgr_bus *to,
    int reverse,
    void *src_address,
    void **dst_address);
 
/* Calls drvmgr_translate() to translate an address range and checks the result,
 * a printout is generated if the check fails. All parameters are passed on to
 * drvmgr_translate() except for size, see paramters of drvmgr_translate().
 *
 * If size=0 only the starting address is not checked.
 *
 * If mapping failes a non-zero result is returned.
 */
extern int drvmgr_translate_check(
    struct drvmgr_dev *dev,
    unsigned int options,
    void *src_address,
    void **dst_address,
    unsigned int size);

extern int drvmgr_func_get(void *obj, int funcid, void **func);

extern int drvmgr_func_call(void *obj, int funcid, void *a, void *b, void *c, void *d);
 
/* Builds a Function ID.
 *
 * Used to request optional functions by a bus or device driver
 */
#define DRVMGR_FUNCID(major, minor) ((((major) & 0xfff) << 20) | ((minor) & 0xfffff))
#define DRVMGR_FUNCID_NONE 0
#define DRVMGR_FUNCID_END DRVMGR_FUNCID(DRVMGR_FUNCID_NONE, 0)
 
/* Major Function ID. Most significant 12-bits. */
enum {
    FUNCID_NONE             = 0x000,
    FUNCID_RW               = 0x001, /* Read/Write functions */
};
 
/* Select Sub-Function Read/Write function by ID */
#define RW_SIZE_1   0x00001    /* Access Size */
#define RW_SIZE_2   0x00002
#define RW_SIZE_4   0x00004
#define RW_SIZE_8   0x00008
#define RW_SIZE_ANY 0x00000
#define RW_SIZE(id) ((unsigned int)(id) & 0xf)
 
#define RW_DIR_ANY  0x00000   /* Access Direction */
#define RW_READ     0x00000   /* Read */
#define RW_WRITE    0x00010   /* Write */
#define RW_SET      0x00020   /* Write with same value (memset) */
#define RW_DIR(id)  (((unsigned int)(id) >> 4) & 0x3)
 
#define RW_RAW      0x00000  /* Raw access - no swapping (machine default) */
#define RW_LITTLE   0x00040  /* Little Endian */
#define RW_BIG      0x00080  /* Big Endian */
#define RW_ENDIAN(id) (((unsigned int)(id) >> 6) & 0x3)
 
#define RW_TYPE_ANY 0x00000  /* Access type */
#define RW_REG      0x00100
#define RW_MEM      0x00200
#define RW_MEMREG   0x00300
#define RW_CFG      0x00400
#define RW_TYPE(id) (((unsigned int)(id) >> 8) & 0xf)
 
#define RW_ARG      0x01000 /* Optional Argument */
#define RW_ERR      0x02000 /* Optional Error Handler */
 
/* Build a Read/Write function ID */
#define DRVMGR_RWFUNC(minor) DRVMGR_FUNCID(FUNCID_RW, minor)
 
/* Argument to Read/Write functions, the "void *arg" pointer is returned by
 * RW_ARG. If NULL is returned no argument is needed.
 */
struct drvmgr_rw_arg {
    void *arg;
    struct drvmgr_dev *dev;
};
 
/* Standard Read/Write function types */
typedef uint8_t (*drvmgr_r8)(uint8_t *srcadr);
typedef uint16_t (*drvmgr_r16)(uint16_t *srcadr);
typedef uint32_t (*drvmgr_r32)(uint32_t *srcadr);
typedef uint64_t (*drvmgr_r64)(uint64_t *srcadr);
typedef void (*drvmgr_w8)(uint8_t *dstadr, uint8_t data);
typedef void (*drvmgr_w16)(uint16_t *dstadr, uint16_t data);
typedef void (*drvmgr_w32)(uint32_t *dstadr, uint32_t data);
typedef void (*drvmgr_w64)(uint64_t *dstadr, uint64_t data);
/* READ/COPY a memory area located on bus into CPU memory.
 * From 'src' (remote) to the destination 'dest' (local), n=number of bytes
 */
typedef int (*drvmgr_rmem)(void *dest, const void *src, int n);
/* WRITE/COPY a user buffer located in CPU memory to a location on the bus.
 * From 'src' (local) to the destination 'dest' (remote), n=number of bytes
 */
typedef int (*drvmgr_wmem)(void *dest, const void *src, int n);
/* Set a memory area to the byte value given in c, see LIBC memset(). Memset is
 * implemented by calling wmem() multiple times with a "large" buffer.
 */
typedef int (*drvmgr_memset)(void *dstadr, int c, size_t n);
 
/* Read/Write function types with additional argument */
typedef uint8_t (*drvmgr_r8_arg)(uint8_t *srcadr, void *a);
typedef uint16_t (*drvmgr_r16_arg)(uint16_t *srcadr, void *a);
typedef uint32_t (*drvmgr_r32_arg)(uint32_t *srcadr, void *a);
typedef uint64_t (*drvmgr_r64_arg)(uint64_t *srcadr, void *a);
typedef void (*drvmgr_w8_arg)(uint8_t *dstadr, uint8_t data, void *a);
typedef void (*drvmgr_w16_arg)(uint16_t *dstadr, uint16_t data, void *a);
typedef void (*drvmgr_w32_arg)(uint32_t *dstadr, uint32_t data, void *a);
typedef void (*drvmgr_w64_arg)(uint64_t *dstadr, uint64_t data, void *a);
typedef int (*drvmgr_rmem_arg)(void *dest, const void *src, int n, void *a);
typedef int (*drvmgr_wmem_arg)(void *dest, const void *src, int n, void *a);
typedef int (*drvmgr_memset_arg)(void *dstadr, int c, size_t n, void *a);
 
/* Report an error to the parent bus of the device */
typedef void (*drvmgr_rw_err)(struct drvmgr_rw_arg *a, struct drvmgr_bus *bus,
                int funcid, void *adr);
 
/* Helper function for buses that implement the memset() over wmem() */
extern void drvmgr_rw_memset(
    void *dstadr,
    int c,
    size_t n,
    void *a,
    drvmgr_wmem_arg wmem
    );
 
/*** PRINT INFORMATION ABOUT DRIVER MANAGER ***/

extern int drvmgr_for_each_listdev(
    struct drvmgr_list *devlist,
    unsigned int state_set_mask,
    unsigned int state_clr_mask,
    int (*func)(struct drvmgr_dev *dev, void *arg),
    void *arg);
 
/* Print all devices */
#define PRINT_DEVS_FAILED   0x01    /* Failed during initialization */
#define PRINT_DEVS_ASSIGNED 0x02    /* Driver assigned */
#define PRINT_DEVS_UNASSIGNED   0x04    /* Driver not assigned */
#define PRINT_DEVS_IGNORED  0x08    /* Device ignored on user's request */
#define PRINT_DEVS_ALL      (PRINT_DEVS_FAILED | \
                PRINT_DEVS_ASSIGNED | \
                PRINT_DEVS_UNASSIGNED |\
                PRINT_DEVS_IGNORED)

extern void drvmgr_summary(void);

extern void drvmgr_print_devs(unsigned int options);

extern void drvmgr_print_topo(void);

extern void drvmgr_print_mem(void);
 
#define OPTION_DEV_GENINFO   0x00000001
#define OPTION_DEV_BUSINFO   0x00000002
#define OPTION_DEV_DRVINFO   0x00000004
#define OPTION_DRV_DEVS      0x00000100
#define OPTION_BUS_DEVS      0x00010000
#define OPTION_RECURSIVE     0x01000000
#define OPTION_INFO_ALL      0xffffffff

extern void drvmgr_info(void *id, unsigned int options);

extern void drvmgr_info_dev(struct drvmgr_dev *dev, unsigned int options);

extern void drvmgr_info_bus(struct drvmgr_bus *bus, unsigned int options);

extern void drvmgr_info_drv(struct drvmgr_drv *drv, unsigned int options);

extern void drvmgr_info_devs_on_bus(struct drvmgr_bus *bus, unsigned int options);

extern void drvmgr_info_devs(unsigned int options);

extern void drvmgr_info_drvs(unsigned int options);

extern void drvmgr_info_buses(unsigned int options);

extern struct drvmgr_drv *drvmgr_drv_by_id(uint64_t id);

extern struct drvmgr_drv *drvmgr_drv_by_name(const char *name);

extern struct drvmgr_dev *drvmgr_dev_by_name(const char *name);
 
#ifdef __cplusplus
}
#endif
 
#endif