Device Driver Interface

Device Model

group device_model

Device Model APIs.

Defines

Z_DEVICE_MAX_NAME_LEN
DEVICE_INIT(dev_name, drv_name, init_fn, data, cfg_info, level, prio)

Create device object and set it up for boot time initialization.

This macro defines a device object that is automatically configured by the kernel during system initialization. Note that devices set up with this macro will not be accessible from user mode since the API is not specified; whenever possible, use DEVICE_AND_API_INIT instead.

Parameters
  • dev_name: Device name. This must be less than Z_DEVICE_MAX_NAME_LEN characters in order to be looked up from user mode with device_get_binding().
  • drv_name: The name this instance of the driver exposes to the system.
  • init_fn: Address to the init function of the driver.
  • data: Pointer to the device’s configuration data.
  • cfg_info: The address to the structure containing the configuration information for this instance of the driver.
  • level: The initialization level at which configuration occurs. Must be one of the following symbols, which are listed in the order they are performed by the kernel:
    • PRE_KERNEL_1: Used for devices that have no dependencies, such as those that rely solely on hardware present in the processor/SOC. These devices cannot use any kernel services during configuration, since they are not yet available.
    • PRE_KERNEL_2: Used for devices that rely on the initialization of devices initialized as part of the PRE_KERNEL_1 level. These devices cannot use any kernel services during configuration, since they are not yet available.
    • POST_KERNEL: Used for devices that require kernel services during configuration.
    • APPLICATION: Used for application components (i.e. non-kernel components) that need automatic configuration. These devices can use all services provided by the kernel during configuration.
  • prio: The initialization priority of the device, relative to other devices of the same initialization level. Specified as an integer value in the range 0 to 99; lower values indicate earlier initialization. Must be a decimal integer literal without leading zeroes or sign (e.g. 32), or an equivalent symbolic name (e.g. #define MY_INIT_PRIO 32); symbolic expressions are not permitted (e.g. CONFIG_KERNEL_INIT_PRIORITY_DEFAULT + 5).

DEVICE_AND_API_INIT(dev_name, drv_name, init_fn, data, cfg_info, level, prio, api)

Create device object and set it up for boot time initialization, with the option to set driver_api.

This macro defines a device object that is automatically configured by the kernel during system initialization. Note that devices set up with this macro will not be accessible from user mode since the API is not specified; whenever possible, use DEVICE_AND_API_INIT instead.

The driver api is also set here, eliminating the need to do that during initialization.

Parameters
  • dev_name: Device name. This must be less than Z_DEVICE_MAX_NAME_LEN characters in order to be looked up from user mode with device_get_binding().
  • drv_name: The name this instance of the driver exposes to the system.
  • init_fn: Address to the init function of the driver.
  • data: Pointer to the device’s configuration data.
  • cfg_info: The address to the structure containing the configuration information for this instance of the driver.
  • level: The initialization level at which configuration occurs. Must be one of the following symbols, which are listed in the order they are performed by the kernel:
    • PRE_KERNEL_1: Used for devices that have no dependencies, such as those that rely solely on hardware present in the processor/SOC. These devices cannot use any kernel services during configuration, since they are not yet available.
    • PRE_KERNEL_2: Used for devices that rely on the initialization of devices initialized as part of the PRE_KERNEL_1 level. These devices cannot use any kernel services during configuration, since they are not yet available.
    • POST_KERNEL: Used for devices that require kernel services during configuration.
    • APPLICATION: Used for application components (i.e. non-kernel components) that need automatic configuration. These devices can use all services provided by the kernel during configuration.
  • prio: The initialization priority of the device, relative to other devices of the same initialization level. Specified as an integer value in the range 0 to 99; lower values indicate earlier initialization. Must be a decimal integer literal without leading zeroes or sign (e.g. 32), or an equivalent symbolic name (e.g. #define MY_INIT_PRIO 32); symbolic expressions are not permitted (e.g. CONFIG_KERNEL_INIT_PRIORITY_DEFAULT + 5).
  • api: Provides an initial pointer to the API function struct used by the driver. Can be NULL.

DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_control_fn, data, cfg_info, level, prio, api)

Create device object and set it up for boot time initialization, with the option to device_pm_control.

This macro defines a device object that is automatically configured by the kernel during system initialization. Note that devices set up with this macro will not be accessible from user mode since the API is not specified; whenever possible, use DEVICE_AND_API_INIT instead.

The driver api is also set here, eliminating the need to do that during initialization.

Parameters
  • dev_name: Device name. This must be less than Z_DEVICE_MAX_NAME_LEN characters in order to be looked up from user mode with device_get_binding().
  • drv_name: The name this instance of the driver exposes to the system.
  • init_fn: Address to the init function of the driver.
  • data: Pointer to the device’s configuration data.
  • cfg_info: The address to the structure containing the configuration information for this instance of the driver.
  • level: The initialization level at which configuration occurs. Must be one of the following symbols, which are listed in the order they are performed by the kernel:
    • PRE_KERNEL_1: Used for devices that have no dependencies, such as those that rely solely on hardware present in the processor/SOC. These devices cannot use any kernel services during configuration, since they are not yet available.
    • PRE_KERNEL_2: Used for devices that rely on the initialization of devices initialized as part of the PRE_KERNEL_1 level. These devices cannot use any kernel services during configuration, since they are not yet available.
    • POST_KERNEL: Used for devices that require kernel services during configuration.
    • APPLICATION: Used for application components (i.e. non-kernel components) that need automatic configuration. These devices can use all services provided by the kernel during configuration.
  • prio: The initialization priority of the device, relative to other devices of the same initialization level. Specified as an integer value in the range 0 to 99; lower values indicate earlier initialization. Must be a decimal integer literal without leading zeroes or sign (e.g. 32), or an equivalent symbolic name (e.g. #define MY_INIT_PRIO 32); symbolic expressions are not permitted (e.g. CONFIG_KERNEL_INIT_PRIORITY_DEFAULT + 5).
  • api: Provides an initial pointer to the API function struct used by the driver. Can be NULL.
Parameters
  • pm_control_fn: Pointer to device_pm_control function. Can be empty function (device_pm_control_nop) if not implemented.

DEVICE_NAME_GET(name)

Expands to the full name of a global device object.

Return the full name of a device object symbol created by DEVICE_INIT(), using the dev_name provided to DEVICE_INIT().

It is meant to be used for declaring extern symbols pointing on device objects before using the DEVICE_GET macro to get the device object.

Return
The expanded name of the device object created by DEVICE_INIT()
Parameters
  • name: The same as dev_name provided to DEVICE_INIT()

DEVICE_GET(name)

Obtain a pointer to a device object by name.

Return the address of a device object created by DEVICE_INIT(), using the dev_name provided to DEVICE_INIT().

Return
A pointer to the device object created by DEVICE_INIT()
Parameters
  • name: The same as dev_name provided to DEVICE_INIT()

DEVICE_DECLARE(name)

Declare a static device object.

This macro can be used at the top-level to declare a device, such that DEVICE_GET() may be used before the full declaration in DEVICE_INIT().

This is often useful when configuring interrupts statically in a device’s init or per-instance config function, as the init function itself is required by DEVICE_INIT() and use of DEVICE_GET() inside it creates a circular dependency.

Parameters
  • name: Device name

Functions

struct device *device_get_binding(const char *name)

Retrieve the device structure for a driver by name.

Device objects are created via the DEVICE_INIT() macro and placed in memory by the linker. If a driver needs to bind to another driver it can use this function to retrieve the device structure of the lower level driver by the name the driver exposes to the system.

Return
pointer to device structure; NULL if not found or cannot be used.
Parameters
  • name: device name to search for.

struct device_config
#include <device.h>

Static device information (In ROM) Per driver instance.

Parameters
  • name: name of the device
  • init: init function for the driver
  • config_info: address of driver instance config information

struct device
#include <device.h>

Runtime device structure (In memory) Per driver instance.

Parameters
  • device_config: Build time config information
  • driver_api: pointer to structure containing the API functions for the device type. This pointer is filled in by the driver at init time.
  • driver_data: driver instance data. For driver use only