michaelh/zephyr
1
0
Fork 0
Code Releases Activity

lib: os: onoff: documentation clarifications

Browse source 
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 <peter.bigot@nordicsemi.no>
This commit is contained in:
Peter Bigot 2020-02-05 03:59:41 -06:00 • committed by Anas Nashif
commit 1977ac3ce2
1 changed files with 15 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

18
include/sys/onoff.h
View file

@ -270,9 +270,12 @@ typedef void (*onoff_client_callback)(struct onoff_service *srv,
* * when operation completion is posted (signalled or callback * * when operation completion is posted (signalled or callback
* invoked). * invoked).
* *
* Only the result field is intended for direct use by clients, and it * After control has reverted to the client the state object must be
* is available for inspection only after control reverts to the * reinitialized for the next operation.
* client. *
* 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 { struct onoff_client {
/* Links the client into the set of waiting service users. */ /* 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 * notification, and instead must periodically check for completion
* using onoff_client_fetch_result(). * 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. * @param cli pointer to the client state object.
*/ */
static inline void onoff_client_init_spinwait(struct onoff_client *cli) 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 * completion of operations submitted through onoff_request() and
* onoff_release() through the provided signal. * onoff_release() through the provided signal.
* *
* On completion of the operation the client object must be
* reinitialized before it can be re-used.
*
* @note * @note
* @rst * @rst
* This capability is available only when :option:`CONFIG_POLL` is * 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 * from various contexts depending on the specific service; see
* @ref onoff_client_callback. * @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 cli pointer to the client state object.
* *
* @param handler a function pointer to use for notification. * @param handler a function pointer to use for notification.