device/driver.h header reference
[Devices support library module]

The source code of this header can be browsed online.

Description  

Driver structures and driver API classes

Members  

Types  

Functions  

Constants  

Macros  

Members detail  

#define DEVICE_ACCESSOR_INIT  

This macro is declared in device/driver.h source file, line 591.

This macro initializes a struct device_accessor_s object to the null accessor.

#define DEVICE_HAS_OP(dev_accessor, op)  

This macro is declared in device/driver.h source file, line 583.

This macro tells whether device defines said function.

See also Device accessor.

#define DEVICE_OP(dev_accessor, op, ...)  

This macro is declared in device/driver.h source file, line 575.

This macro invokes the requested operation on a device accessor object. The function must be provided by the driver.

See also Device accessor.

#define DEVICE_PV(pvdata, device)  

This macro is declared in device/driver.h source file, line 435.

This macro is used to declare a driver private data local variable from dev

#define DEVICE_START_COUNT_INC  

This macro is declared in device/driver.h source file, line 764.

This macro specifies the value added to the device_s::start_count value when the device_start function is invoked.

#define DEV_CLEANUP(n)  

This macro is declared in device/driver.h source file, line 259.

See also dev_cleanup_t.

#define DEV_ENUM_ATA_ENTRY(_str)  

This macro is declared in device/driver.h source file, line 158.

Shortcut for creating an ATA entry in a static struct dev_enum_ident_s array.

Parameter list:

  • _str: the string to match from the device

#define DEV_ENUM_FDTNAME_ENTRY(_name)  

This macro is declared in device/driver.h source file, line 168.

Shortcut for creating a flat-device-tree entry in a static struct dev_enum_ident_s array.

Parameter list:

  • _name: The string to match from the device-tree

#define DEV_ENUM_GAISLER_ENTRY(_vendor, _device)  

This macro is declared in device/driver.h source file, line 179.

Shortcut for creating a Gaisler entry in a static struct dev_enum_ident_s array.

Parameter list:

  • _vendor: the vendor id to match, -1 for wildcard
  • _device: the device id to match, -1 for wildcard

#define DEV_ENUM_GENERIC_ENTRY(_vendor, _device, _rev_major, _rev_minor)  

This macro is declared in device/driver.h source file, line 192.

Shortcut for creating a Generic with vendor/device ids and version number in a static struct dev_enum_ident_s array.

Parameter list:

  • _vendor: the vendor id to match, -1 for wildcard
  • _device: the device id to match, -1 for wildcard
  • _rev_major: the device major revision, -1 for wildcard
  • _rev_minor: the minimum supported minor revision, -1 for wildcard

#define DEV_ENUM_ISA_ENTRY(_vendor)  

This macro is declared in device/driver.h source file, line 148.

Shortcut for creating an ISA entry in a static struct dev_enum_ident_s array.

Parameter list:

  • _vendor: the vendor id to match

#define DEV_ENUM_PCI_ENTRY(_vendor, _device, _class)  

This macro is declared in device/driver.h source file, line 137.

Shortcut for creating a PCI entry in a static struct dev_enum_ident_s array.

Parameter list:

  • _vendor: the vendor id to match, -1 for wildcard
  • _device: the device id to match, -1 for wildcard
  • _class: the class to match, -1 for wildcard

#define DEV_INIT(n)  

This macro is declared in device/driver.h source file, line 202.

See also dev_init_t.

#define DEV_USE(n)  

This macro is declared in device/driver.h source file, line 367.

See also dev_use_t.

#define DRIVER_DECLARE(symbol_, flags_, pretty_, prefix_, ...)  

This macro is declared in device/driver.h source file, line 440.

This macro declares a struct driver_s object. Implemented device classes must be specified as extra parameters.

#define DRIVER_DECLARE_CLEANUP(x)  

This macro is declared in device/driver.h source file, line 424.

Preprocessor condition: defined( CONFIG_DEVICE_CLEANUP )

#define DRIVER_DECLARE_CLEANUP(x)  

This macro is declared in device/driver.h source file, line 426.

Preprocessor condition: not defined( CONFIG_DEVICE_CLEANUP )

#define DRIVER_DECLARE_DESC(x)  

This macro is declared in device/driver.h source file, line 418.

Preprocessor condition: defined( CONFIG_DEVICE_DRIVER_DESC )

#define DRIVER_DECLARE_DESC(x)  

This macro is declared in device/driver.h source file, line 420.

Preprocessor condition: not defined( CONFIG_DEVICE_DRIVER_DESC )

#define DRIVER_PV(...)  

This macro is declared in device/driver.h source file, line 430.

This macro is used to declare a driver private data structure

#define DRIVER_REGISTER(driver_, ...)  

This macro is declared in device/driver.h source file, line 479.

This macro registers a struct driver_s object in the driver_registry_table table. This enables lookup and dynamic binding of the driver to a device.

When this macro is not used, the driver can't be used for enumerated devices. In this case, a pointer to the driver must be passed to the DEV_DECLARE_STATIC macro or to the device_bind_driver function.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: defined( CONFIG_DEVICE_DRIVER_REGISTRY )

#define DRIVER_REGISTER(driver_, ...)  

This macro is declared in device/driver.h source file, line 491.

Documentation from alternate declaration:

This macro registers a struct driver_s object in the driver_registry_table table. This enables lookup and dynamic binding of the driver to a device.

When this macro is not used, the driver can't be used for enumerated devices. In this case, a pointer to the driver must be passed to the DEV_DECLARE_STATIC macro or to the device_bind_driver function.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: not defined( CONFIG_DEVICE_DRIVER_REGISTRY )

#define DRIVER_REGISTRY_SECTION(x)  

This macro is declared in device/driver.h source file, line 465.

Preprocessor condition: defined( CONFIG_ARCH_EMU_DARWIN )

#define DRIVER_REGISTRY_SECTION(x)  

This macro is declared in device/driver.h source file, line 467.

Preprocessor condition: not defined( CONFIG_ARCH_EMU_DARWIN )

#define __DRIVER_H__  

This macro is declared in device/driver.h source file, line 29.

typedef error_t (dev_cleanup_t)(struct device_s *dev)   

This typedef is declared in device/driver.h source file, line 285.

This typedef is the device cleanup function type. This typedef tries to release all ressources allocated by the dev_init_t function.

This function will only be called these conditions are met:

This function is called with the device lock held. This typedef function must return -EBUSY if it is not possible to release the device yet.

This typedef function may also return -EAGAIN if cleanup has been initiated but requires completion of some asynchronous operations. The cleanup will complete when the device_async_cleanup_done function is called from a deferred kroutine. This requires definition of the CONFIG_DEVICE_INIT_ASYNC token.

This declaration involves expansion of the DEV_CLEANUP macro.

error_t dev_driver_notsup_fcn(void )  

This function function does nothing but returning -ENOTUP

struct dev_enum_ident_s  

This struct is declared in device/driver.h source file, line 98.

device structure identification informations. wildcard values are enum driver dependent

FieldDescription
enum dev_enum_type_e type;
union <anonymous> {
struct <anonymous> {
uint16_t vendor;
uint16_t device;
uint16_t rev_minor;
uint16_t rev_major;
} generic;
struct <anonymous> {
uint16_t vendor;
uint16_t device;
uint32_t class;
} pci;
struct <anonymous> {
uint16_t vendor;
uint16_t device;
} grlib;
struct <anonymous> {
uint16_t vendor;
} isa;
struct <anonymous> {
const char * name;
} fdtname;
struct <anonymous> {
const char * str;
} ata;
};

const char dev_enum_type_e[]  

This variable is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/driver.h source file, line 80.

Alternate declarations with same identifier: [1], [2].

enum dev_enum_type_e  

This enum is declared in device/driver.h source file, line 85.

This enum specifies types of enumeration data

Alternate declarations with same identifier: [1], [2].

See also struct dev_enum_ident_s.

IdentifierDescription
DEV_ENUM_TYPE_INVALID
DEV_ENUM_TYPE_GENERIC
DEV_ENUM_TYPE_PCI
DEV_ENUM_TYPE_ISA
DEV_ENUM_TYPE_ATA
DEV_ENUM_TYPE_FDTNAME
DEV_ENUM_TYPE_GAISLER

typedef error_t (dev_init_t)(struct device_s *dev, uint32_t cl_missing)   

This typedef is declared in device/driver.h source file, line 255.

This typedef is the device driver initialization function type. This function allocates device private data and initialize the hardware. It will be called before using any other functions on the device.

The device initialization status will be updated depending on the return value of this function:

  • If 0 is returned, the device status changes to DEVICE_INIT_DONE.

  • The first call to this function might not be able to fully complete the initialization of the device. In this case, it should return -EAGAIN to indicate that initialization will complete later. The device status will then be changed to DEVICE_INIT_ONGOING. The initialization may complete either when the device_async_init_done is called by the driver or when the dev_init_t function is called again. The later occurs when some progress are made on initialization of related devices and the DRIVER_FLAGS_INIT_RETRY flag of the driver is set. The device_init_is_partial function should be used to test for the initial invocation.

  • If an error is returned and the driver has not invoked the device_init_enable_api function, the status is changed to DEVICE_INIT_FAILED. The driver must have released all resource associated to the device in this case as the dev_cleanup_t function will not be called.

  • If an error is returned but some classes have been reported as initialized, the status is changed to DEVICE_INIT_PARTIAL.

The DRIVER_FLAGS_NO_DEPEND flag can be used so that this function is called even if some resource dependencies are not satisfied. The driver is then responsible for testing missing dependencies. In this case the cl_missing mask parameter indicates any driver classes related to a missing resource dependencies.

The DRIVER_FLAGS_EARLY_INIT flag can be used so that this function is called early during startup. Some kernel service can not be used in this case, especially, asynchronous initialization can not be used.

This declaration involves expansion of the DEV_INIT macro.

See also Device status.

error_t dev_use_generic(void *param, enum dev_use_op_e op)  

enum dev_use_op_e  

This enum is declared in device/driver.h source file, line 289.

This enum specifies device usage operations.

See also dev_use_t.

IdentifierDescription
DEV_USE_GET_ACCESSORGet and Put operations are used when the device_get_accessor and device_put_accessor functions are called. An error code may be returned on DEV_USE_GET_ACCESSOR in order to prevent the caller from acquiring an accessor. The param argument is a pointer to a struct device_accessor_s object.
DEV_USE_PUT_ACCESSOR
DEV_USE_LAST_NUMBERThis operation is used when device_last_number is called. The param argument is a pointer to a struct device_accessor_s structure with the dev and api field properly initialized. The default implementation reports 0.
DEV_USE_STARTStart and stop operations are invoked from the device_start and device_stop functions. An error code may be returned on DEV_USE_START. The param argument is a pointer to a struct device_accessor_s object. The default implementation does nothing and always succeed.
The driver may test if the value of device_s::start_count is zero. This field is updated by the device_start and device_stop functions. The driver may also manage the lower bits of the value directly if they were reserved by providing a suitable value for the CONFIG_DEVICE_START_LOG2INC token. The driver may still maintain some other internal start counters if sub-devices do require separate counters.
DEV_USE_STOPSee DEV_USE_START.
DEV_USE_SLEEPThis operation is only used when the driver has previously called the device_sleep_schedule function. The device power must be reduced if the device is not currently in use. The param argument is a pointer to a struct device_s object.
What is actually performed by the driver is device dependent. This may include releasing clock and power endpoints, calling device_stop on associated spi or i2c bus controllers or enabling a device specific low power mode.
When this operation is performed on multiple devices, driver initialization order is used to determine the call order. This ensure a bus controller is not disabled then re-enabled in order to put a dependent device in low power mode.
See also device_sleep_schedule.
DEV_USE_CLOCK_SINK_GATE_DONEThis operation is used when a clock or power enable operation requested by the driver has been satisfied. The param argument is a pointer to the sink endpoint.
See also dev_clock_sink_gate.
DEV_USE_CLOCK_SINK_FREQ_CHANGEDThis operation is used when a clock frequency change occurred on a clock sink endpoint and the change notifications is enabled. The change might not have been solicited by the driver. The param argument is a pointer to a struct dev_clock_notify_s object.
DEV_USE_ENUM_CHILD_INITThis operation is used when a device child initialization completes. The param argument is a pointer to the child device.

typedef error_t (dev_use_t)(void *param, enum dev_use_op_e op)   

This typedef is declared in device/driver.h source file, line 376.

This typedef is called when the usage status of a device changes. The dev_use_generic function provides a default implementation of this driver API function.

This function is called with the device lock held. Valid operations are defined in enum dev_use_op_e.

This declaration involves expansion of the DEV_USE macro.

struct device_accessor_s  

This struct is declared in device/driver.h source file, line 567.

This struct is the generic device accessor.

See also device_get_accessor and Device accessor.

FieldDescription
struct device_s * dev;
const struct driver_class_s * api;
uint_fast8_t number;

void device_async_cleanup_done(struct device_s *dev)  

This function function may be called from a deferred kroutine handler of the device driver when the dev_cleanup_t has previously returned -EAGAIN and the cleanup eventually terminates. It must be called with the device lock held.

This is available when CONFIG_DEVICE_CLEANUP and CONFIG_DEVICE_INIT_ASYNC are both defined.

void device_async_init_done(struct device_s *dev, error_t error)  

This function function may be called from a deferred kroutine handler of the device driver when the dev_init_t has previously returned -EAGAIN and some progress has been made. It must be called with the device lock held.

This is used to notify waiters, start a new pass on the device tree for initialization of depending devices and optionally update the device status.

  • If no error is reported, the device status changes to DEVICE_INIT_DONE.

  • If the -EAGAIN error code is used, the device is left in the DEVICE_INIT_ONGOING state.

  • If an error is reported and the driver has not invoked the device_init_enable_api function yet, the status is changed to DEVICE_INIT_FAILED. The driver must have released all resource associated to the device in this case as the dev_cleanup_t function will not be called.

  • If an error is reported and some classes have been reported as initialized, the status is changed to DEVICE_INIT_PARTIAL.

This is available when CONFIG_DEVICE_INIT_ASYNC is defined.

error_t device_bind_driver(struct device_s *dev, const struct driver_s *drv)  

This function binds a device to a device driver. No check is performed to determine if the driver is appropriate.

bool_t device_check_accessor(const struct device_accessor_s *acc)  

This function is declared in device/driver.h source file, line 750.

This function returns true is the device accessor has been successfully bound to a device by either the device_get_accessor or device_get_accessor_by_path function. This function returns false if one of these functions failed or if the accessor has not been touched since it was cleaned-up by device_put_accessor or initialized with DEVICE_ACCESSOR_INIT.

bool_t device_cmp_accessor(const struct device_accessor_s *a, const struct device_accessor_s *b)  

This function is declared in device/driver.h source file, line 703.

error_t device_copy_accessor(struct device_accessor_s *dst, const struct device_accessor_s *src)  

This function copies a device accessor. This gets a new reference to the accessor that must be released with device_put_accessor by itself.

See also Device accessor and device_put_accessor.

error_t device_get_accessor(struct device_accessor_s *acc, struct device_s *dev, enum driver_class_e cl, uint_fast8_t number)  

This function initializes a device accessor object. If the return value is 0, the accessor object can then be used to access device driver functions of requested api class.

The number parameter can be used when the device provides multiple sub-devices of the requested class type.

See also Device accessor and device_put_accessor.

error_t device_get_accessor_by_path(struct device_accessor_s *acc, struct device_node_s *root, const char *path, enum driver_class_e cl)  

This function initializes a device accessor object after lookup in the device tree. The root parameter may be NULL to lookup from the device tree root.

The path is of the form "node0/node1". An additionnal instance number may be added: "node0/node1[2]", the default instance number is 0. Multiple space separated paths can be specified as fallbacks: "node0 node1[0] node1[1]".

See device_get_by_path for more details in the path string format.

See also device_get_accessor and Device accessor.

void device_init_accessor(struct device_accessor_s *acc)  

This function is declared in device/driver.h source file, line 759.

This function initializes an accessor so that the device_check_accessor function return false.

error_t device_init_driver(struct device_s *dev)  

This function performs device initialization using previously bound driver.

void device_init_enable_api(struct device_s *dev, uint_fast8_t index)  

This function is declared in device/driver.h source file, line 643.

This function marks an API of the driver as available during partial initialization. The index specifies an API as passed to the DRIVER_DECLARE macro of the driver.

This is available when CONFIG_DEVICE_INIT_PARTIAL is defined.

See also DEVICE_INIT_ONGOING.

bool_t device_init_is_partial(struct device_s *dev)  

This function is declared in device/driver.h source file, line 666.

This function can be used from the dev_init_t function to test if we are doing additional passes of partial device initialization. This function returns false if we are in the first call to the initialization function which is always the case when CONFIG_DEVICE_INIT_PARTIAL is not defined.

bool_t device_init_test_api(struct device_s *dev, uint_fast8_t index)  

This function is declared in device/driver.h source file, line 651.

This function can be used during the initialization phase of a device to test if a specified API is initialized. The index specifies an API as passed to the DRIVER_DECLARE macro of the driver. This function always returns true if CONFIG_DEVICE_INIT_PARTIAL is not defined.

error_t device_last_number(struct device_s *dev, enum driver_class_e cl, uint_fast8_t *num)  

This function retreives the value of the last possibly valid sub-devices number. It returns -ENOTSUP if the class does not implement sub-devices. Other errors indicate that the driver class is not ready for use.

Numbers are used to specify an instance of a hardware device function, a logical driver feature or both. Implemented sub-devices numbers may not be contiguous. This allows binding a number to a particular feature or a special way of using the hardware which never changes for a given driver. In this case the driver may report a last number which may not be available with the current configuration.

void device_put_accessor(struct device_accessor_s *acc)  

This function must be called when device driver accessor is discarded. This function is used to decrement device usage references count.

See also device_get_accessor.

error_t device_release_driver(struct device_s *dev)  

This function stops the device and cleanup driver allocated resources.

This is available when CONFIG_DEVICE_CLEANUP is defined.

error_t device_start(struct device_accessor_s *acc)  

This function instructs the driver to keep the device in active state. This function internally invoke the DEV_USE_START operation of the driver increases the value of device_s::start_count and.

This function always returns immediately. It is implementation defined if the actual device startup is delayed by the driver.

Depending on the device class, the device operation may also get started when submitting requests to the device driver. In this case, this function can be used when the device must remain active between requests. Refer to the device class specific documentation for details..

See also device_stop and DEVICE_START_COUNT_INC.

error_t device_stop(struct device_accessor_s *acc)  

This function reverts the effect of the device_start function. This function internally decreases the value of device_s::start_count and invoke the DEV_USE_STOP operation of the driver..

See also device_start.

error_t device_unbind_driver(struct device_s *dev)  

This function leave the device without any associated driver.

This is available when CONFIG_DEVICE_CLEANUP is defined.

error_t device_wait_accessor(struct device_accessor_s *acc, struct device_s *dev, enum driver_class_e cl, uint_fast8_t number)  

This function function is similar to device_get_accessor, the current scheduler context is suspended until the device is initialized.

This is available when CONFIG_DEVICE_ENUM and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t device_wait_accessor_by_path(struct device_accessor_s *acc, struct device_node_s *root, const char *path, enum driver_class_e cl)  

This function function is similar to device_get_accessor_by_path, the current scheduler context is suspended until the device is initialized.

This is available when CONFIG_DEVICE_ENUM and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

const char driver_class_e[]  

This variable is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/driver.h source file, line 37.

Alternate declarations with same identifier: [1], [2].

enum driver_class_e  

This enum is declared in device/driver.h source file, line 42.

This enum specifies identifiers of device driver API classes.

Alternate declarations with same identifier: [1], [2].

See also Device classes.

IdentifierDescription
DRIVER_CLASS_NONE
DRIVER_CLASS_BLOCK
DRIVER_CLASS_CHARSee device/class/char.h and device/valio/uart_config.h.
DRIVER_CLASS_ENUMSee device/class/enum.h.
DRIVER_CLASS_FB
DRIVER_CLASS_ICUInterrupt Controller Unit
See also device/class/icu.h.
DRIVER_CLASS_DMASee device/class/dma.h.
DRIVER_CLASS_INPUT
DRIVER_CLASS_NETSee device/class/net.h.
DRIVER_CLASS_PCMSee device/class/pcm.h.
DRIVER_CLASS_TIMERSee device/class/timer.h.
DRIVER_CLASS_PWMSee device/class/pwm.h.
DRIVER_CLASS_SPI_CTRLSee device/class/spi.h.
DRIVER_CLASS_LCD
DRIVER_CLASS_CMUClock Management Unit
See also device/class/cmu.h.
DRIVER_CLASS_GPIOSee device/class/gpio.h.
DRIVER_CLASS_IOMUXSee device/class/iomux.h.
DRIVER_CLASS_I2C_CTRLSee device/class/i2c.h.
DRIVER_CLASS_I2C_SLAVE
DRIVER_CLASS_MEMSee device/class/mem.h.
DRIVER_CLASS_RFPACKETSee device/class/rfpacket.h.
DRIVER_CLASS_CRYPTOSee device/class/crypto.h.
DRIVER_CLASS_CPUSee device/class/cpu.h.
DRIVER_CLASS_VALIOSee device/class/valio.h.
DRIVER_CLASS_USBDEVSee device/class/usbdev.h.
DRIVER_CLASS_DISPLAYSee device/class/display.h.
DRIVER_CLASS_SMI
DRIVER_CLASS_PHY
DRIVER_CLASS_BITBANGSee device/class/bitbang.h.

enum driver_flags_e  

This enum is declared in device/driver.h source file, line 382.

This enum specifies struct driver_s flags

IdentifierDescription
DRIVER_FLAGS_EARLY_INITPerform initialization of the device during the INIT_BOOTSTRAP phase instead of INIT_SMP. This is needed mainly for processor and memory devices. It is not possible to rely on some kernel features (scheduler, irq, kroutines) being functional during the early initialization phase.
DRIVER_FLAGS_NO_DEPENDDo not test for missing resource dependencies before calling the driver initialization function on a device.
DRIVER_FLAGS_RETRY_INITThe dev_init_t function of the driver will be called again when the -EAGAIN error code is returned.

struct driver_s  

This struct is declared in device/driver.h source file, line 399.

device driver object structure

FieldDescription
const char * desc;driver description string
dev_init_t * f_init;
dev_cleanup_t * f_cleanup;
dev_use_t * f_use;
enum driver_flags_e flags:8;
uint16_t pv_size;
const struct driver_class_s * classes[];NULL terminated array of pointers to driver classes structs

#define DRIVER_CLASS_TYPES(id, cl, ...)  

This macro is declared in device/driver.h source file, line 498.

This macro declares a driver class.

This macro is for internal use only.

See also driver_class_e and Device classes.

#define DRIVER_CTX_CLASS_TYPES(id, cl, ...)  

This macro is declared in device/driver.h source file, line 540.

This macro declares a driver class which uses a libdevice context.

This macro is for internal use only.

See also DRIVER_CLASS_TYPES.

error_t device_get_api(struct device_s *dev, enum driver_class_e cl, const struct driver_class_s **api)  

This function is for internal use only.

struct driver_class_s  

This struct is declared in device/driver.h source file, line 557.

This struct is the generic device driver class struct header.

This struct is for internal use only.

FieldDescription
uint16_t class_;
uint16_t ctx_offset;
void * functions[];

struct driver_registry_s  

This struct is declared in device/driver.h source file, line 454.

This struct is for internal use only.

FieldDescription
const struct driver_s * driver;
const struct dev_enum_ident_s * id_table;
size_t id_count;

const struct driver_registry_s driver_registry_table[]  

This variable is declared in device/driver.h source file, line 461.

This variable is for internal use only.

const struct driver_registry_s driver_registry_table_end[]  

This variable is declared in device/driver.h source file, line 463.

This variable is for internal use only.

Valid XHTML 1.0 StrictGenerated by diaxen on Wed Oct 17 21:18:38 2018 using MkDoc