30  * @brief Device Model
31  * @defgroup device_model Device Model
40  * @brief Flag value used in lists of device dependencies to separate distinct
46  * @brief Flag value used in lists of device dependencies to indicate the end of
58  * @brief Type used to represent a "handle" for a device.
60  * Every @ref device has an associated handle. You can get a pointer to a
61  * @ref device from its handle and vice versa, but the handle uses less space
62  * than a pointer. The device.h API mainly uses handles to store lists of
66  * identify functionality that does not correspond to a Zephyr device, such as
74 /** @brief Flag value used to identify an unknown device. */
78  * @brief Expands to the name of a global device object.
80  * Return the full name of a device object symbol created by DEVICE_DEFINE(),
82  * global variable storing the device structure, not a pointer to the string in
83  * the @ref device.name field.
85  * It is meant to be used for declaring extern symbols pointing to device
86  * objects before using the DEVICE_GET macro to get the device object.
88  * This macro is normally only useful within device driver source code. In other
91  * @param dev_id Device identifier.
93  * @return The full name of the device object defined by device definition
107 /* Export device identifiers using the builtin name */
112  * @brief Create a device object and set it up for boot time initialization.
114  * This macro defines a @ref device that is automatically configured by the
116  * device is not being allocated from a devicetree node. If you are allocating a
117  * device from a devicetree node, use DEVICE_DT_DEFINE() or
120  * @param dev_id A unique token which is used in the name of the global device
122  * @param name A string name for the device, which will be stored in
123  * @ref device.name. This name can be used to look up the device with
126  * @param init_fn Pointer to the device's initialization function, which will be
128  * @param pm Pointer to the device's power management resources, a
129  * @ref pm_device, which will be stored in @ref device.pm field. Use `NULL` if
130  * the device does not use PM.
131  * @param data Pointer to the device's private mutable data, which will be
132  * stored in @ref device.data.
133  * @param config Pointer to the device's private constant data, which will be
134  * stored in @ref device.config.
135  * @param level The device's initialization level (PRE_KERNEL_1, PRE_KERNEL_2 or
137  * @param prio The device's priority within its initialization level. See
139  * @param api Pointer to the device's API structure. Can be `NULL`.
151  * This macro returns a string literal usable as a device's name from a
173  * @brief Create a device object from a devicetree node identifier and set it up
176  * This macro defines a @ref device that is automatically configured by the
177  * kernel during system initialization. The global device object's name as a C
178  * identifier is derived from the node's dependency ordinal. @ref device.name is
181  * The device is declared with extern visibility, so a pointer to a global
182  * device object can be obtained with `DEVICE_DT_GET(node_id)` from any source
183  * file that includes `<zephyr/device.h>` (even from extensions, when
188  * @param init_fn Pointer to the device's initialization function, which will be
190  * @param pm Pointer to the device's power management resources, a
191  * @ref pm_device, which will be stored in @ref device.pm. Use `NULL` if the
192  * device does not use PM.
193  * @param data Pointer to the device's private mutable data, which will be
194  * stored in @ref device.data.
195  * @param config Pointer to the device's private constant data, which will be
196  * stored in @ref device.config field.
197  * @param level The device's initialization level (PRE_KERNEL_1, PRE_KERNEL_2 or
199  * @param prio The device's priority within its initialization level. See
201  * @param api Pointer to the device's API structure. Can be `NULL`.
224  * @brief The name of the global device object for @p node_id
226  * Returns the name of the global device structure as a C identifier. The device
230  * This macro is normally only useful within device driver source code. In other
235  * @return The name of the device object as a C identifier
240  * @brief Get a @ref device reference from a devicetree node identifier.
242  * Returns a pointer to a device object created from a devicetree node, if any
243  * device was allocated by a driver.
245  * If no such device was allocated, this will fail at linker time. If you get an
247  * what happened. Check to make sure your device driver is being compiled,
252  * @return A pointer to the device object created for that node
257  * @brief Get a @ref device reference for an instance of a `DT_DRV_COMPAT`
263  * @return A pointer to the device object created for that instance
268  * @brief Get a @ref device reference from a devicetree compatible.
270  * If an enabled devicetree node has the given compatible and a device
271  * object was created from it, this returns a pointer to that device.
277  * If this returns non-NULL, the device must be checked for readiness
281  * @return a pointer to a device, or NULL
289  * @brief Get a @ref device reference from a devicetree compatible.
291  * If an enabled devicetree node has the given compatible and a device object
292  * was created from it, this returns a pointer to that device.
298  * If this returns non-NULL, the device must be checked for readiness before
302  * @return a pointer to a device
310  * @brief Utility macro to obtain an optional reference to a device.
317  * @return a @ref device reference for the node identifier, which may be `NULL`.
324  * @brief Obtain a pointer to a device object by name
326  * @details Return the address of a device object created by
329  * @param dev_id Device identifier.
331  * @return A pointer to the device object created by DEVICE_DEFINE()
336  * @brief Declare a static device object
338  * This macro can be used at the top-level to declare a device, such
343  * device's init or per-instance config function, as the init function
347  * @param dev_id Device identifier.
350 	static const struct device DEVICE_NAME_GET(dev_id)
363  * @brief Get a @ref init_entry reference from a device identifier.
365  * @param dev_id Device identifier.
367  * @return A pointer to the init_entry object created for that device
372  * @brief Runtime device dynamic structure (in RAM) per driver instance
381 	 * Device initialization return code (positive errno value).
383 	 * Device initialization functions return a negative errno code if they
389 	/** Indicates the device initialization function has been
409  * @brief Runtime device structure (in ROM) per driver instance
411 struct device {  struct
412 	/** Name of the device instance */
414 	/** Address of device instance config information */  argument
416 	/** Address of the API structure exposed by the device instance */  argument
418 	/** Address of the common device state */  argument
420 	/** Address of the device instance private data */
424 	 * Optional pointer to dependencies associated with the device.  argument
426 	 * This encodes a sequence of sets of device handles that have some
435 	 * Reference to the device PM resources (only available if
450  * @brief Get the handle for a given device  argument
452  * @param dev the device for which a handle is desired.
454  * @return the handle for the device, or DEVICE_HANDLE_NULL if the device does
457 static inline device_handle_t device_handle_get(const struct device *dev)  in device_handle_get()
460 	STRUCT_SECTION_START_EXTERN(device);  in device_handle_get()
466 		ret = 1 + (device_handle_t)(dev - STRUCT_SECTION_START(device));  in device_handle_get()
473  * @brief Get the device corresponding to a handle.
475  * @param dev_handle the device handle
477  * @return the device that has that handle, or a null pointer if @p dev_handle
478  * does not identify a device.
480 static inline const struct device *
483 	STRUCT_SECTION_START_EXTERN(device);  in device_from_handle()
484 	const struct device *dev = NULL;  in device_from_handle()
487 	STRUCT_SECTION_COUNT(device, &numdev);  in device_from_handle()
490 		dev = &STRUCT_SECTION_START(device)[dev_handle - 1];  in device_from_handle()
503  * device in the set.
507  * @param dev a device in the set being iterated
516 typedef int (*device_visitor_callback_t)(const struct device *dev,
520  * @brief Get the device handles for devicetree dependencies of this device.
522  * This function returns a pointer to an array of device handles. The length of
525  * The array contains a handle for each device that @p dev requires directly, as
529  * @param dev the device for which dependencies are desired.
532  * value may be set to zero if the device has no devicetree dependencies.
534  * @return a pointer to a sequence of @p count device handles, or a null pointer
538 device_required_handles_get(const struct device *dev, size_t *count)  in device_required_handles_get()
556  * @brief Get the device handles for injected dependencies of this device.
558  * This function returns a pointer to an array of device handles. The length of
561  * The array contains a handle for each device that @p dev manually injected as
565  * @param dev the device for which injected dependencies are desired.
568  * value may be set to zero if the device has no devicetree dependencies.
570  * @return a pointer to a sequence of @p *count device handles, or a null
574 device_injected_handles_get(const struct device *dev, size_t *count)  in device_injected_handles_get()
599  * @brief Get the set of handles that this device supports.
601  * This function returns a pointer to an array of device handles. The length of
604  * The array contains a handle for each device that @p dev "supports" -- that
609  * @param dev the device for which supports are desired.
614  * @return a pointer to a sequence of @p *count device handles, or a null
618 device_supported_handles_get(const struct device *dev, size_t *count)  in device_supported_handles_get()
647  * @brief Visit every device that @p dev directly requires.
650  * another device; for example an I2C-based sensor driver will require an I2C
656  * include making sure required devices are ready before the requiring device is
657  * used, and releasing them when the requiring device is no longer needed.
666  * @param dev a device of interest. The devices that this device depends on will
668  * @param visitor_cb the function that should be invoked on each device in the
676 int device_required_foreach(const struct device *dev,
681  * @brief Visit every device that @p dev directly supports.
684  * another device; for example an I2C controller will support an I2C-based
699  * @param dev a device of interest. The devices that this device supports
701  * @param visitor_cb the function that should be invoked on each device in the
709 int device_supported_foreach(const struct device *dev,
716  * @brief Get a @ref device reference from its @ref device.name field.
718  * This function iterates through the devices on the system. If a device with
719  * the given @p name field is found, and that device initialized successfully at
720  * boot time, this function returns a pointer to the device.
722  * If no device has the given @p name, this function returns `NULL`.
724  * This function also returns NULL when a device is found, but it failed to
726  * breakpoint on your device driver's initialization function.)
728  * @param name device name to search for. A null pointer, or a pointer to an
731  * @return pointer to device structure with the given name; `NULL` if the device
732  * is not found or if the device with that name's initialization function
735 __syscall const struct device *device_get_binding(const char *name);
745 size_t z_device_get_all_static(const struct device **devices);
748  * @brief Verify that a device is ready for use.
750  * Indicates whether the provided device pointer is for a device known to be
753  * This can be used with device pointers captured from DEVICE_DT_GET(), which
755  * this means that the device has been successfully initialized.
757  * @param dev pointer to the device in question.
759  * @retval true If the device is ready for use.
760  * @retval false If the device is not ready for use or if a NULL device pointer
763 __syscall bool device_is_ready(const struct device *dev);
766  * @brief Initialize a device.
768  * A device whose initialization was deferred (by marking it as
772  * initialization deferred device that failed initialization with this call.
774  * @param dev device to be initialized.
776  * @retval -ENOENT If device was not found - or isn't a deferred one.
779 __syscall int device_init(const struct device *dev);
788  * @brief Synthesize a unique name for the device state associated with
794  * @brief Utility macro to define and initialize the device state.
796  * @param dev_id Device identifier.
805  * @brief Synthesize the name of the object that holds device ordinal and
808  * @param dev_id Device identifier.
820 /** @brief Linker section were device dependencies are placed. */
831  * @brief Define device dependencies.
833  * Initial build provides a record that associates the device object with its
885  * @brief Devicetree node labels associated with a device
897  * @brief Devicetree metadata associated with a device
905 	 * @brief Node labels associated with the device
912  * @brief Get a @ref device reference from a devicetree node label.
916  * 1. a device was defined from a devicetree node, for example
919  * 3. the device initialized successfully at boot time,
921  * then this function returns a pointer to the device. Otherwise, it
925  * @return a device reference for a device created from a node with that
926  *         node label, or NULL if either no such device exists or the device
929 __syscall const struct device *device_get_by_dt_nodelabel(const char *nodelabel);
932  * @brief Get the devicetree node labels associated with a device
933  * @param dev device whose metadata to look up
937 device_get_dt_nodelabels(const struct device *dev)  in device_get_dt_nodelabels()
954  * @brief Name of the identifier for a device's DT metadata structure
955  * @param dev_id device identifier
961  *        saved for a device.
966  * @brief Initialize an entry in the device DT node label lookup table
985  * @brief Init sub-priority of the device
996  * @brief Maximum device name length.
1004  * @brief Compile time check for device name length
1006  * @param name Device name.
1013  * @brief Initializer for @ref device.
1015  * @param name_ Name of the device.
1017  * @param data_ Reference to device data.
1018  * @param config_ Reference to device config.
1019  * @param api_ Reference to device API ops.
1020  * @param state_ Reference to device state.
1021  * @param deps_ Reference to device dependencies.
1023  * @param dev_id_ Device identifier token, as passed to Z_DEVICE_BASE_DEFINE
1053  * @brief Device section name (used for sorting purposes).
1062  * @brief Define a @ref device
1064  * @param node_id Devicetree node id for the device (DT_INVALID_NODE if a
1065  * software device).
1066  * @param dev_id Device identifier (used to name the defined @ref device).
1067  * @param name Name of the device.
1068  * @param pm Reference to @ref pm_device_base associated with the device.
1070  * @param data Reference to device data.
1071  * @param config Reference to device config.
1074  * @param api Reference to device API.
1082 		device, COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (device_mutable), (device)),     \
1098  * @brief Define the init entry for a device.
1100  * @param node_id Devicetree node id for the device (DT_INVALID_NODE if a
1101  * software device).
1102  * @param dev_id Device identifier.
1103  * @param init_fn_ Device init function.
1142  * @brief Define a @ref device and all other required objects.
1144  * This is the common macro used to define @ref device objects. It can be used
1147  * @param node_id Devicetree node id for the device (DT_INVALID_NODE if a
1148  * software device).
1149  * @param dev_id Device identifier (used to name the defined @ref device).
1150  * @param name Name of the device.
1151  * @param init_fn Device init function.
1152  * @param pm Reference to @ref pm_device_base associated with the device.
1154  * @param data Reference to device data.
1155  * @param config Reference to device config.
1158  * @param api Reference to device API.
1159  * @param state Reference to device state.
1185  * @brief Declare a device for each status "okay" devicetree node.
1190  * This is only "maybe" a device because some nodes have status "okay", but
1191  * don't have a corresponding @ref device allocated. There's no way to figure
1196 			   (const)) struct device DEVICE_DT_NAME_GET(node_id);
1206  * @brief Wrapper macro for declaring device API structs inside iterable sections.
1208  * @param _class The device API class.
1214  * @brief Expands to the pointer of a device's API for a given class.
1216  * @param _class The device API class.
1217  * @param _dev The device instance pointer.
1219  * @return the pointer to the device API.
1225  *        a device is of a particular class.
1227  * @param _class The device API class.
1228  * @param _dev The device instance pointer.
1230  * @retval true If the device is of the given class
1231  * @retval false If the device is not of the given class
1245 #include <zephyr/syscalls/device.h>