Device Model. More...

Modules
	Device memory-mapped IO management
	Definitions and helper macros for managing driver memory-mapped input/output (MMIO) regions appropriately in either RAM or ROM.

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_NULL 0
	Flag value used to identify an unknown device.

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

#define	DEVICE_DEFINE(dev_id, name, init_fn, pm, data, config, level, prio, api)
	Create a device object and set it up for boot time initialization.

#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.

#define	DEVICE_DT_DEFER(node_id) DT_PROP(node_id, zephyr_deferred_init)
	Determine if a devicetree node initialization should be deferred.

#define	DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api, ...)
	Create a device object from a devicetree node identifier and set it up for boot time initialization.

#define	DEVICE_DT_INST_DEFINE(inst, ...) DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
	Like DEVICE_DT_DEFINE(), but uses an instance of a `DT_DRV_COMPAT` compatible instead of a node identifier.

#define	DEVICE_DT_NAME_GET(node_id) DEVICE_NAME_GET(Z_DEVICE_DT_DEV_ID(node_id))
	The name of the global device object for `node_id`.

#define	DEVICE_DT_GET(node_id) (&DEVICE_DT_NAME_GET(node_id))
	Get a device reference from a devicetree node identifier.

#define	DEVICE_DT_INST_GET(inst) DEVICE_DT_GET(DT_DRV_INST(inst))
	Get a device reference for an instance of a `DT_DRV_COMPAT` compatible.

#define	DEVICE_DT_GET_ANY(compat)
	Get a device reference from a devicetree compatible.

#define	DEVICE_DT_GET_ONE(compat)
	Get a device reference from a devicetree compatible.

#define	DEVICE_DT_GET_OR_NULL(node_id)
	Utility macro to obtain an optional reference to a device.

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

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

#define	DEVICE_INIT_DT_GET(node_id) (&Z_INIT_ENTRY_NAME(DEVICE_DT_NAME_GET(node_id)))
	Get a init_entry reference from a devicetree node.

#define	DEVICE_INIT_GET(dev_id) (&Z_INIT_ENTRY_NAME(DEVICE_NAME_GET(dev_id)))
	Get a init_entry reference from a device identifier.

Typedefs
typedef int16_t	device_handle_t
	Type used to represent a "handle" for a device.

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

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

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

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

static const device_handle_t *	device_injected_handles_get (const struct device dev, size_t count)
	Get the device handles for injected dependencies of this device.

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.

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

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

const struct device *	device_get_binding (const char *name)
	Get a device reference from its device::name field.

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

int	device_init (const struct device *dev)
	Initialize a device.

Detailed Description

Device Model.

Since: 1.0

Version: 1.0.0

Macro Definition Documentation

◆ DEVICE_DECLARE

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

#include <zephyr/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

dev_id Device identifier.

◆ DEVICE_DEFINE

#define DEVICE_DEFINE	(	dev_id,
		name,
		init_fn,
		pm,
		data,
		config,
		level,
		prio,
		api
	)

#include <zephyr/device.h>

Value:

        Z_DEVICE_STATE_DEFINE(dev_id);                                         \
        Z_DEVICE_DEFINE(DT_INVALID_NODE, dev_id, name, init_fn, pm, data,      \
                        config, level, prio, api,                              \
                        &Z_DEVICE_STATE_NAME(dev_id))

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

This macro defines a device that is automatically configured by the kernel during system initialization. This macro should only be used when the device is not being allocated from a devicetree node. If you are allocating a device from a devicetree node, use DEVICE_DT_DEFINE() or DEVICE_DT_INST_DEFINE() instead.

Parameters

dev_id	A unique token which is used in the name of the global device structure as a C identifier.
name	A string name for the device, which will be stored in device::name. This name can be used to look up the device with device_get_binding(). This must be less than Z_DEVICE_MAX_NAME_LEN characters (including terminating `NULL`) in order to be looked up from user mode.
init_fn	Pointer to the device's initialization function, which will be run by the kernel during system initialization. Can be `NULL`.
pm	Pointer to the device's power management resources, a pm_device, which will be stored in device::pm field. Use `NULL` if the device does not use PM.
data	Pointer to the device's private mutable data, which will be stored in device::data.
config	Pointer to the device's private constant data, which will be stored in device::config.
level	The device's initialization level (PRE_KERNEL_1, PRE_KERNEL_2 or POST_KERNEL).
prio	The device's priority within its initialization level. See SYS_INIT() for details.
api	Pointer to the device's API structure. Can be `NULL`.

◆ DEVICE_DT_DEFER

#define DEVICE_DT_DEFER ( node_id ) DT_PROP(node_id, zephyr_deferred_init)

#include <zephyr/device.h>

Determine if a devicetree node initialization should be deferred.

Parameters

node_id The devicetree node identifier.

Returns: Boolean stating if node initialization should be deferred.

◆ DEVICE_DT_DEFINE

#define DEVICE_DT_DEFINE	(	node_id,
		init_fn,
		pm,
		data,
		config,
		level,
		prio,
		api,
		...
	)

#include <zephyr/device.h>

Value:

        Z_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id));                    \
        Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id),                  \
                        DEVICE_DT_NAME(node_id), init_fn, pm, data, config,    \
                        level, prio, api,                                      \
                        &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)),     \
                        __VA_ARGS__)

Create a device object from a devicetree node identifier and set it up for boot time initialization.

This macro defines a device that is automatically configured by the kernel during system initialization. The global device object's name as a C identifier is derived from the node's dependency ordinal. device::name is set to DEVICE_DT_NAME(node_id).

The device is declared with extern visibility, so a pointer to a global device object can be obtained with DEVICE_DT_GET(node_id) from any source file that includes <zephyr/device.h>. Before using the pointer, the referenced object should be checked using device_is_ready().

Parameters

node_id	The devicetree node identifier.
init_fn	Pointer to the device's initialization function, which will be run by the kernel during system initialization. Can be `NULL`.
pm	Pointer to the device's power management resources, a pm_device, which will be stored in device::pm. Use `NULL` if the device does not use PM.
data	Pointer to the device's private mutable data, which will be stored in device::data.
config	Pointer to the device's private constant data, which will be stored in device::config field.
level	The device's initialization level (PRE_KERNEL_1, PRE_KERNEL_2 or POST_KERNEL).
prio	The device's priority within its initialization level. See SYS_INIT() for details.
api	Pointer to the device's API structure. Can be `NULL`.

◆ DEVICE_DT_GET

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

#include <zephyr/device.h>

Get a device reference from a devicetree node identifier.

Returns a pointer to a device object created from a devicetree node, if any device was allocated by a driver.

If no such device was allocated, this will fail at linker time. If you get an error that looks like undefined reference to __device_dts_ord_<N>, that is what happened. Check to make sure your device driver is being compiled, usually by enabling the Kconfig options it requires.

Parameters

node_id A devicetree node identifier

Returns: A pointer to the device object created for that node

◆ DEVICE_DT_GET_ANY

#define DEVICE_DT_GET_ANY ( compat )

#include <zephyr/device.h>

Value:

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

Get a device reference from a devicetree compatible.

If an enabled devicetree node has the given compatible and a device object was created from it, this returns a pointer to 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 <zephyr/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)))

Get a device reference from a devicetree compatible.

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

If there are no such devices, this will fail at compile time.

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_GET_OR_NULL

#define DEVICE_DT_GET_OR_NULL ( node_id )

#include <zephyr/device.h>

Value:

COND_CODE_1(DT_NODE_HAS_STATUS(node_id, okay), \

(DEVICE_DT_GET(node_id)), (NULL))

DT_NODE_HAS_STATUS

#define DT_NODE_HAS_STATUS(node_id, status)

Does a node identifier refer to a node with a status?

Definition: devicetree.h:3212

Utility macro to obtain an optional reference to a device.

If the node identifier refers to a node with status okay, this returns DEVICE_DT_GET(node_id). Otherwise, it returns NULL.

Parameters

node_id devicetree node identifier

Returns: a device reference for the node identifier, which may be NULL.

◆ DEVICE_DT_INST_DEFINE

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

#include <zephyr/device.h>

Like DEVICE_DT_DEFINE(), but uses an instance of a DT_DRV_COMPAT compatible instead of a node identifier.

Parameters

inst	Instance number. The `node_id` argument to DEVICE_DT_DEFINE() is set to `DT_DRV_INST(inst)`.
...	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 <zephyr/device.h>

Get a device reference for an instance of a DT_DRV_COMPAT compatible.

This is equivalent to DEVICE_DT_GET(DT_DRV_INST(inst)).

Parameters

inst	`DT_DRV_COMPAT` instance number

Returns: A pointer to the device object created for that instance

◆ DEVICE_DT_NAME

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

#include <zephyr/device.h>

Return a string name for a devicetree node.

This macro returns a string literal usable as a device's name from a devicetree node identifier.

Parameters

node_id The devicetree node identifier.

Returns: The value of the node's label property, if it has one. Otherwise, the node's full name in node-name@unit-address form.

◆ DEVICE_DT_NAME_GET

#define DEVICE_DT_NAME_GET ( node_id ) DEVICE_NAME_GET(Z_DEVICE_DT_DEV_ID(node_id))

#include <zephyr/device.h>

The name of the global device object for node_id.

Returns the name of the global device structure as a C identifier. The device must be allocated using DEVICE_DT_DEFINE() or DEVICE_DT_INST_DEFINE() for this to work.

This macro is normally only useful within device driver source code. In other situations, you are probably looking for DEVICE_DT_GET().

Parameters

node_id Devicetree node identifier

Returns: The name of the device object as a C identifier

◆ DEVICE_GET

#define DEVICE_GET ( dev_id ) (&DEVICE_NAME_GET(dev_id))

#include <zephyr/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_id provided to DEVICE_DEFINE().

Parameters

dev_id Device identifier.

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

◆ DEVICE_HANDLE_NULL

#define DEVICE_HANDLE_NULL 0

#include <zephyr/device.h>

Flag value used to identify an unknown device.

◆ DEVICE_INIT_DT_GET

#define DEVICE_INIT_DT_GET ( node_id ) (&Z_INIT_ENTRY_NAME(DEVICE_DT_NAME_GET(node_id)))

#include <zephyr/device.h>

Get a init_entry reference from a devicetree node.

Parameters

node_id A devicetree node identifier

Returns: A pointer to the init_entry object created for that node

◆ DEVICE_INIT_GET

#define DEVICE_INIT_GET ( dev_id ) (&Z_INIT_ENTRY_NAME(DEVICE_NAME_GET(dev_id)))

#include <zephyr/device.h>

Get a init_entry reference from a device identifier.

Parameters

dev_id Device identifier.

Returns: A pointer to the init_entry object created for that device

◆ DEVICE_NAME_GET

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

#include <zephyr/device.h>

Expands to the name of a global device object.

Return the full name of a device object symbol created by DEVICE_DEFINE(), using the dev_id provided to DEVICE_DEFINE(). This is the name of the global variable storing the device structure, not a pointer to the string in the device::name field.

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

This macro is normally only useful within device driver source code. In other situations, you are probably looking for device_get_binding().

Parameters

dev_id Device identifier.

Returns: The full name of the device object defined by device definition macros.

Typedef Documentation

◆ device_handle_t

typedef int16_t device_handle_t

#include <zephyr/device.h>

Type used to represent a "handle" for a device.

Every device has an associated handle. You can get a pointer to a device from its handle and vice versa, but the handle uses less space than a pointer. The device.h API mainly uses handles to store lists of multiple devices in a compact way.

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.

See also: device_handle_get(); device_from_handle()

◆ device_visitor_callback_t

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

#include <zephyr/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.

See also: device_required_foreach(); device_supported_foreach()

Function Documentation

◆ device_from_handle()

static const struct device * device_from_handle ( device_handle_t dev_handle )

inlinestatic

#include <zephyr/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 <zephyr/device.h>

Get a device reference from its device::name field.

This function iterates through the devices on the system. If a device with the given name field is found, and that device initialized successfully at boot time, this function returns a pointer to the device.

If no device has the given name, this function returns NULL.

This function also returns NULL when a device is found, but it failed to initialize successfully at boot time. (To troubleshoot this case, set a breakpoint on your device driver's initialization function.)

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 with the given name; NULL if the device is not found or if the device with that name's initialization function failed.

◆ device_handle_get()

static device_handle_t device_handle_get ( const struct device * dev )

inlinestatic

#include <zephyr/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_init()

int device_init ( const struct device * dev )

#include <zephyr/device.h>

Initialize a device.

A device whose initialization was deferred (by marking it as zephyr,deferred-init on devicetree) needs to be initialized manually via this call. Note that only devices whose initialization was deferred can be initialized via this call - one can not try to initialize a non initialization deferred device that failed initialization with this call.

Parameters

dev	device to be initialized.

Return values

-ENOENT	If device was not found - or isn't a deferred one.
-errno	For other errors.

◆ device_injected_handles_get()

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

inlinestatic

#include <zephyr/device.h>

Get the device handles for injected dependencies of this device.

This function returns a pointer to an array of device handles. The length of the array is stored in the count parameter.

The array contains a handle for each device that dev manually injected as a dependency, via providing extra arguments to Z_DEVICE_DEFINE. This does not include transitive dependencies; you must recursively determine those.

Parameters

dev	the device for which injected dependencies are desired.
count	pointer to where this function should store the length of the returned array. No value is stored if the call returns a null pointer. The value may be set to zero if the device has no devicetree dependencies.

Returns: a pointer to a sequence of *count device handles, or a null pointer if dev does not have any dependency data.

◆ device_is_ready()

bool device_is_ready ( const struct device * dev )

#include <zephyr/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.

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 <zephyr/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_cb 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_cb` 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 <zephyr/device.h>

Get the device handles for devicetree dependencies of this device.

This function returns a pointer to an array of device handles. The length of the array is stored in the count parameter.

The array contains a handle for each device that dev requires directly, as determined from the devicetree. This does not include transitive dependencies; you must recursively determine those.

Parameters

dev	the device for which dependencies are desired.
count	pointer to where this function should store the length of the returned array. No value is stored if the call returns a null pointer. The value may be set to zero if the device has no devicetree dependencies.

Returns: a pointer to a sequence of count device handles, or a null pointer if dev does not have any dependency data.

◆ device_supported_foreach()

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

#include <zephyr/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_cb 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_cb` 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 <zephyr/device.h>

Get the set of handles that this device supports.

This function returns a pointer to an array of device handles. The length of the array is stored in the count parameter.

The array contains a handle for each device that dev "supports" – that is, devices that require dev directly – as determined from the devicetree. This does not include transitive dependencies; you must recursively determine those.

Parameters

dev	the device for which supports are desired.
count	pointer to where this function should store the length of the returned array. No value is stored if the call returns a null pointer. The value may be set to zero if nothing in the devicetree depends on `dev`.

Returns: a pointer to a sequence of *count device handles, or a null pointer if dev does not have any dependency data.

Modules

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ DEVICE_DECLARE

◆ DEVICE_DEFINE

◆ DEVICE_DT_DEFER

◆ DEVICE_DT_DEFINE

◆ DEVICE_DT_GET

◆ DEVICE_DT_GET_ANY

◆ DEVICE_DT_GET_ONE

◆ DEVICE_DT_GET_OR_NULL

◆ DEVICE_DT_INST_DEFINE

◆ DEVICE_DT_INST_GET

◆ DEVICE_DT_NAME

◆ DEVICE_DT_NAME_GET

◆ DEVICE_GET

◆ DEVICE_HANDLE_NULL

◆ DEVICE_INIT_DT_GET

◆ DEVICE_INIT_GET

◆ DEVICE_NAME_GET

Typedef Documentation

◆ device_handle_t

◆ device_visitor_callback_t

Function Documentation

◆ device_from_handle()

◆ device_get_binding()

◆ device_handle_get()

◆ device_init()

◆ device_injected_handles_get()

◆ device_is_ready()

◆ device_required_foreach()

◆ device_required_handles_get()

◆ device_supported_foreach()

◆ device_supported_handles_get()