Asynchronous Notification APIs

Data Structures
struct	sys_notify
	State associated with notification for an asynchronous operation. More...

Typedefs
typedef void(*	sys_notify_generic_callback) ()
	Generic signature used to notify of result completion by callback.

Functions
static uint32_t	sys_notify_get_method (const struct sys_notify *notify)
int	sys_notify_validate (struct sys_notify *notify)
	Validate and initialize the notify structure.
sys_notify_generic_callback	sys_notify_finalize (struct sys_notify *notify, int res)
	Record and signal the operation completion.
static int	sys_notify_fetch_result (const struct sys_notify *notify, int *result)
	Check for and read the result of an asynchronous operation.
static void	sys_notify_init_spinwait (struct sys_notify *notify)
	Initialize a notify object for spin-wait notification.
static void	sys_notify_init_signal (struct sys_notify *notify, struct k_poll_signal *sigp)
	Initialize a notify object for (k_poll) signal notification.
static void	sys_notify_init_callback (struct sys_notify *notify, sys_notify_generic_callback handler)
	Initialize a notify object for callback notification.
static bool	sys_notify_uses_callback (const struct sys_notify *notify)
	Detect whether a particular notification uses a callback.

Detailed Description

Typedef Documentation

sys_notify_generic_callback

typedef void(* sys_notify_generic_callback) ()

#include <include/zephyr/sys/notify.h>

Generic signature used to notify of result completion by callback.

Functions with this role may be invoked from any context including pre-kernel, ISR, or cooperative or pre-emptible threads. Compatible functions must be isr-ok and not sleep.

Parameters that should generally be passed to such functions include:

• a pointer to a specific client request structure, i.e. the one that contains the sys_notify structure.
• the result of the operation, either as passed to sys_notify_finalize() or extracted afterwards using sys_notify_fetch_result(). Expected values are service-specific, but the value shall be non-negative if the operation succeeded, and negative if the operation failed.

Function Documentation

sys_notify_fetch_result()

static int sys_notify_fetch_result ( const struct sys_notify *  notify, int *  result  )

inlinestatic

#include <include/zephyr/sys/notify.h>

Check for and read the result of an asynchronous operation.

Parameters

notify	pointer to the object used to specify asynchronous function behavior and store completion information.
result	pointer to storage for the result of the operation. The result is stored only if the operation has completed.

Return values

0	if the operation has completed.
-EAGAIN	if the operation has not completed.

sys_notify_finalize()

sys_notify_generic_callback sys_notify_finalize	(	struct sys_notify *	notify,
		int	res
	)

#include <include/zephyr/sys/notify.h>

Record and signal the operation completion.

Parameters

notify	pointer to the notification state structure.
res	the result of the operation. Expected values are service-specific, but the value shall be non-negative if the operation succeeded, and negative if the operation failed.

Returns

If the notification is to be done by callback this returns the generic version of the function to be invoked. The caller must immediately invoke that function with whatever arguments are expected by the callback. If notification is by spin-wait or signal, the notification has been completed by the point this function returns, and a null pointer is returned.

sys_notify_get_method()

static uint32_t sys_notify_get_method ( const struct sys_notify *  notify )

inlinestatic

#include <include/zephyr/sys/notify.h>

sys_notify_init_callback()

static void sys_notify_init_callback ( struct sys_notify *  notify, sys_notify_generic_callback  handler  )

inlinestatic

#include <include/zephyr/sys/notify.h>

Initialize a notify object for callback notification.

Clients that use this initialization will be notified of the completion of operations through the provided callback. Note that callbacks may be invoked from various contexts depending on the specific service; see sys_notify_generic_callback.

On completion of the operation the client object must be reinitialized before it can be re-used.

Parameters

notify	pointer to the notification configuration object.
handler	a function pointer to use for notification.

sys_notify_init_signal()

static void sys_notify_init_signal ( struct sys_notify *  notify, struct k_poll_signal *  sigp  )

inlinestatic

#include <include/zephyr/sys/notify.h>

Initialize a notify object for (k_poll) signal notification.

Clients that use this initialization will be notified of the completion of operations through the provided signal.

On completion of the operation the client object must be reinitialized before it can be re-used.

Note

This capability is available only when CONFIG_POLL is selected.

Parameters

notify	pointer to the notification configuration object.
sigp	pointer to the signal to use for notification. The value must not be null. The signal must be reset before the client object is passed to the on-off service API.

sys_notify_init_spinwait()

static void sys_notify_init_spinwait ( struct sys_notify *  notify )

inlinestatic

#include <include/zephyr/sys/notify.h>

Initialize a notify object for spin-wait notification.

Clients that use this initialization receive no asynchronous notification, and instead must periodically check for completion using sys_notify_fetch_result().

On completion of the operation the client object must be reinitialized before it can be re-used.

Parameters

notify

pointer to the notification configuration object.

sys_notify_uses_callback()

static bool sys_notify_uses_callback ( const struct sys_notify *  notify )

inlinestatic

#include <include/zephyr/sys/notify.h>

Detect whether a particular notification uses a callback.

The generic handler does not capture the signature expected by the callback, and the translation to a service-specific callback must be provided by the service. This check allows abstracted services to reject callback notification requests when the service doesn't provide a translation function.

Returns

true if and only if a callback is to be used for notification.

sys_notify_validate()

int sys_notify_validate

(

struct sys_notify *

notify

)

#include <include/zephyr/sys/notify.h>

Validate and initialize the notify structure.

This should be invoked at the start of any service-specific configuration validation. It ensures that the basic asynchronous notification configuration is consistent, and clears the result.

Note that this function does not validate extension bits (zeroed by async notify API init functions like sys_notify_init_callback()). It may fail to recognize that an uninitialized structure has been passed because only method bits of flags are tested against method settings. To reduce the chance of accepting an uninitialized operation service validation of structures that contain an sys_notify instance should confirm that the extension bits are set or cleared as expected.

Return values

0	on successful validation and reinitialization
-EINVAL	if the configuration is not valid.