Zephyr Project API 3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
onoff.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_ONOFF_H_
9#define ZEPHYR_INCLUDE_SYS_ONOFF_H_
10
11#include <zephyr/kernel.h>
12#include <zephyr/types.h>
13#include <zephyr/sys/notify.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
30#define ONOFF_FLAG_ERROR BIT(0)
31
33#define ONOFF_FLAG_ONOFF BIT(1)
34#define ONOFF_FLAG_TRANSITION BIT(2)
45#define ONOFF_STATE_MASK (ONOFF_FLAG_ERROR \
46 | ONOFF_FLAG_ONOFF \
47 | ONOFF_FLAG_TRANSITION)
48
52#define ONOFF_STATE_OFF 0U
53
57#define ONOFF_STATE_ON ONOFF_FLAG_ONOFF
58
63#define ONOFF_STATE_ERROR ONOFF_FLAG_ERROR
64
69#define ONOFF_STATE_TO_ON (ONOFF_FLAG_TRANSITION | ONOFF_STATE_ON)
70
75#define ONOFF_STATE_TO_OFF (ONOFF_FLAG_TRANSITION | ONOFF_STATE_OFF)
76
81#define ONOFF_STATE_RESETTING (ONOFF_FLAG_TRANSITION | ONOFF_STATE_ERROR)
82
83/* Forward declarations */
84struct onoff_manager;
85struct onoff_monitor;
86
101typedef void (*onoff_notify_fn)(struct onoff_manager *mgr,
102 int res);
103
129typedef void (*onoff_transition_fn)(struct onoff_manager *mgr,
130 onoff_notify_fn notify);
131
145
180
190#define ONOFF_TRANSITIONS_INITIALIZER(_start, _stop, _reset) { \
191 .start = (_start), \
192 .stop = (_stop), \
193 .reset = (_reset), \
194}
195
197#define ONOFF_MANAGER_INITIALIZER(_transitions) { \
198 .transitions = (_transitions), \
199}
222 const struct onoff_transitions *transitions);
223
224/* Forward declaration */
225struct onoff_client;
226
252typedef void (*onoff_client_callback)(struct onoff_manager *mgr,
253 struct onoff_client *cli,
255 int res);
256
281 sys_snode_t node;
286};
287
300#define ONOFF_CLIENT_EXTENSION_POS SYS_NOTIFY_EXTENSION_POS
301
315static inline bool onoff_has_error(const struct onoff_manager *mgr)
316{
317 return (mgr->flags & ONOFF_FLAG_ERROR) != 0;
318}
319
348 struct onoff_client *cli);
349
369
402 struct onoff_client *cli);
403
435static inline int onoff_cancel_or_release(struct onoff_manager *mgr,
436 struct onoff_client *cli)
437{
438 int rv = onoff_cancel(mgr, cli);
439
440 if (rv == -EALREADY) {
441 rv = onoff_release(mgr);
442 }
443 return rv;
444}
445
482 struct onoff_client *cli);
483
512typedef void (*onoff_monitor_callback)(struct onoff_manager *mgr,
513 struct onoff_monitor *mon,
515 int res);
516
537
550 struct onoff_monitor *mon);
551
564 struct onoff_monitor *mon);
565
583
601 k_spinlock_key_t *keyp);
602
637 struct onoff_client *cli,
638 int res,
639 bool on);
640
643#ifdef __cplusplus
644}
645#endif
646
647#endif /* ZEPHYR_INCLUDE_SYS_ONOFF_H_ */
volatile int rv
Definition main.c:49
int onoff_sync_lock(struct onoff_sync_service *srv, k_spinlock_key_t *keyp)
Lock a synchronous onoff service and provide its state.
int onoff_release(struct onoff_manager *mgr)
Release a reserved use of an on-off service.
int onoff_request(struct onoff_manager *mgr, struct onoff_client *cli)
Request a reservation to use an on-off service.
static bool onoff_has_error(const struct onoff_manager *mgr)
Test whether an on-off service has recorded an error.
Definition onoff.h:315
void(* onoff_client_callback)(struct onoff_manager *mgr, struct onoff_client *cli, uint32_t state, int res)
Signature used to notify an on-off service client of the completion of an operation.
Definition onoff.h:252
int onoff_monitor_unregister(struct onoff_manager *mgr, struct onoff_monitor *mon)
Remove a monitor of state changes from a manager.
void(* onoff_transition_fn)(struct onoff_manager *mgr, onoff_notify_fn notify)
Signature used by service implementations to effect a transition.
Definition onoff.h:129
int onoff_manager_init(struct onoff_manager *mgr, const struct onoff_transitions *transitions)
Initialize an on-off service to off state.
static int onoff_cancel_or_release(struct onoff_manager *mgr, struct onoff_client *cli)
Helper function to safely cancel a request.
Definition onoff.h:435
int onoff_monitor_register(struct onoff_manager *mgr, struct onoff_monitor *mon)
Add a monitor of state changes for a manager.
#define ONOFF_FLAG_ERROR
Flag indicating an error state.
Definition onoff.h:30
void(* onoff_notify_fn)(struct onoff_manager *mgr, int res)
Signature used to notify an on-off manager that a transition has completed.
Definition onoff.h:101
int onoff_cancel(struct onoff_manager *mgr, struct onoff_client *cli)
Attempt to cancel an in-progress client operation.
int onoff_sync_finalize(struct onoff_sync_service *srv, k_spinlock_key_t key, struct onoff_client *cli, int res, bool on)
Process the completion of a transition in a synchronous service and release lock.
void(* onoff_monitor_callback)(struct onoff_manager *mgr, struct onoff_monitor *mon, uint32_t state, int res)
Signature used to notify a monitor of an onoff service of errors or completion of a state transition.
Definition onoff.h:512
int onoff_reset(struct onoff_manager *mgr, struct onoff_client *cli)
Clear errors on an on-off service and reset it to its off state.
struct _slist sys_slist_t
Single-linked list structure.
Definition slist.h:49
struct _snode sys_snode_t
Single-linked list node structure.
Definition slist.h:39
struct z_spinlock_key k_spinlock_key_t
Spinlock key type.
Definition spinlock.h:130
#define EALREADY
Operation already in progress.
Definition errno.h:104
Public kernel APIs.
state
Definition parser_state.h:29
static k_spinlock_key_t key
Definition spinlock_error_case.c:15
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__INT32_TYPE__ int32_t
Definition stdint.h:74
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
Kernel Spin Lock.
Definition spinlock.h:45
State associated with a client of an on-off service.
Definition onoff.h:274
struct sys_notify notify
Notification configuration.
Definition onoff.h:285
State associated with an on-off manager.
Definition onoff.h:154
sys_slist_t clients
List of clients waiting for request or reset completion notifications.
Definition onoff.h:158
uint16_t refs
Number of active clients for the service.
Definition onoff.h:178
sys_slist_t monitors
List of monitors to be notified of state changes including errors and transition completion.
Definition onoff.h:163
uint16_t flags
Flags identifying the service state.
Definition onoff.h:175
int last_res
The result of the last transition.
Definition onoff.h:172
const struct onoff_transitions * transitions
Transition functions.
Definition onoff.h:166
struct k_spinlock lock
Mutex protection for other fields.
Definition onoff.h:169
Registration state for notifications of onoff service transitions.
Definition onoff.h:524
sys_snode_t node
Links the client into the set of waiting service users.
Definition onoff.h:529
onoff_monitor_callback callback
Callback to be invoked on state change.
Definition onoff.h:535
State used when a driver uses the on-off service API for synchronous operations.
Definition onoff.h:576
struct k_spinlock lock
Mutex protection for other fields.
Definition onoff.h:578
int32_t count
Negative is error, non-negative is reference count.
Definition onoff.h:581
On-off service transition functions.
Definition onoff.h:133
onoff_transition_fn reset
Function to force the service state to reset, where supported.
Definition onoff.h:143
onoff_transition_fn start
Function to invoke to transition the service to on.
Definition onoff.h:135
onoff_transition_fn stop
Function to invoke to transition the service to off.
Definition onoff.h:138
State associated with notification for an asynchronous operation.
Definition notify.h:138