25  * @brief Device Model
26  * @defgroup device_model Device Model
31  * @brief Type used to represent a "handle" for a device.
33  * Every @ref device has an associated handle. You can get a pointer to a
34  * @ref device from its handle and vice versa, but the handle uses less space
35  * than a pointer. The device.h API mainly uses handles to store lists of
39  * identify functionality that does not correspond to a Zephyr device, such as
48  * @brief Flag value used in lists of device handles to separate distinct
56  * @brief Flag value used in lists of device handles to indicate the end of the
63 /** @brief Flag value used to identify an unknown device. */
67  * @brief Expands to the name of a global device object.
69  * Return the full name of a device object symbol created by DEVICE_DEFINE(),
71  * global variable storing the device structure, not a pointer to the string in
72  * the @ref device.name field.
74  * It is meant to be used for declaring extern symbols pointing to device
75  * objects before using the DEVICE_GET macro to get the device object.
77  * This macro is normally only useful within device driver source code. In other
80  * @param dev_id Device identifier.
82  * @return The full name of the device object defined by device definition
98  * @brief Create a device object and set it up for boot time initialization.
100  * This macro defines a @ref device that is automatically configured by the
102  * device is not being allocated from a devicetree node. If you are allocating a
103  * device from a devicetree node, use DEVICE_DT_DEFINE() or
106  * @param dev_id A unique token which is used in the name of the global device
108  * @param name A string name for the device, which will be stored in
109  * @ref device.name. This name can be used to look up the device with
112  * @param init_fn Pointer to the device's initialization function, which will be
114  * @param pm Pointer to the device's power management resources, a
115  * @ref pm_device, which will be stored in @ref device.pm field. Use `NULL` if
116  * the device does not use PM.
117  * @param data Pointer to the device's private mutable data, which will be
118  * stored in @ref device.data.
119  * @param config Pointer to the device's private constant data, which will be
120  * stored in @ref device.config.
121  * @param level The device's initialization level. See @ref sys_init for
123  * @param prio The device's priority within its initialization level. See
125  * @param api Pointer to the device's API structure. Can be `NULL`.
137  * This macro returns a string literal usable as a device's name from a
149  * @brief Create a device object from a devicetree node identifier and set it up
152  * This macro defines a @ref device that is automatically configured by the
153  * kernel during system initialization. The global device object's name as a C
154  * identifier is derived from the node's dependency ordinal. @ref device.name is
157  * The device is declared with extern visibility, so a pointer to a global
158  * device object can be obtained with `DEVICE_DT_GET(node_id)` from any source
159  * file that includes `<zephyr/device.h>`. Before using the pointer, the
163  * @param init_fn Pointer to the device's initialization function, which will be
165  * @param pm Pointer to the device's power management resources, a
166  * @ref pm_device, which will be stored in @ref device.pm. Use `NULL` if the
167  * device does not use PM.
168  * @param data Pointer to the device's private mutable data, which will be
169  * stored in @ref device.data.
170  * @param config Pointer to the device's private constant data, which will be
171  * stored in @ref device.config field.
172  * @param level The device's initialization level. See SYS_INIT() for details.
173  * @param prio The device's priority within its initialization level. See
175  * @param api Pointer to the device's API structure. Can be `NULL`.
198  * @brief The name of the global device object for @p node_id
200  * Returns the name of the global device structure as a C identifier. The device
204  * This macro is normally only useful within device driver source code. In other
209  * @return The name of the device object as a C identifier
214  * @brief Get a @ref device reference from a devicetree node identifier.
216  * Returns a pointer to a device object created from a devicetree node, if any
217  * device was allocated by a driver.
219  * If no such device was allocated, this will fail at linker time. If you get an
221  * what happened. Check to make sure your device driver is being compiled,
226  * @return A pointer to the device object created for that node
231  * @brief Get a @ref device reference for an instance of a `DT_DRV_COMPAT`
237  * @return A pointer to the device object created for that instance
242  * @brief Get a @ref device reference from a devicetree compatible.
244  * If an enabled devicetree node has the given compatible and a device
245  * object was created from it, this returns a pointer to that device.
251  * If this returns non-NULL, the device must be checked for readiness
255  * @return a pointer to a device, or NULL
263  * @brief Get a @ref device reference from a devicetree compatible.
265  * If an enabled devicetree node has the given compatible and a device object
266  * was created from it, this returns a pointer to that device.
272  * If this returns non-NULL, the device must be checked for readiness before
276  * @return a pointer to a device
284  * @brief Utility macro to obtain an optional reference to a device.
291  * @return a @ref device reference for the node identifier, which may be `NULL`.
298  * @brief Obtain a pointer to a device object by name
300  * @details Return the address of a device object created by
303  * @param dev_id Device identifier.
305  * @return A pointer to the device object created by DEVICE_DEFINE()
310  * @brief Declare a static device object
312  * This macro can be used at the top-level to declare a device, such
317  * device's init or per-instance config function, as the init function
321  * @param dev_id Device identifier.
324 	static const struct device DEVICE_NAME_GET(dev_id)
337  * @brief Get a @ref init_entry reference from a device identifier.
339  * @param dev_id Device identifier.
341  * @return A pointer to the init_entry object created for that device
346  * @brief Runtime device dynamic structure (in RAM) per driver instance
355 	 * Device initialization return code (positive errno value).
357 	 * Device initialization functions return a negative errno code if they
363 	/** Indicates the device initialization function has been
378  * @brief Runtime device structure (in ROM) per driver instance
380 struct device {  struct
381 	/** Name of the device instance */
383 	/** Address of device instance config information */  argument
385 	/** Address of the API structure exposed by the device instance */  argument
387 	/** Address of the common device state */  argument
389 	/** Address of the device instance private data */
392 	 * Optional pointer to handles associated with the device.  argument
394 	 * This encodes a sequence of sets of device handles that have some
402 	 * Reference to the device PM resources (only available if
410  * @brief Get the handle for a given device
412  * @param dev the device for which a handle is desired.
414  * @return the handle for the device, or DEVICE_HANDLE_NULL if the device does
417 static inline device_handle_t device_handle_get(const struct device *dev)  in device_handle_get()
420 	STRUCT_SECTION_START_EXTERN(device);  in device_handle_get()
426 		ret = 1 + (device_handle_t)(dev - STRUCT_SECTION_START(device));  in device_handle_get()
433  * @brief Get the device corresponding to a handle.
435  * @param dev_handle the device handle
437  * @return the device that has that handle, or a null pointer if @p dev_handle
438  * does not identify a device.
440 static inline const struct device *
443 	STRUCT_SECTION_START_EXTERN(device);  in device_from_handle()
444 	const struct device *dev = NULL;  in device_from_handle()
447 	STRUCT_SECTION_COUNT(device, &numdev);  in device_from_handle()
450 		dev = &STRUCT_SECTION_START(device)[dev_handle - 1];  in device_from_handle()
461  * device in the set.
465  * @param dev a device in the set being iterated
474 typedef int (*device_visitor_callback_t)(const struct device *dev,
478  * @brief Get the device handles for devicetree dependencies of this device.
480  * This function returns a pointer to an array of device handles. The length of
483  * The array contains a handle for each device that @p dev requires directly, as
487  * @param dev the device for which dependencies are desired.
490  * value may be set to zero if the device has no devicetree dependencies.
492  * @return a pointer to a sequence of @p count device handles, or a null pointer
496 device_required_handles_get(const struct device *dev, size_t *count)  in device_required_handles_get()
514  * @brief Get the device handles for injected dependencies of this device.
516  * This function returns a pointer to an array of device handles. The length of
519  * The array contains a handle for each device that @p dev manually injected as
523  * @param dev the device for which injected dependencies are desired.
526  * value may be set to zero if the device has no devicetree dependencies.
528  * @return a pointer to a sequence of @p *count device handles, or a null
532 device_injected_handles_get(const struct device *dev, size_t *count)  in device_injected_handles_get()
557  * @brief Get the set of handles that this device supports.
559  * This function returns a pointer to an array of device handles. The length of
562  * The array contains a handle for each device that @p dev "supports" -- that
567  * @param dev the device for which supports are desired.
572  * @return a pointer to a sequence of @p *count device handles, or a null
576 device_supported_handles_get(const struct device *dev, size_t *count)  in device_supported_handles_get()
605  * @brief Visit every device that @p dev directly requires.
608  * another device; for example an I2C-based sensor driver will require an I2C
614  * include making sure required devices are ready before the requiring device is
615  * used, and releasing them when the requiring device is no longer needed.
624  * @param dev a device of interest. The devices that this device depends on will
626  * @param visitor_cb the function that should be invoked on each device in the
634 int device_required_foreach(const struct device *dev,
639  * @brief Visit every device that @p dev directly supports.
642  * another device; for example an I2C controller will support an I2C-based
657  * @param dev a device of interest. The devices that this device supports
659  * @param visitor_cb the function that should be invoked on each device in the
667 int device_supported_foreach(const struct device *dev,
672  * @brief Get a @ref device reference from its @ref device.name field.
674  * This function iterates through the devices on the system. If a device with
675  * the given @p name field is found, and that device initialized successfully at
676  * boot time, this function returns a pointer to the device.
678  * If no device has the given @p name, this function returns `NULL`.
680  * This function also returns NULL when a device is found, but it failed to
682  * breakpoint on your device driver's initialization function.)
684  * @param name device name to search for. A null pointer, or a pointer to an
687  * @return pointer to device structure with the given name; `NULL` if the device
688  * is not found or if the device with that name's initialization function
691 __syscall const struct device *device_get_binding(const char *name);
701 size_t z_device_get_all_static(const struct device **devices);
704  * @brief Verify that a device is ready for use.
709  * @param dev pointer to the device in question.
711  * @retval true If the device is ready for use.
712  * @retval false If the device is not ready for use or if a NULL device pointer
717 bool z_device_is_ready(const struct device *dev);
720  * @brief Verify that a device is ready for use.
722  * Indicates whether the provided device pointer is for a device known to be
725  * This can be used with device pointers captured from DEVICE_DT_GET(), which
727  * this means that the device has been successfully initialized.
729  * @param dev pointer to the device in question.
731  * @retval true If the device is ready for use.
732  * @retval false If the device is not ready for use or if a NULL device pointer
735 __syscall bool device_is_ready(const struct device *dev);
737 static inline bool z_impl_device_is_ready(const struct device *dev)  in z_impl_device_is_ready()
749  * @brief Synthesize a unique name for the device state associated with
755  * @brief Utility macro to define and initialize the device state.
757  * @param dev_id Device identifier.
764  * @brief Synthesize the name of the object that holds device ordinal and
767  * @param dev_id Device identifier.
779 /** @brief Linker section were device handles are placed. */
790  * @brief Define device handles.
792  * Initial build provides a record that associates the device object with its
842  * @brief Maximum device name length.
850  * @brief Compile time check for device name length
852  * @param name Device name.
859  * @brief Initializer for @ref device.
861  * @param name_ Name of the device.
863  * @param data_ Reference to device data.
864  * @param config_ Reference to device config.
865  * @param api_ Reference to device API ops.
866  * @param state_ Reference to device state.
867  * @param handles_ Reference to device handles.
881  * @brief Device section name (used for sorting purposes).
890  * @brief Define a @ref device
892  * @param node_id Devicetree node id for the device (DT_INVALID_NODE if a
893  * software device).
894  * @param dev_id Device identifier (used to name the defined @ref device).
895  * @param name Name of the device.
896  * @param pm Reference to @ref pm_device associated with the device.
898  * @param data Reference to device data.
899  * @param config Reference to device config.
902  * @param api Reference to device API.
908 	const STRUCT_SECTION_ITERABLE_NAMED(device,                            \
914  * @brief Define the init entry for a device.
916  * @param dev_id Device identifier.
917  * @param init_fn_ Device init function.
930  * @brief Define a @ref device and all other required objects.
932  * This is the common macro used to define @ref device objects. It can be used
935  * @param node_id Devicetree node id for the device (DT_INVALID_NODE if a
936  * software device).
937  * @param dev_id Device identifier (used to name the defined @ref device).
938  * @param name Name of the device.
939  * @param init_fn Device init function.
940  * @param pm Reference to @ref pm_device associated with the device.
942  * @param data Reference to device data.
943  * @param config Reference to device config.
946  * @param api Reference to device API.
947  * @param state Reference to device state.
963  * @brief Declare a device for each status "okay" devicetree node.
968  * This is only "maybe" a device because some nodes have status "okay", but
969  * don't have a corresponding @ref device allocated. There's no way to figure
973 	extern const struct device DEVICE_DT_NAME_GET(node_id);
984 #include <syscalls/device.h>