Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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 <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 <zephyr/sys/notify.h>

Check for and read the result of an asynchronous operation.

Parameters
notifypointer to the object used to specify asynchronous function behavior and store completion information.
resultpointer to storage for the result of the operation. The result is stored only if the operation has completed.
Return values
0if the operation has completed.
-EAGAINif the operation has not completed.

◆ sys_notify_finalize()

sys_notify_generic_callback sys_notify_finalize ( struct sys_notify notify,
int  res 
)

#include <zephyr/sys/notify.h>

Record and signal the operation completion.

Parameters
notifypointer to the notification state structure.
resthe 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 <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 <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
notifypointer to the notification configuration object.
handlera 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 <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
notifypointer to the notification configuration object.
sigppointer 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 <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
notifypointer to the notification configuration object.

◆ sys_notify_uses_callback()

static bool sys_notify_uses_callback ( const struct sys_notify notify)
inlinestatic

#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 <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
0on successful validation and reinitialization
-EINVALif the configuration is not valid.