This is an automated email from the ASF dual-hosted git repository. janc pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/mynewt-core.git
commit d9d679b376b4beb5de6823c248727d681c71f55a Author: Wojciech Pietraszewski <[email protected]> AuthorDate: Wed Jun 26 15:57:17 2024 +0200 kernel/os_dev: Update doxygen comments in the header file Adds missing documentation for functions and callbacks. Adjusts the formatting for better readability. --- kernel/os/include/os/os_dev.h | 151 +++++++++++++++++++++++++++++------------- 1 file changed, 106 insertions(+), 45 deletions(-) diff --git a/kernel/os/include/os/os_dev.h b/kernel/os/include/os/os_dev.h index 18689a24d..2d35ba11f 100644 --- a/kernel/os/include/os/os_dev.h +++ b/kernel/os/include/os/os_dev.h @@ -37,12 +37,13 @@ extern "C" { struct os_dev; -/* - * Initialization order, defines when a device should be initialized - * by the Mynewt kernel. - * +/** + * @defgroup OSDevice_init_order Initialization order + * Defines when a device should be initialized by the Mynewt kernel. + * @{ */ -/* Primary is initialized during OS init, after the initialization + +/** Primary is initialized during OS init, after the initialization * of OS memory and architecture specific functions, but before the * OS gets started. */ @@ -58,8 +59,16 @@ struct os_dev; */ #define OS_DEV_INIT_F_CRITICAL (1 << 0) +/** Default priority for device initialization. */ #define OS_DEV_INIT_PRIO_DEFAULT (0xff) +/** @} */ + +/** + * @defgroup OSDevice_status_flags Status flags + * @{ + */ + /** Device is initialized, and ready to be accessed. */ #define OS_DEV_F_STATUS_READY (1 << 0) /** Device is open */ @@ -72,20 +81,63 @@ struct os_dev; */ #define OS_DEV_F_INIT_CRITICAL (1 << 3) +/** @} */ + /** * Initialize a device. * - * @param dev The device to initialize. - * @param arg User defined argument to pass to the device initalization + * @param dev The device to initialize. + * @param arg User defined argument to pass to the device + * initialization. * - * @return 0 on success, non-zero error code on failure. + * @return 0 on success; + * non-zero error code on failure. */ typedef int (*os_dev_init_func_t)(struct os_dev *dev, void *arg); +/** + * Open a device. + * + * @param dev The device to open. + * @param timo The timeout to open the device. + * @param arg User defined argument to pass to the device + * open callback. + * + * @return 0 on success; + * non-zero error code on failure. + */ typedef int (*os_dev_open_func_t)(struct os_dev *dev, uint32_t timo, void *arg); + +/** + * Suspend a device. + * + * @param dev The device to suspend. + * @param suspend_t Specifies when the device should be suspended. + * @param force Whether to force the suspend operation. + * + * @return 0 on success; + * non-zero error code on failure. + */ typedef int (*os_dev_suspend_func_t)(struct os_dev *dev, os_time_t suspend_t, int force); +/** + * Resume a device. + * + * @param dev The device to resume. + * + * @return 0 on success; + * non-zero error code on failure. + */ typedef int (*os_dev_resume_func_t)(struct os_dev *dev); + +/** + * Close a device. + * + * @param dev The device to close. + * + * @return 0 on success; + * non-zero error code on failure. + */ typedef int (*os_dev_close_func_t)(struct os_dev *dev); /** @@ -116,9 +168,7 @@ struct os_dev_handlers { os_dev_close_func_t od_close; }; -/* - * Device structure. - */ +/** Device structure. */ struct os_dev { /** Device handlers. Implementation of base device functions. */ struct os_dev_handlers od_handlers; @@ -139,9 +189,11 @@ struct os_dev { uint8_t od_flags; /** Device name */ const char *od_name; + /** Next device in the list. */ STAILQ_ENTRY(os_dev) od_next; }; +/** Set the open and close handlers for a device. */ #define OS_DEV_SETHANDLERS(__dev, __open, __close) \ (__dev)->od_handlers.od_open = (__open); \ (__dev)->od_handlers.od_close = (__close); @@ -150,37 +202,40 @@ struct os_dev { /** * Suspend the operation of the device. * - * @param dev The device to suspend. - * @param suspend_t When the device should be suspended. - * @param force Whether not the suspend operation can be overridden by the - * device handler. + * @param dev The device to suspend. + * @param suspend_t When the device should be suspended. + * @param force Whether the suspend operation can be + * overridden by the device handler. * - * @return 0 on success, non-zero error code on failure. + * @return 0 on success; + * non-zero error code on failure. */ int os_dev_suspend(struct os_dev *dev, os_time_t suspend_t, uint8_t force); /** * Resume the device operation. * - * @param dev The device to resume + * @param dev The device to resume * - * @return 0 on success, non-zero error code on failure. + * @return 0 on success; + * non-zero error code on failure. */ int os_dev_resume(struct os_dev *dev); /** * Create a new device in the kernel. * - * @param dev The device to create. - * @param name The name of the device to create. - * @param stage The stage to initialize that device to. - * @param priority The priority of initializing that device - * @param od_init The initialization function to call for this - * device. - * @param arg The argument to provide this device initialization - * function. + * @param dev The device to create. + * @param name The name of the device to create. + * @param stage The stage to initialize that device to. + * @param priority The priority of initializing that device + * @param od_init The initialization function to call for this + * device. + * @param arg The argument to provide this device + * initialization function. * - * @return 0 on success, non-zero on failure. + * @return 0 on success; + * non-zero on failure. */ int os_dev_create(struct os_dev *dev, const char *name, uint8_t stage, uint8_t priority, os_dev_init_func_t od_init, void *arg); @@ -188,21 +243,23 @@ int os_dev_create(struct os_dev *dev, const char *name, uint8_t stage, /** * Lookup a device by name. * - * WARNING: This should be called before any locking on the device is done, or + * @warning This should be called before any locking on the device is done, or * the device list itself is modified in any context. There is no locking. * - * @param name The name of the device to look up. + * @param name The name of the device to look up. * - * @return A pointer to the device corresponding to name, or NULL if not found. + * @return A pointer to the device corresponding to name; + * NULL if not found. */ struct os_dev *os_dev_lookup(const char *name); /** * Initialize all devices for a given state. * - * @param stage The stage to initialize. + * @param stage The stage to initialize. * - * @return 0 on success, non-zero on failure. + * @return 0 on success; + * non-zero on failure. */ int os_dev_initialize_all(uint8_t stage); @@ -210,38 +267,42 @@ int os_dev_initialize_all(uint8_t stage); /** * Suspend all devices. * - * @param suspend_t The number of ticks to suspend this device for - * @param force Whether or not to force suspending the device + * @param suspend_t The number of ticks to suspend this device for + * @param force Whether or not to force suspending the device * - * @return 0 on success, or a non-zero error code if one of the devices - * returned it. + * @return 0 on success; + * a non-zero error code if one of the devices + * returned it. */ int os_dev_suspend_all(os_time_t suspend_t, uint8_t force); /** * Resume all the devices that were suspended. * - * @return 0 on success, -1 if any of the devices have failed to resume. + * @return 0 on success; + * -1 if any of the devices have failed to resume. */ int os_dev_resume_all(void); /** * Open a device. * - * @param dev The device to open - * @param timo The timeout to open the device, if not specified. - * @param arg The argument to the device open() call. + * @param devname The device to open + * @param timo The timeout to open the device, if not specified. + * @param arg The argument to the device open() call. * - * @return 0 on success, non-zero on failure. + * @return 0 on success; + * non-zero on failure. */ struct os_dev *os_dev_open(const char *devname, uint32_t timo, void *arg); /** * Close a device. * - * @param dev The device to close + * @param dev The device to close * - * @return 0 on success, non-zero on failure. + * @return 0 on success; + * non-zero on failure. */ int os_dev_close(struct os_dev *dev); @@ -256,8 +317,8 @@ void os_dev_reset(void); /** * Walk through all devices, calling callback for every device. * - * @param walk_func Function to call - * @aparm arg Argument to pass to walk_func + * @param walk_func Function to call + * @param arg Argument to pass to walk_func */ void os_dev_walk(int (*walk_func)(struct os_dev *walk_func_dev, void *walk_func_arg), void *arg);
