11  * @brief Device Driver APIs
12  * @defgroup io_interfaces Device Driver APIs
24  * @brief Device Model APIs
25  * @defgroup device_model Device Model APIs
31 #include <pm/device.h>
43  * device, such as the system clock or a SYS_INIT() function.
47 /** @brief Flag value used in lists of device handles to separate
54 /** @brief Flag value used in lists of device handles to indicate the
61 /** @brief Flag value used to identify an unknown device. */
69  * @brief Expands to the full name of a global device object
71  * @details Return the full name of a device object symbol created by
74  * It is meant to be used for declaring extern symbols pointing on device
75  * objects before using the DEVICE_GET macro to get the device object.
79  * @return The expanded name of the device object created by DEVICE_DEFINE()
87  * and define device PM control function.
90  * (@p pm_control_fn), no API (@p api_ptr), and a device name derived from
101  * @brief Create device object and set it up for boot time initialization,
102  * with the option to pm_control. In case of Device Idle Power
103  * Management is enabled, make sure the device is in suspended state after
106  * @details This macro defines a device object that is automatically
111  * @param dev_name Device name. This must be less than Z_DEVICE_MAX_NAME_LEN
123  * @param data_ptr Pointer to the device's private data.
148  * @details This macro returns a string literal usable as a device name
163  * @details This macro defines a device object that is automatically
164  * configured by the kernel during system initialization. The device
169  * The device is declared with extern visibility, so device objects
181  * @param data_ptr Pointer to the device's private data.
220  * @brief The name of the struct device object for @p node_id
222  * @details Return the full name of a device object symbol created by
225  * It is meant to be used for declaring extern symbols pointing on device
226  * objects before using the DEVICE_DT_GET macro to get the device object.
230  * @return The expanded name of the device object created by
238  * @brief Obtain a pointer to a device object by @p node_id
240  * @details Return the address of a device object created by
245  * @return A pointer to the device object created by DEVICE_DT_DEFINE()
251  * @brief Obtain a pointer to a device object for an instance of a
261  * @brief Obtain a pointer to a device object by devicetree compatible
264  * device object was created from it, this returns that device.
270  * If this returns non-NULL, the device must be checked for readiness
274  * @return a pointer to a device, or NULL
284  * @brief Obtain a pointer to a device object by devicetree compatible
287  * device object was created from it, this returns that device.
293  * If this returns non-NULL, the device must be checked for readiness
297  * @return a pointer to a device
307  * @brief Obtain a pointer to a device object by name
309  * @details Return the address of a device object created by
314  * @return A pointer to the device object created by DEVICE_DEFINE()
320  * @brief Declare a static device object
322  * This macro can be used at the top-level to declare a device, such
327  * device's init or per-instance config function, as the init function
331  * @param name Device name
333 #define DEVICE_DECLARE(name) static const struct device DEVICE_NAME_GET(name)
336  * @brief Runtime device dynamic structure (in RAM) per driver instance
344 	/** Non-negative result of initializing the device.
346 	 * The absolute value returned when the device initialization
353 	/** Indicates the device initialization function has been
365  * @brief Runtime device structure (in ROM) per driver instance
367 struct device {  struct
368 	/** Name of the device instance */
370 	/** Address of device instance config information */  argument
372 	/** Address of the API structure exposed by the device instance */  argument
374 	/** Address of the common device state */  argument
376 	/** Address of the device instance private data */
378 	/** optional pointer to handles associated with the device.  argument
380 	 * This encodes a sequence of sets of device handles that have
389 	/** Pointer to device instance power management data */
395  * @brief Get the handle for a given device
397  * @param dev the device for which a handle is desired.
399  * @return the handle for the device, or DEVICE_HANDLE_NULL if the
400  * device does not have an associated handle.
403 device_handle_get(const struct device *dev)  in device_handle_get()
406 	extern const struct device __device_start[];  in device_handle_get()
419  * @brief Get the device corresponding to a handle.
421  * @param dev_handle the device handle
423  * @return the device that has that handle, or a null pointer if @p
424  * dev_handle does not identify a device.
426 static inline const struct device *
429 	extern const struct device __device_start[];  in device_from_handle()
430 	extern const struct device __device_end[];  in device_from_handle()
431 	const struct device *dev = NULL;  in device_from_handle()
446  * device in the set.
450  * @param dev a device in the set being iterated
457 typedef int (*device_visitor_callback_t)(const struct device *dev, void *context);
460  * @brief Get the set of handles for devicetree dependencies of this device.
462  * These are the device dependencies inferred from devicetree.
464  * @param dev the device for which dependencies are desired.
470  * @return a pointer to a sequence of @p *count device handles, or a null
474 device_required_handles_get(const struct device *dev,  in device_required_handles_get()
493  * @brief Visit every device that @p dev directly requires.
496  * another device; for example an I2C-based sensor driver will require an I2C
502  * include making sure required devices are ready before the requiring device
503  * is used, and releasing them when the requiring device is no longer needed.
512  * @param dev a device of interest. The devices that this device depends on
516  * @param visitor_cb the function that should be invoked on each device in the
525 int device_required_foreach(const struct device *dev,
530  * @brief Retrieve the device structure for a driver by name
532  * @details Device objects are created via the DEVICE_DEFINE() macro and
534  * it can use this function to retrieve the device structure of the lower level
537  * @param name device name to search for. A null pointer, or a pointer to an
540  * @return pointer to device structure; NULL if not found or cannot be used.
542 __syscall const struct device *device_get_binding(const char *name);
552 size_t z_device_get_all_static(const struct device * *devices);
554 /** @brief Determine whether a device has been successfully initialized.
556  * @param dev pointer to the device in question.
558  * @return true if and only if the device is available for use.
560 bool z_device_ready(const struct device *dev);
562 /** @brief Determine whether a device is ready for use
567  * @param dev pointer to the device in question.
571 static inline int z_device_usable_check(const struct device *dev)  in z_device_usable_check()
576 /** @brief Determine whether a device is ready for use.
578  * This checks whether a device can be used, returning 0 if it can, and
581  * @retval 0 if the device is usable.
582  * @retval -ENODEV if the device has not been initialized, the device pointer
585  * make the device unusable.
587 __syscall int device_usable_check(const struct device *dev);
589 static inline int z_impl_device_usable_check(const struct device *dev)  in z_impl_device_usable_check()
594 /** @brief Verify that a device is ready for use.
596  * Indicates whether the provided device pointer is for a device known to be
599  * This can be used with device pointers captured from DEVICE_DT_GET(), which
601  * this means that the device has been successfully initialized, but it may
604  * @param dev pointer to the device in question.
606  * @retval true if the device is ready for use.
607  * @retval false if the device is not ready for use or if a NULL device pointer
610 static inline bool device_is_ready(const struct device *dev)  in device_is_ready()
629 /* Synthesize a unique name for the device state associated with
634 /** Synthesize the name of the object that holds device ordinal and
655  * @brief Utility macro to define and initialize the device state.
657  * @param node_id Devicetree node id of the device.
658  * @param dev_name Device name.
666 /* If device power management is enabled, this macro defines a pointer to a
667  * device in the z_pm_device_slots region. When invoked for each device, this
668  * will effectively result in a device pointer array with the same size of the
669  * actual devices list. This is used internally by the device PM subsystem to
674 	static const Z_DECL_ALIGN(struct device *)			\
681 /* Construct objects that are referenced from struct device. These
734 /* Initial build provides a record that associates the device object
791 		const Z_DECL_ALIGN(struct device)			\
813 #include <syscalls/device.h>