onoff.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_ONOFF_H_
#define ZEPHYR_INCLUDE_SYS_ONOFF_H_
 
#include <zephyr/kernel.h>
#include <zephyr/types.h>
#include <zephyr/sys/notify.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define ONOFF_FLAG_ERROR BIT(0)
 
#define ONOFF_FLAG_ONOFF BIT(1)
#define ONOFF_FLAG_TRANSITION BIT(2)
 
#define ONOFF_STATE_MASK (ONOFF_FLAG_ERROR   \
                          | ONOFF_FLAG_ONOFF \
                          | ONOFF_FLAG_TRANSITION)
 
#define ONOFF_STATE_OFF 0U
 
#define ONOFF_STATE_ON ONOFF_FLAG_ONOFF
 
#define ONOFF_STATE_ERROR ONOFF_FLAG_ERROR
 
#define ONOFF_STATE_TO_ON (ONOFF_FLAG_TRANSITION | ONOFF_STATE_ON)
 
#define ONOFF_STATE_TO_OFF (ONOFF_FLAG_TRANSITION | ONOFF_STATE_OFF)
 
#define ONOFF_STATE_RESETTING (ONOFF_FLAG_TRANSITION | ONOFF_STATE_ERROR)
 
/* Forward declarations */
struct onoff_manager;
struct onoff_monitor;
 
typedef void (*onoff_notify_fn)(struct onoff_manager *mgr,
                                int res);
 
typedef void (*onoff_transition_fn)(struct onoff_manager *mgr,
                                    onoff_notify_fn notify);
 
struct onoff_transitions {
        /* Function to invoke to transition the service to on. */
        onoff_transition_fn start;
 
        /* Function to invoke to transition the service to off. */
        onoff_transition_fn stop;
 
        /* Function to force the service state to reset, where
         * supported.
         */
        onoff_transition_fn reset;
};
 
struct onoff_manager {
        /* List of clients waiting for request or reset completion
         * notifications.
         */
        sys_slist_t clients;
 
        /* List of monitors to be notified of state changes including
         * errors and transition completion.
         */
        sys_slist_t monitors;
 
        /* Transition functions. */
        const struct onoff_transitions *transitions;
 
        /* Mutex protection for other fields. */
        struct k_spinlock lock;
 
        /* The result of the last transition. */
        int last_res;
 
        /* Flags identifying the service state. */
        uint16_t flags;
 
        /* Number of active clients for the service. */
        uint16_t refs;
};
 
#define ONOFF_TRANSITIONS_INITIALIZER(_start, _stop, _reset) { \
                .start = _start,                               \
                .stop = _stop,                                 \
                .reset = _reset,                               \
}
 
#define ONOFF_MANAGER_INITIALIZER(_transitions) { \
                .transitions = _transitions,      \
}
 
int onoff_manager_init(struct onoff_manager *mgr,
                       const struct onoff_transitions *transitions);
 
/* Forward declaration */
struct onoff_client;
 
typedef void (*onoff_client_callback)(struct onoff_manager *mgr,
                                      struct onoff_client *cli,
                                      uint32_t state,
                                      int res);
 
struct onoff_client {
        sys_snode_t node;
 
        struct sys_notify notify;
};
 
#define ONOFF_CLIENT_EXTENSION_POS SYS_NOTIFY_EXTENSION_POS
 
static inline bool onoff_has_error(const struct onoff_manager *mgr)
{
        return (mgr->flags & ONOFF_FLAG_ERROR) != 0;
}
 
int onoff_request(struct onoff_manager *mgr,
                  struct onoff_client *cli);
 
int onoff_release(struct onoff_manager *mgr);
 
int onoff_cancel(struct onoff_manager *mgr,
                 struct onoff_client *cli);
 
static inline int onoff_cancel_or_release(struct onoff_manager *mgr,
                                          struct onoff_client *cli)
{
        int rv = onoff_cancel(mgr, cli);
 
        if (rv == -EALREADY) {
                rv = onoff_release(mgr);
        }
        return rv;
}
 
int onoff_reset(struct onoff_manager *mgr,
                struct onoff_client *cli);
 
typedef void (*onoff_monitor_callback)(struct onoff_manager *mgr,
                                       struct onoff_monitor *mon,
                                       uint32_t state,
                                       int res);
 
struct onoff_monitor {
        /* Links the client into the set of waiting service users.
         *
         * This must be zero-initialized.
         */
        sys_snode_t node;
 
        onoff_monitor_callback callback;
};
 
int onoff_monitor_register(struct onoff_manager *mgr,
                           struct onoff_monitor *mon);
 
int onoff_monitor_unregister(struct onoff_manager *mgr,
                             struct onoff_monitor *mon);
 
struct onoff_sync_service {
        /* Mutex protection for other fields. */
        struct k_spinlock lock;
 
        /* Negative is error, non-negative is reference count. */
        int32_t count;
};
 
int onoff_sync_lock(struct onoff_sync_service *srv,
                    k_spinlock_key_t *keyp);
 
int onoff_sync_finalize(struct onoff_sync_service *srv,
                         k_spinlock_key_t key,
                         struct onoff_client *cli,
                         int res,
                         bool on);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SYS_ONOFF_H_ */