From 8d04deb2d9133cddaa5dfee49037a82c0d109a0c Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Thu, 23 Dec 2021 17:36:13 +0100 Subject: [PATCH] device: improve (z_)device_is_ready docs Improve the documentation so that both z_device_is_ready and device_is_ready are consistent with each other. Information about PM has been removed since device_is_ready does not take into account the PM status of a device. Signed-off-by: Gerard Marull-Paretas --- include/device.h | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/include/device.h b/include/device.h index 255848751ab..f06cc06c78c 100644 --- a/include/device.h +++ b/include/device.h @@ -733,11 +733,19 @@ __syscall const struct device *device_get_binding(const char *name); */ size_t z_device_get_all_static(const struct device * *devices); -/** @brief Determine whether a device has been successfully initialized. +/** + * @brief Verify that a device is ready for use. + * + * This is the implementation underlying device_is_ready(), without the overhead + * of a syscall wrapper. * * @param dev pointer to the device in question. * - * @return true if and only if the device is available for use. + * @retval true If the device is ready for use. + * @retval false If the device is not ready for use or if a NULL device pointer + * is passed as argument. + * + * @see device_is_ready() */ bool z_device_is_ready(const struct device *dev); @@ -748,13 +756,12 @@ bool z_device_is_ready(const struct device *dev); * * 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, but it may - * take on further conditions (e.g. is not powered down). + * this means that the device has been successfully initialized. * * @param dev pointer to the device in question. * - * @retval true if the device is ready for use. - * @retval false if the device is not ready for use or if a NULL device pointer + * @retval true If the device is ready for use. + * @retval false If the device is not ready for use or if a NULL device pointer * is passed as argument. */ __syscall bool device_is_ready(const struct device *dev);