Device Model APIs. More...

Data Structures
struct	device_state
	Runtime device dynamic structure (in RAM) per driver instance. More...

struct	device
	Runtime device structure (in ROM) per driver instance. More...

Macros
#define	DEVICE_HANDLE_SEP INT16_MIN
	Flag value used in lists of device handles to separate distinct groups. More...

#define	DEVICE_HANDLE_ENDS INT16_MAX
	Flag value used in lists of device handles to indicate the end of the list. More...

#define	DEVICE_HANDLE_NULL 0
	Flag value used to identify an unknown device. More...

#define	DEVICE_NAME_GET(name) _CONCAT(__device_, name)
	Expands to the full name of a global device object. More...

#define	SYS_DEVICE_DEFINE(drv_name, init_fn, pm_control_fn, level, prio)
	Run an initialization function at boot at specified priority, and define device PM control function. More...

#define	DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_control_fn, data_ptr, cfg_ptr, level, prio, api_ptr)
	Create device object and set it up for boot time initialization, with the option to pm_control. In case of Device Idle Power Management is enabled, make sure the device is in suspended state after initialization. More...

#define	DEVICE_DT_NAME(node_id) DT_PROP_OR(node_id, label, DT_NODE_FULL_NAME(node_id))
	Return a string name for a devicetree node. More...

#define	DEVICE_DT_DEFINE(node_id, init_fn, pm_control_fn, data_ptr, cfg_ptr, level, prio, api_ptr, ...)
	Like DEVICE_DEFINE but taking metadata from a devicetree node. More...

#define	DEVICE_DT_INST_DEFINE(inst, ...) DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
	Like DEVICE_DT_DEFINE for an instance of a DT_DRV_COMPAT compatible. More...

#define	DEVICE_DT_NAME_GET(node_id) DEVICE_NAME_GET(Z_DEVICE_DT_DEV_NAME(node_id))
	The name of the struct device object for `node_id`. More...

#define	DEVICE_DT_GET(node_id) (&DEVICE_DT_NAME_GET(node_id))
	Obtain a pointer to a device object by `node_id`. More...

#define	DEVICE_DT_INST_GET(inst) DEVICE_DT_GET(DT_DRV_INST(inst))
	Obtain a pointer to a device object for an instance of a DT_DRV_COMPAT compatible. More...

#define	DEVICE_DT_GET_ANY(compat)
	Obtain a pointer to a device object by devicetree compatible. More...

#define	DEVICE_DT_GET_ONE(compat)
	Obtain a pointer to a device object by devicetree compatible. More...

#define	DEVICE_GET(name) (&DEVICE_NAME_GET(name))
	Obtain a pointer to a device object by name. More...

#define	DEVICE_DECLARE(name) static const struct device DEVICE_NAME_GET(name)
	Declare a static device object. More...

#define	SYS_INIT(_init_fn, _level, _prio) Z_INIT_ENTRY_DEFINE(Z_SYS_NAME(_init_fn), _init_fn, NULL, _level, _prio)
	Run an initialization function at boot at specified priority. More...

Typedefs
typedef int16_t	device_handle_t
	Type used to represent devices and functions. More...

typedef int(*	device_visitor_callback_t) (const struct device dev, void context)
	Prototype for functions used when iterating over a set of devices. More...

Functions
static device_handle_t	device_handle_get (const struct device *dev)
	Get the handle for a given device. More...

static const struct device *	device_from_handle (device_handle_t dev_handle)
	Get the device corresponding to a handle. More...

static const device_handle_t *	device_required_handles_get (const struct device dev, size_t count)
	Get the set of handles for devicetree dependencies of this device. More...

static const device_handle_t *	device_supported_handles_get (const struct device dev, size_t count)
	Get the set of handles that this device supports. More...

int	device_required_foreach (const struct device dev, device_visitor_callback_t visitor_cb, void context)
	Visit every device that `dev` directly requires. More...

int	device_supported_foreach (const struct device dev, device_visitor_callback_t visitor_cb, void context)
	Visit every device that `dev` directly supports. More...

const struct device *	device_get_binding (const char *name)
	Retrieve the device structure for a driver by name. More...

int	device_usable_check (const struct device *dev)
	Determine whether a device is ready for use. More...

static bool	device_is_ready (const struct device *dev)
	Verify that a device is ready for use. More...

Detailed Description

Device Model APIs.

Macro Definition Documentation

◆ DEVICE_DECLARE

#define DEVICE_DECLARE ( name ) static const struct device DEVICE_NAME_GET(name)

#include <include/device.h>

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_DEFINE().

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_DEFINE() and use of DEVICE_GET() inside it creates a circular dependency.

Parameters

name	Device name

◆ DEVICE_DEFINE

#define DEVICE_DEFINE	(	dev_name,
		drv_name,
		init_fn,
		pm_control_fn,
		data_ptr,
		cfg_ptr,
		level,
		prio,
		api_ptr
	)

#include <include/device.h>

Value:

        Z_DEVICE_DEFINE(DT_INVALID_NODE, dev_name, drv_name, init_fn,   \
                        pm_control_fn,                                  \
                        data_ptr, cfg_ptr, level, prio, api_ptr)

Create device object and set it up for boot time initialization, with the option to pm_control. In case of Device Idle Power Management is enabled, make sure the device is in suspended state after 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;

Parameters

dev_name	Device name. This must be less than Z_DEVICE_MAX_NAME_LEN characters (including terminating NUL) 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.
pm_control_fn	Pointer to pm_control function. Can be NULL if not implemented.
data_ptr	Pointer to the device's private data.
cfg_ptr	The address to the structure containing the configuration information for this instance of the driver.
level	The initialization level. See SYS_INIT() for details.
prio	Priority within the selected initialization level. See SYS_INIT() for details.
api_ptr	Provides an initial pointer to the API function struct used by the driver. Can be NULL.

◆ DEVICE_DT_DEFINE

#define DEVICE_DT_DEFINE	(	node_id,
		init_fn,
		pm_control_fn,
		data_ptr,
		cfg_ptr,
		level,
		prio,
		api_ptr,
		...
	)

#include <include/device.h>

Value:

        Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_NAME(node_id),         \
                        DEVICE_DT_NAME(node_id), init_fn,               \
                        pm_control_fn,                                  \
                        data_ptr, cfg_ptr, level, prio,                 \
                        api_ptr, __VA_ARGS__)

Like DEVICE_DEFINE but taking metadata from a devicetree node.

This macro defines a device object that is automatically configured by the kernel during system initialization. The device object name is derived from the node identifier (encoding the devicetree path to the node), and the driver name is from the label property of the devicetree node.

The device is declared with extern visibility, so device objects defined through this API can be obtained directly through DEVICE_DT_GET() using node_id. Before using the pointer the referenced object should be checked using device_is_ready().

Parameters

node_id	The devicetree node identifier.
init_fn	Address to the init function of the driver.
pm_control_fn	Pointer to pm_control function. Can be NULL if not implemented.
data_ptr	Pointer to the device's private data.
cfg_ptr	The address to the structure containing the configuration information for this instance of the driver.
level	The initialization level. See SYS_INIT() for details.
prio	Priority within the selected initialization level. See SYS_INIT() for details.
api_ptr	Provides an initial pointer to the API function struct used by the driver. Can be NULL.

◆ DEVICE_DT_GET

#define DEVICE_DT_GET ( node_id ) (&DEVICE_DT_NAME_GET(node_id))

#include <include/device.h>

Obtain a pointer to a device object by node_id.

Return the address of a device object created by DEVICE_DT_INIT(), using the dev_name derived from node_id

Parameters

node_id The same as node_id provided to DEVICE_DT_DEFINE()

Returns: A pointer to the device object created by DEVICE_DT_DEFINE()

◆ DEVICE_DT_GET_ANY

#define DEVICE_DT_GET_ANY ( compat )

#include <include/device.h>

Value:

        COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),                      \
                    (DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(compat))), \
                    (NULL))

Obtain a pointer to a device object by devicetree compatible.

If any enabled devicetree node has the given compatible and a device object was created from it, this returns that device.

If there no such devices, this returns NULL.

If there are multiple, this returns an arbitrary one.

If this returns non-NULL, the device must be checked for readiness before use, e.g. with device_is_ready().

Parameters

compat lowercase-and-underscores devicetree compatible

Returns: a pointer to a device, or NULL

◆ DEVICE_DT_GET_ONE

#define DEVICE_DT_GET_ONE ( compat )

#include <include/device.h>

Value:

        COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),                      \
                    (DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(compat))), \
                    (ZERO_OR_COMPILE_ERROR(0)))

Obtain a pointer to a device object by devicetree compatible.

If any enabled devicetree node has the given compatible and a device object was created from it, this returns that device.

If there no such devices, this throws a compilation error.

If there are multiple, this returns an arbitrary one.

If this returns non-NULL, the device must be checked for readiness before use, e.g. with device_is_ready().

Parameters

compat lowercase-and-underscores devicetree compatible

Returns: a pointer to a device

◆ DEVICE_DT_INST_DEFINE

#define DEVICE_DT_INST_DEFINE	(	inst,
		...
	)	DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)

#include <include/device.h>

Like DEVICE_DT_DEFINE for an instance of a DT_DRV_COMPAT compatible.

Parameters

inst	instance number. This is replaced by `DT_DRV_COMPAT(inst)` in the call to DEVICE_DT_DEFINE.
...	other parameters as expected by DEVICE_DT_DEFINE.

◆ DEVICE_DT_INST_GET

#define DEVICE_DT_INST_GET ( inst ) DEVICE_DT_GET(DT_DRV_INST(inst))

#include <include/device.h>

Obtain a pointer to a device object for an instance of a DT_DRV_COMPAT compatible.

Parameters

inst	instance number

◆ DEVICE_DT_NAME

#define DEVICE_DT_NAME ( node_id ) DT_PROP_OR(node_id, label, DT_NODE_FULL_NAME(node_id))

#include <include/device.h>

Return a string name for a devicetree node.

This macro returns a string literal usable as a device name from a devicetree node. If the node has a "label" property, its value is returned. Otherwise, the node's full "node-name@@unit-address" name is returned.

Parameters

node_id The devicetree node identifier.

◆ DEVICE_DT_NAME_GET

#define DEVICE_DT_NAME_GET ( node_id ) DEVICE_NAME_GET(Z_DEVICE_DT_DEV_NAME(node_id))

#include <include/device.h>

The name of the struct device object for node_id.

Return the full name of a device object symbol created by DEVICE_DT_DEFINE(), using the dev_name derived from node_id

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

Parameters

node_id The same as node_id provided to DEVICE_DT_DEFINE()

Returns: The expanded name of the device object created by DEVICE_DT_DEFINE()

◆ DEVICE_GET

#define DEVICE_GET ( name ) (&DEVICE_NAME_GET(name))

#include <include/device.h>

Obtain a pointer to a device object by name.

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

Parameters

name	The same as dev_name provided to DEVICE_DEFINE()

Returns: A pointer to the device object created by DEVICE_DEFINE()

◆ DEVICE_HANDLE_ENDS

#define DEVICE_HANDLE_ENDS INT16_MAX

#include <include/device.h>

Flag value used in lists of device handles to indicate the end of the list.

This is the maximum value for the device_handle_t type.

◆ DEVICE_HANDLE_NULL

#define DEVICE_HANDLE_NULL 0

#include <include/device.h>

Flag value used to identify an unknown device.

◆ DEVICE_HANDLE_SEP

#define DEVICE_HANDLE_SEP INT16_MIN

#include <include/device.h>

Flag value used in lists of device handles to separate distinct groups.

This is the minimum value for the device_handle_t type.

◆ DEVICE_NAME_GET

#define DEVICE_NAME_GET ( name ) _CONCAT(__device_, name)

#include <include/device.h>

Expands to the full name of a global device object.

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

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.

Parameters

name	The same as dev_name provided to DEVICE_DEFINE()

Returns: The expanded name of the device object created by DEVICE_DEFINE()

◆ SYS_DEVICE_DEFINE

#define SYS_DEVICE_DEFINE	(	drv_name,
		init_fn,
		pm_control_fn,
		level,
		prio
	)

#include <include/device.h>

Value:

        DEVICE_DEFINE(Z_SYS_NAME(init_fn), drv_name, init_fn,           \
                      pm_control_fn,                                    \
                      NULL, NULL, level, prio, NULL)

Run an initialization function at boot at specified priority, and define device PM control function.

Invokes DEVICE_DEFINE() with no power management support (pm_control_fn), no API (api_ptr), and a device name derived from the init_fn name (dev_name).

◆ SYS_INIT

#define SYS_INIT	(	_init_fn,
		_level,
		_prio
	)	Z_INIT_ENTRY_DEFINE(Z_SYS_NAME(_init_fn), _init_fn, NULL, _level, _prio)

#include <include/init.h>

Run an initialization function at boot at specified priority.

This macro lets you run a function at system boot.

Parameters

_init_fn	Pointer to the boot function to run
_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 initialization objects that have no dependencies, such as those that rely solely on hardware present in the processor/SOC. These objects cannot use any kernel services during configuration, since they are not yet available. PRE_KERNEL_2: Used for initialization objects that rely on objects initialized as part of the PRE_KERNEL_1 level. These objects cannot use any kernel services during configuration, since they are not yet available. POST_KERNEL: Used for initialization objects that require kernel services during configuration. POST_KERNEL_SMP: Used for initialization objects that require kernel services during configuration after SMP initialization. APPLICATION: Used for application components (i.e. non-kernel components) that need automatic configuration. These objects can use all services provided by the kernel during configuration.
_prio	The initialization priority of the object, relative to other objects 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).

Typedef Documentation

◆ device_handle_t

typedef int16_t device_handle_t

#include <include/device.h>

Type used to represent devices and functions.

The extreme values and zero have special significance. Negative values identify functionality that does not correspond to a Zephyr device, such as the system clock or a SYS_INIT() function.

◆ device_visitor_callback_t

typedef int(* device_visitor_callback_t) (const struct device *dev, void *context)

#include <include/device.h>

Prototype for functions used when iterating over a set of devices.

Such a function may be used in API that identifies a set of devices and provides a visitor API supporting caller-specific interaction with each device in the set.

The visit is said to succeed if the visitor returns a non-negative value.

Parameters

dev	a device in the set being iterated
context	state used to support the visitor function

Returns: A non-negative number to allow walking to continue, and a negative error code to case the iteration to stop.

Function Documentation

◆ device_from_handle()

static const struct device * device_from_handle ( device_handle_t dev_handle )

inlinestatic

#include <include/device.h>

Get the device corresponding to a handle.

Parameters

dev_handle the device handle

Returns: the device that has that handle, or a null pointer if dev_handle does not identify a device.

◆ device_get_binding()

const struct device * device_get_binding ( const char * name )

#include <include/device.h>

Retrieve the device structure for a driver by name.

Device objects are created via the DEVICE_DEFINE() 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.

Parameters

name	device name to search for. A null pointer, or a pointer to an empty string, will cause NULL to be returned.

Returns: pointer to device structure; NULL if not found or cannot be used.

◆ device_handle_get()

static device_handle_t device_handle_get ( const struct device * dev )

inlinestatic

#include <include/device.h>

Get the handle for a given device.

Parameters

dev	the device for which a handle is desired.

Returns: the handle for the device, or DEVICE_HANDLE_NULL if the device does not have an associated handle.

◆ device_is_ready()

static bool device_is_ready ( const struct device * dev )

inlinestatic

#include <include/device.h>

Verify that a device is ready for use.

Indicates whether the provided device pointer is for a device known to be in a state where it can be used with its standard API.

This can be used with device pointers captured from DEVICE_DT_GET(), which does not include the readiness checks of device_get_binding(). At minimum this means that the device has been successfully initialized, but it may take on further conditions (e.g. is not powered down).

Parameters

dev	pointer to the device in question.

Return values

true	if the device is ready for use.
false	if the device is not ready for use or if a NULL device pointer is passed as argument.

◆ device_required_foreach()

int device_required_foreach	(	const struct device *	dev,
		device_visitor_callback_t	visitor_cb,
		void *	context
	)

#include <include/device.h>

Visit every device that dev directly requires.

Zephyr maintains information about which devices are directly required by another device; for example an I2C-based sensor driver will require an I2C controller for communication. Required devices can derive from statically-defined devicetree relationships or dependencies registered at runtime.

This API supports operating on the set of required devices. Example uses include making sure required devices are ready before the requiring device is used, and releasing them when the requiring device is no longer needed.

There is no guarantee on the order in which required devices are visited.

If the visitor function returns a negative value iteration is halted, and the returned value from the visitor is returned from this function.

Note: This API is not available to unprivileged threads.

Parameters

dev	a device of interest. The devices that this device depends on will be used as the set of devices to visit. This parameter must not be null.
visitor_cb	the function that should be invoked on each device in the dependency set. This parameter must not be null.
context	state that is passed through to the visitor function. This parameter may be null if `visitor` tolerates a null `context`.

Returns: The number of devices that were visited if all visits succeed, or the negative value returned from the first visit that did not succeed.

◆ device_required_handles_get()

static const device_handle_t * device_required_handles_get	(	const struct device *	dev,
		size_t *	count
	)

inlinestatic

#include <include/device.h>

Get the set of handles for devicetree dependencies of this device.

These are the device dependencies inferred from devicetree.

Parameters

dev	the device for which dependencies are desired.
count	pointer to a place to store the number of devices provided at the returned pointer. The value is not set if the call returns a null pointer. The value may be set to zero.

Returns: a pointer to a sequence of *count device handles, or a null pointer if dh does not provide dependency information.

◆ device_supported_foreach()

int device_supported_foreach	(	const struct device *	dev,
		device_visitor_callback_t	visitor_cb,
		void *	context
	)

#include <include/device.h>

Visit every device that dev directly supports.

Zephyr maintains information about which devices are directly supported by another device; for example an I2C controller will support an I2C-based sensor driver. Supported devices can derive from statically-defined devicetree relationships.

This API supports operating on the set of supported devices. Example uses include iterating over the devices connected to a regulator when it is powered on.

There is no guarantee on the order in which required devices are visited.

If the visitor function returns a negative value iteration is halted, and the returned value from the visitor is returned from this function.

Note: This API is not available to unprivileged threads.

Parameters

dev	a device of interest. The devices that this device supports will be used as the set of devices to visit. This parameter must not be null.
visitor_cb	the function that should be invoked on each device in the support set. This parameter must not be null.
context	state that is passed through to the visitor function. This parameter may be null if `visitor` tolerates a null `context`.

Returns: The number of devices that were visited if all visits succeed, or the negative value returned from the first visit that did not succeed.

◆ device_supported_handles_get()

static const device_handle_t * device_supported_handles_get	(	const struct device *	dev,
		size_t *	count
	)

inlinestatic

#include <include/device.h>

Get the set of handles that this device supports.

The set of supported devices is inferred from devicetree, and does not include any software constructs that may depend on the device.

Parameters

dev	the device for which supports are desired.
count	pointer to a place to store the number of devices provided at the returned pointer. The value is not set if the call returns a null pointer. The value may be set to zero.

Returns: a pointer to a sequence of *count device handles, or a null pointer if dh does not provide dependency information.

◆ device_usable_check()

int device_usable_check ( const struct device * dev )

#include <include/device.h>

Determine whether a device is ready for use.

This checks whether a device can be used, returning 0 if it can, and distinct error values that identify the reason if it cannot.

Return values

0	if the device is usable.
-ENODEV	if the device has not been initialized, the device pointer is NULL or the initialization failed.
other	negative error codes to indicate additional conditions that make the device unusable.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ DEVICE_DECLARE

◆ DEVICE_DEFINE

◆ DEVICE_DT_DEFINE

◆ DEVICE_DT_GET

◆ DEVICE_DT_GET_ANY

◆ DEVICE_DT_GET_ONE

◆ DEVICE_DT_INST_DEFINE

◆ DEVICE_DT_INST_GET

◆ DEVICE_DT_NAME

◆ DEVICE_DT_NAME_GET

◆ DEVICE_GET

◆ DEVICE_HANDLE_ENDS

◆ DEVICE_HANDLE_NULL

◆ DEVICE_HANDLE_SEP

◆ DEVICE_NAME_GET

◆ SYS_DEVICE_DEFINE

◆ SYS_INIT

Typedef Documentation

◆ device_handle_t

◆ device_visitor_callback_t

Function Documentation

◆ device_from_handle()

◆ device_get_binding()

◆ device_handle_get()

◆ device_is_ready()

◆ device_required_foreach()

◆ device_required_handles_get()

◆ device_supported_foreach()

◆ device_supported_handles_get()

◆ device_usable_check()