notify.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019 Peter Bigot Consulting, LLC
 * Copyright (c) 2020 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_SYS_NOTIFY_H_
#define ZEPHYR_INCLUDE_SYS_NOTIFY_H_
 
#include <zephyr/kernel.h>
#include <zephyr/types.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct sys_notify;
 
/*
 * Flag value that overwrites the method field when the operation has
 * completed.
 */
#define SYS_NOTIFY_METHOD_COMPLETED 0
 
/*
 * Indicates that no notification will be provided.
 *
 * Callers must check for completions using
 * sys_notify_fetch_result().
 *
 * See sys_notify_init_spinwait().
 */
#define SYS_NOTIFY_METHOD_SPINWAIT 1
 
/*
 * Select notification through @ref k_poll signal
 *
 * See sys_notify_init_signal().
 */
#define SYS_NOTIFY_METHOD_SIGNAL 2
 
/*
 * Select notification through a user-provided callback.
 *
 * See sys_notify_init_callback().
 */
#define SYS_NOTIFY_METHOD_CALLBACK 3
 
#define SYS_NOTIFY_METHOD_MASK 0x03U
#define SYS_NOTIFY_METHOD_POS 0
 
#define SYS_NOTIFY_EXTENSION_POS 2
 
/*
 * Mask isolating the bits of sys_notify::flags that are available
 * for extension.
 */
#define SYS_NOTIFY_EXTENSION_MASK (~BIT_MASK(SYS_NOTIFY_EXTENSION_POS))
 
typedef void (*sys_notify_generic_callback)();
 
struct sys_notify {
        union method {
                /* Pointer to signal used to notify client.
                 *
                 * The signal value corresponds to the res parameter
                 * of sys_notify_callback.
                 */
                struct k_poll_signal *signal;
 
                /* Generic callback function for callback notification. */
                sys_notify_generic_callback callback;
        } method;
 
        /*
         * Flags recording information about the operation.
         *
         * Bits below SYS_NOTIFY_EXTENSION_POS are initialized by
         * async notify API init functions like
         * sys_notify_init_callback(), and must not by modified by
         * extensions or client code.
         *
         * Bits at and above SYS_NOTIFY_EXTENSION_POS are available
         * for use by service extensions while the containing object
         * is managed by the service.  They are not for client use,
         * are zeroed by the async notify API init functions, and will
         * be zeroed by sys_notify_finalize().
         */
        uint32_t volatile flags;
 
        /*
         * The result of the operation.
         *
         * This is the value that was (or would be) passed to the
         * async infrastructure.  This field is the sole record of
         * success or failure for spin-wait synchronous operations.
         */
        int volatile result;
};
 
static inline uint32_t sys_notify_get_method(const struct sys_notify *notify)
{
        uint32_t method = notify->flags >> SYS_NOTIFY_METHOD_POS;
 
        return method & SYS_NOTIFY_METHOD_MASK;
}
 
int sys_notify_validate(struct sys_notify *notify);
 
sys_notify_generic_callback sys_notify_finalize(struct sys_notify *notify,
                                                    int res);
 
static inline int sys_notify_fetch_result(const struct sys_notify *notify,
                                            int *result)
{
        __ASSERT_NO_MSG(notify != NULL);
        __ASSERT_NO_MSG(result != NULL);
        int rv = -EAGAIN;
 
        if (sys_notify_get_method(notify) == SYS_NOTIFY_METHOD_COMPLETED) {
                rv = 0;
                *result = notify->result;
        }
 
        return rv;
}
 
static inline void sys_notify_init_spinwait(struct sys_notify *notify)
{
        __ASSERT_NO_MSG(notify != NULL);
 
        *notify = (struct sys_notify){
                .flags = SYS_NOTIFY_METHOD_SPINWAIT,
        };
}
 
static inline void sys_notify_init_signal(struct sys_notify *notify,
                                            struct k_poll_signal *sigp)
{
        __ASSERT_NO_MSG(notify != NULL);
        __ASSERT_NO_MSG(sigp != NULL);
 
        *notify = (struct sys_notify){
                .method = {
                        .signal = sigp,
                },
                .flags = SYS_NOTIFY_METHOD_SIGNAL,
        };
}
 
static inline void sys_notify_init_callback(struct sys_notify *notify,
                                              sys_notify_generic_callback handler)
{
        __ASSERT_NO_MSG(notify != NULL);
        __ASSERT_NO_MSG(handler != NULL);
 
        *notify = (struct sys_notify){
                .method = {
                        .callback = handler,
                },
                .flags = SYS_NOTIFY_METHOD_CALLBACK,
        };
}
 
static inline bool sys_notify_uses_callback(const struct sys_notify *notify)
{
        __ASSERT_NO_MSG(notify != NULL);
 
        return sys_notify_get_method(notify) == SYS_NOTIFY_METHOD_CALLBACK;
}
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SYS_NOTIFY_H_ */