From 1977ac3ce26cfe1c884e892f6288b296879dcb88 Mon Sep 17 00:00:00 2001 From: Peter Bigot Date: Wed, 5 Feb 2020 03:59:41 -0600 Subject: [PATCH] lib: os: onoff: documentation clarifications Note that the client structure must be reinitialized before each use, and make more clear that its internal fields are not part of the public API. Signed-off-by: Peter Bigot --- include/sys/onoff.h | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/include/sys/onoff.h b/include/sys/onoff.h index 363e62d08d4..d8629d6a549 100644 --- a/include/sys/onoff.h +++ b/include/sys/onoff.h @@ -270,9 +270,12 @@ typedef void (*onoff_client_callback)(struct onoff_service *srv, * * when operation completion is posted (signalled or callback * invoked). * - * Only the result field is intended for direct use by clients, and it - * is available for inspection only after control reverts to the - * client. + * After control has reverted to the client the state object must be + * reinitialized for the next operation. + * + * The content of this structure is not public API: all configuration + * and inspection should be done with functions like + * onoff_client_init_callback() and onoff_client_fetch_result(). */ struct onoff_client { /* Links the client into the set of waiting service users. */ @@ -341,6 +344,9 @@ static inline int onoff_client_fetch_result(const struct onoff_client *op, * notification, and instead must periodically check for completion * using onoff_client_fetch_result(). * + * On completion of the operation the client object must be + * reinitialized before it can be re-used. + * * @param cli pointer to the client state object. */ static inline void onoff_client_init_spinwait(struct onoff_client *cli) @@ -360,6 +366,9 @@ static inline void onoff_client_init_spinwait(struct onoff_client *cli) * completion of operations submitted through onoff_request() and * onoff_release() through the provided signal. * + * On completion of the operation the client object must be + * reinitialized before it can be re-used. + * * @note * @rst * This capability is available only when :option:`CONFIG_POLL` is @@ -398,6 +407,9 @@ static inline void onoff_client_init_signal(struct onoff_client *cli, * from various contexts depending on the specific service; see * @ref onoff_client_callback. * + * On completion of the operation the client object must be + * reinitialized before it can be re-used. + * * @param cli pointer to the client state object. * * @param handler a function pointer to use for notification.