Zephyr API Documentation 4.0.0
A Scalable Open Source RTOS
|
Device Model . More...
Topics | |
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) |
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) |
Return a string name for a devicetree node. | |
#define | DEVICE_DT_DEFER(node_id) |
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, ...) |
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) |
The name of the global device object for node_id . | |
#define | DEVICE_DT_GET(node_id) |
Get a device reference from a devicetree node identifier. | |
#define | DEVICE_DT_INST_GET(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) |
Obtain a pointer to a device object by name. | |
#define | DEVICE_DECLARE(dev_id) |
Declare a static device object. | |
#define | DEVICE_INIT_DT_GET(node_id) |
Get a init_entry reference from a devicetree node. | |
#define | DEVICE_INIT_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. | |
Device Model .
#define DEVICE_DECLARE | ( | 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.
dev_id | Device identifier. |
#define DEVICE_DEFINE | ( | dev_id, | |
name, | |||
init_fn, | |||
pm, | |||
data, | |||
config, | |||
level, | |||
prio, | |||
api ) |
#include <zephyr/device.h>
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.
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 . |
#define DEVICE_DT_DEFER | ( | node_id | ) |
#include <zephyr/device.h>
Determine if a devicetree node initialization should be deferred.
node_id | The devicetree node identifier. |
#define DEVICE_DT_DEFINE | ( | node_id, | |
init_fn, | |||
pm, | |||
data, | |||
config, | |||
level, | |||
prio, | |||
api, | |||
... ) |
#include <zephyr/device.h>
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>
(even from extensions, when
CONFIG_LLEXT_EXPORT_DEVICES
is enabled). Before using the pointer, the referenced object should be checked using device_is_ready().
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 . |
#define DEVICE_DT_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.
node_id | A devicetree node identifier |
#define DEVICE_DT_GET_ANY | ( | compat | ) |
#include <zephyr/device.h>
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().
compat | lowercase-and-underscores devicetree compatible |
#define DEVICE_DT_GET_ONE | ( | compat | ) |
#include <zephyr/device.h>
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().
compat | lowercase-and-underscores devicetree compatible |
#define DEVICE_DT_GET_OR_NULL | ( | node_id | ) |
#include <zephyr/device.h>
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
.
node_id | devicetree node identifier |
NULL
. #define DEVICE_DT_INST_DEFINE | ( | inst, | |
... ) |
#include <zephyr/device.h>
Like DEVICE_DT_DEFINE(), but uses an instance of a DT_DRV_COMPAT
compatible instead of a node identifier.
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(). |
#define DEVICE_DT_INST_GET | ( | 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))
.
inst | DT_DRV_COMPAT instance number |
#define DEVICE_DT_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.
node_id | The devicetree node identifier. |
label
property, if it has one. Otherwise, the node's full name in node-name@unit-address
form. #define DEVICE_DT_NAME_GET | ( | 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().
node_id | Devicetree node identifier |
#define DEVICE_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().
dev_id | Device identifier. |
#define DEVICE_HANDLE_NULL 0 |
#include <zephyr/device.h>
Flag value used to identify an unknown device.
#define DEVICE_INIT_DT_GET | ( | node_id | ) |
#include <zephyr/device.h>
Get a init_entry reference from a devicetree node.
node_id | A devicetree node identifier |
#define DEVICE_INIT_GET | ( | dev_id | ) |
#include <zephyr/device.h>
Get a init_entry reference from a device identifier.
dev_id | Device identifier. |
#define DEVICE_NAME_GET | ( | 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().
dev_id | Device identifier. |
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.
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.
dev | a device in the set being iterated |
context | state used to support the visitor function |
|
inlinestatic |
#include <zephyr/device.h>
Get the device corresponding to a handle.
dev_handle | the device handle |
dev_handle
does not identify a device. 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.)
name | device name to search for. A null pointer, or a pointer to an empty string, will cause NULL to be returned. |
NULL
if the device is not found or if the device with that name's initialization function failed.
|
inlinestatic |
#include <zephyr/device.h>
Get the handle for a given device.
dev | the device for which a handle is desired. |
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.
dev | device to be initialized. |
-ENOENT | If device was not found - or isn't a deferred one. |
-errno | For other errors. |
|
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.
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. |
*count
device handles, or a null pointer if dev
does not have any dependency data. #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.
dev | pointer to the device in question. |
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. |
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.
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 . |
|
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.
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. |
count
device handles, or a null pointer if dev
does not have any dependency data. 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.
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 . |
|
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.
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 . |
*count
device handles, or a null pointer if dev
does not have any dependency data.