Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
notify.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2019 Peter Bigot Consulting, LLC
3 * Copyright (c) 2020 Nordic Semiconductor ASA
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8#ifndef ZEPHYR_INCLUDE_SYS_NOTIFY_H_
9#define ZEPHYR_INCLUDE_SYS_NOTIFY_H_
10
11#include <kernel.h>
12#include <zephyr/types.h>
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
18struct sys_notify;
19
20/*
21 * Flag value that overwrites the method field when the operation has
22 * completed.
23 */
24#define SYS_NOTIFY_METHOD_COMPLETED 0
25
26/*
27 * Indicates that no notification will be provided.
28 *
29 * Callers must check for completions using
30 * sys_notify_fetch_result().
31 *
32 * See sys_notify_init_spinwait().
33 */
34#define SYS_NOTIFY_METHOD_SPINWAIT 1
35
36/*
37 * Select notification through @ref k_poll signal
38 *
39 * See sys_notify_init_signal().
40 */
41#define SYS_NOTIFY_METHOD_SIGNAL 2
42
43/*
44 * Select notification through a user-provided callback.
45 *
46 * See sys_notify_init_callback().
47 */
48#define SYS_NOTIFY_METHOD_CALLBACK 3
49
50#define SYS_NOTIFY_METHOD_MASK 0x03U
51#define SYS_NOTIFY_METHOD_POS 0
52
66#define SYS_NOTIFY_EXTENSION_POS 2
67
68/*
69 * Mask isolating the bits of sys_notify::flags that are available
70 * for extension.
71 */
72#define SYS_NOTIFY_EXTENSION_MASK (~BIT_MASK(SYS_NOTIFY_EXTENSION_POS))
73
99
139 union method {
140 /* Pointer to signal used to notify client.
141 *
142 * The signal value corresponds to the res parameter
143 * of sys_notify_callback.
144 */
146
147 /* Generic callback function for callback notification. */
150
151 /*
152 * Flags recording information about the operation.
153 *
154 * Bits below SYS_NOTIFY_EXTENSION_POS are initialized by
155 * async notify API init functions like
156 * sys_notify_init_callback(), and must not by modified by
157 * extensions or client code.
158 *
159 * Bits at and above SYS_NOTIFY_EXTENSION_POS are available
160 * for use by service extensions while the containing object
161 * is managed by the service. They are not for client use,
162 * are zeroed by the async notify API init functions, and will
163 * be zeroed by sys_notify_finalize().
164 */
165 uint32_t volatile flags;
166
167 /*
168 * The result of the operation.
169 *
170 * This is the value that was (or would be) passed to the
171 * async infrastructure. This field is the sole record of
172 * success or failure for spin-wait synchronous operations.
173 */
174 int volatile result;
175};
176
178static inline uint32_t sys_notify_get_method(const struct sys_notify *notify)
179{
180 uint32_t method = notify->flags >> SYS_NOTIFY_METHOD_POS;
181
182 return method & SYS_NOTIFY_METHOD_MASK;
183}
184
204int sys_notify_validate(struct sys_notify *notify);
205
223 int res);
224
237static inline int sys_notify_fetch_result(const struct sys_notify *notify,
238 int *result)
239{
240 __ASSERT_NO_MSG(notify != NULL);
241 __ASSERT_NO_MSG(result != NULL);
242 int rv = -EAGAIN;
243
245 rv = 0;
246 *result = notify->result;
247 }
248
249 return rv;
250}
251
264static inline void sys_notify_init_spinwait(struct sys_notify *notify)
265{
266 __ASSERT_NO_MSG(notify != NULL);
267
268 *notify = (struct sys_notify){
270 };
271}
272
292static inline void sys_notify_init_signal(struct sys_notify *notify,
293 struct k_poll_signal *sigp)
294{
295 __ASSERT_NO_MSG(notify != NULL);
296 __ASSERT_NO_MSG(sigp != NULL);
297
298 *notify = (struct sys_notify){
299 .method = {
300 .signal = sigp,
301 },
303 };
304}
305
321static inline void sys_notify_init_callback(struct sys_notify *notify,
323{
324 __ASSERT_NO_MSG(notify != NULL);
325 __ASSERT_NO_MSG(handler != NULL);
326
327 *notify = (struct sys_notify){
328 .method = {
329 .callback = handler,
330 },
332 };
333}
334
346static inline bool sys_notify_uses_callback(const struct sys_notify *notify)
347{
348 __ASSERT_NO_MSG(notify != NULL);
349
351}
352
355#ifdef __cplusplus
356}
357#endif
358
359#endif /* ZEPHYR_INCLUDE_SYS_NOTIFY_H_ */
void
Definition: eswifi_shell.c:15
volatile int rv
Definition: main.c:45
static uint32_t sys_notify_get_method(const struct sys_notify *notify)
Definition: notify.h:178
void(* sys_notify_generic_callback)()
Generic signature used to notify of result completion by callback.
Definition: notify.h:98
static void sys_notify_init_signal(struct sys_notify *notify, struct k_poll_signal *sigp)
Initialize a notify object for (k_poll) signal notification.
Definition: notify.h:292
sys_notify_generic_callback sys_notify_finalize(struct sys_notify *notify, int res)
Record and signal the operation completion.
int sys_notify_validate(struct sys_notify *notify)
Validate and initialize the notify structure.
static int sys_notify_fetch_result(const struct sys_notify *notify, int *result)
Check for and read the result of an asynchronous operation.
Definition: notify.h:237
static bool sys_notify_uses_callback(const struct sys_notify *notify)
Detect whether a particular notification uses a callback.
Definition: notify.h:346
static void sys_notify_init_callback(struct sys_notify *notify, sys_notify_generic_callback handler)
Initialize a notify object for callback notification.
Definition: notify.h:321
static void sys_notify_init_spinwait(struct sys_notify *notify)
Initialize a notify object for spin-wait notification.
Definition: notify.h:264
#define EAGAIN
Definition: errno.h:50
#define SYS_NOTIFY_METHOD_SPINWAIT
Definition: notify.h:34
#define SYS_NOTIFY_METHOD_CALLBACK
Definition: notify.h:48
#define SYS_NOTIFY_METHOD_MASK
Definition: notify.h:50
#define SYS_NOTIFY_METHOD_POS
Definition: notify.h:51
#define SYS_NOTIFY_METHOD_SIGNAL
Definition: notify.h:41
#define SYS_NOTIFY_METHOD_COMPLETED
Definition: notify.h:24
__UINT32_TYPE__ uint32_t
Definition: stdint.h:60
Definition: kernel.h:5405
Definition: errno.c:36
State associated with notification for an asynchronous operation.
Definition: notify.h:138
uint32_t volatile flags
Definition: notify.h:165
int volatile result
Definition: notify.h:174
union sys_notify::method method
static void handler(struct k_timer *timer)
Definition: main.c:19
Definition: notify.h:139
struct k_poll_signal * signal
Definition: notify.h:145
sys_notify_generic_callback callback
Definition: notify.h:148