Zephyr API Documentation  3.1.99
A Scalable Open Source RTOS
Device Model APIs

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 name of a global device object. More...
 
#define DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_device, data_ptr, cfg_ptr, level, prio, api_ptr)
 Create a device object and set it up for boot time 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_device, data_ptr, cfg_ptr, level, prio, api_ptr, ...)
 Create a device object from a devicetree node identifier and set it up for boot time initialization. More...
 
#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. More...
 
#define DEVICE_DT_NAME_GET(node_id)   DEVICE_NAME_GET(Z_DEVICE_DT_DEV_NAME(node_id))
 The name of the global device object for node_id. More...
 
#define DEVICE_DT_GET(node_id)   (&DEVICE_DT_NAME_GET(node_id))
 Get a const struct device* from a devicetree node identifier. More...
 
#define DEVICE_DT_INST_GET(inst)   DEVICE_DT_GET(DT_DRV_INST(inst))
 Get a const struct device* for an instance of a DT_DRV_COMPAT compatible. More...
 
#define DEVICE_DT_GET_ANY(compat)
 Get a const struct device* from a devicetree compatible. More...
 
#define DEVICE_DT_GET_ONE(compat)
 Get a const struct device* from a devicetree compatible. More...
 
#define DEVICE_DT_GET_OR_NULL(node_id)
 Utility macro to obtain an optional reference to a device. 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 DEVICE_INIT_DT_GET(node_id)   (&Z_INIT_ENTRY_NAME(DEVICE_DT_NAME_GET(node_id)))
 Get a const struct init_entry* from a devicetree node. More...
 
#define DEVICE_INIT_GET(name)   (&Z_INIT_ENTRY_NAME(DEVICE_NAME_GET(name)))
 Get a const struct init_entry* from a device by name. More...
 
#define SYS_INIT(_init_fn, _level, _prio)    SYS_INIT_NAMED(_init_fn, _init_fn, _level, _prio)
 Run an initialization function at boot at specified priority. More...
 
#define SYS_INIT_NAMED(_name, _init_fn, _level, _prio)    Z_INIT_ENTRY_DEFINE(Z_SYS_NAME(_name), _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 a "handle" for a device. 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 devicedevice_from_handle (device_handle_t dev_handle)
 Get the device corresponding to a handle. More...
 
static const device_handle_tdevice_required_handles_get (const struct device *dev, size_t *count)
 Get the device handles for devicetree dependencies of this device. More...
 
static const device_handle_tdevice_injected_handles_get (const struct device *dev, size_t *count)
 Get the device handles for injected dependencies of this device. More...
 
static const device_handle_tdevice_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 devicedevice_get_binding (const char *name)
 Get a const struct device* from its name field. More...
 
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 <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
nameDevice name

◆ DEVICE_DEFINE

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

#include <zephyr/device.h>

Value:
Z_DEVICE_STATE_DEFINE(DT_INVALID_NODE, dev_name) \
Z_DEVICE_DEFINE(DT_INVALID_NODE, dev_name, drv_name, init_fn, \
pm_device, \
data_ptr, cfg_ptr, level, prio, api_ptr, \
&Z_DEVICE_STATE_NAME(dev_name))
#define DT_INVALID_NODE
Name for an invalid node identifier.
Definition: devicetree.h:75
static int init_fn(const struct device *dev)
Definition: main.c:241

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

This macro defines a struct 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_nameA unique token which is used in the name of the global device structure as a C identifier.
drv_nameA string name for the device, which will be stored in the device structure's name field. 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 NUL) in order to be looked up from user mode.
init_fnPointer to the device's initialization function, which will be run by the kernel during system initialization.
pm_devicePointer to the device's power management resources, a struct pm_device, which will be stored in the device structure's pm field. Use NULL if the device does not use PM.
data_ptrPointer to the device's private mutable data, which will be stored in the device structure's data field.
cfg_ptrPointer to the device's private constant data, which will be stored in the device structure's config field.
levelThe device's initialization level. See SYS_INIT() for details.
prioThe device's priority within its initialization level. See SYS_INIT() for details.
api_ptrPointer to the device's API structure. Can be NULL.

◆ DEVICE_DT_DEFINE

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

#include <zephyr/device.h>

Value:
Z_DEVICE_STATE_DEFINE(node_id, Z_DEVICE_DT_DEV_NAME(node_id)) \
Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_NAME(node_id), \
DEVICE_DT_NAME(node_id), init_fn, \
pm_device, \
data_ptr, cfg_ptr, level, prio, \
api_ptr, \
&Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_NAME(node_id)), \
__VA_ARGS__)
#define DEVICE_DT_NAME(node_id)
Return a string name for a devicetree node.
Definition: device.h:182

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

This macro defines a struct 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. The device structure's name field 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 device.h. Before using the pointer, the referenced object should be checked using device_is_ready().

Parameters
node_idThe devicetree node identifier.
init_fnPointer to the device's initialization function, which will be run by the kernel during system initialization.
pm_devicePointer to the device's power management resources, a struct pm_device, which will be stored in the device structure's pm field. Use NULL if the device does not use PM.
data_ptrPointer to the device's private mutable data, which will be stored in the device structure's data field.
cfg_ptrPointer to the device's private constant data, which will be stored in the device structure's config field.
levelThe device's initialization level. See SYS_INIT() for details.
prioThe device's priority within its initialization level. See SYS_INIT() for details.
api_ptrPointer 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 const struct device* 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_idA 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:
(NULL))
#define DEVICE_DT_GET(node_id)
Get a const struct device* from a devicetree node identifier.
Definition: device.h:283
#define DT_HAS_COMPAT_STATUS_OKAY(compat)
Does the devicetree have a status "okay" node with a compatible?
Definition: devicetree.h:2244
#define DT_COMPAT_GET_ANY_STATUS_OKAY(compat)
Get a node identifier for a status "okay" node with a compatible.
Definition: devicetree.h:424
#define COND_CODE_1(_flag, _if_1_code, _else_code)
Insert code depending on whether _flag expands to 1 or not.
Definition: util_macro.h:156

Get a const struct device* 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
compatlowercase-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:
#define ZERO_OR_COMPILE_ERROR(cond)
0 if cond is true-ish; causes a compile error otherwise.
Definition: util.h:78

Get a const struct device* 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 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
compatlowercase-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))
#define DT_NODE_HAS_STATUS(node_id, status)
Does a node identifier refer to a node with a status?
Definition: devicetree.h:2224

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_iddevicetree node identifier
Returns
a const struct device* 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
instinstance 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 const struct device* for an instance of a DT_DRV_COMPAT compatible.

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

Parameters
instDT_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 field from a devicetree node identifier.

Parameters
node_idThe 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_NAME(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_idDevicetree node identifier
Returns
The name of the device object as a C identifier

◆ DEVICE_GET

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

#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_name provided to DEVICE_DEFINE().

Parameters
nameThe 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 <zephyr/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 <zephyr/device.h>

Flag value used to identify an unknown device.

◆ DEVICE_HANDLE_SEP

#define DEVICE_HANDLE_SEP   INT16_MIN

#include <zephyr/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_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 const struct init_entry* from a devicetree node.

Parameters
node_idA devicetree node identifier
Returns
A pointer to the init_entry object created for that node

◆ DEVICE_INIT_GET

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

#include <zephyr/device.h>

Get a const struct init_entry* from a device by name.

Parameters
nameThe same as dev_name provided to DEVICE_DEFINE()
Returns
A pointer to the init_entry object created for that device

◆ DEVICE_NAME_GET

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

#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_name 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's 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
nameThe same dev_name token given to DEVICE_DEFINE()
Returns
The full name of the device object defined by DEVICE_DEFINE()

◆ SYS_INIT

#define SYS_INIT (   _init_fn,
  _level,
  _prio 
)     SYS_INIT_NAMED(_init_fn, _init_fn, _level, _prio)

#include <zephyr/init.h>

Run an initialization function at boot at specified priority.

This macro lets you run a function at system boot.

Parameters
_init_fnPointer to the boot function to run
_levelThe 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.
_prioThe 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).

◆ SYS_INIT_NAMED

#define SYS_INIT_NAMED (   _name,
  _init_fn,
  _level,
  _prio 
)     Z_INIT_ENTRY_DEFINE(Z_SYS_NAME(_name), _init_fn, NULL, _level, _prio)

#include <zephyr/init.h>

Run an initialization function at boot at specified priority.

This macro lets you run a function at system boot.

Parameters
_nameUnique name for SYS_INIT entry. Allows specifying multiple init entries that utilise the same function.
_init_fnSee SYS_INIT
_levelSee SYS_INIT
_prioSee SYS_INIT

Typedef Documentation

◆ device_handle_t

#include <zephyr/device.h>

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

Every struct device has an associated handle. You can get a pointer to a device structure 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
deva device in the set being iterated
contextstate 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_handlethe 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 const struct device* from its 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
namedevice 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
devthe 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_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
devthe device for which injected dependencies are desired.
countpointer 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
devpointer to the device in question.
Return values
trueIf the device is ready for use.
falseIf 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 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
deva 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_cbthe function that should be invoked on each device in the dependency set. This parameter must not be null.
contextstate 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 <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
devthe device for which dependencies are desired.
countpointer 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 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
deva 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_cbthe function that should be invoked on each device in the support set. This parameter must not be null.
contextstate 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 <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
devthe device for which supports are desired.
countpointer 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.