Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
On-Off Service APIs

Data Structures

struct  onoff_transitions
 On-off service transition functions. More...
 
struct  onoff_manager
 State associated with an on-off manager. More...
 
struct  onoff_client
 State associated with a client of an on-off service. More...
 
struct  onoff_monitor
 Registration state for notifications of onoff service transitions. More...
 
struct  onoff_sync_service
 State used when a driver uses the on-off service API for synchronous operations. More...
 

Macros

#define ONOFF_FLAG_ERROR   BIT(0)
 Flag indicating an error state.
 
#define ONOFF_STATE_MASK
 Mask used to isolate bits defining the service state.
 
#define ONOFF_STATE_OFF   0U
 Value exposed by ONOFF_STATE_MASK when service is off.
 
#define ONOFF_STATE_ON   ONOFF_FLAG_ONOFF
 Value exposed by ONOFF_STATE_MASK when service is on.
 
#define ONOFF_STATE_ERROR   ONOFF_FLAG_ERROR
 Value exposed by ONOFF_STATE_MASK when the service is in an error state (and not in the process of resetting its state).
 
#define ONOFF_STATE_TO_ON   (ONOFF_FLAG_TRANSITION | ONOFF_STATE_ON)
 Value exposed by ONOFF_STATE_MASK when service is transitioning to on.
 
#define ONOFF_STATE_TO_OFF   (ONOFF_FLAG_TRANSITION | ONOFF_STATE_OFF)
 Value exposed by ONOFF_STATE_MASK when service is transitioning to off.
 
#define ONOFF_STATE_RESETTING   (ONOFF_FLAG_TRANSITION | ONOFF_STATE_ERROR)
 Value exposed by ONOFF_STATE_MASK when service is in the process of resetting.
 
#define ONOFF_TRANSITIONS_INITIALIZER(_start, _stop, _reset)
 Initializer for a onoff_transitions object.
 
#define ONOFF_CLIENT_EXTENSION_POS   SYS_NOTIFY_EXTENSION_POS
 Identify region of sys_notify flags available for containing services.
 

Typedefs

typedef void(* onoff_notify_fn) (struct onoff_manager *mgr, int res)
 Signature used to notify an on-off manager that a transition has completed.
 
typedef void(* onoff_transition_fn) (struct onoff_manager *mgr, onoff_notify_fn notify)
 Signature used by service implementations to effect a transition.
 
typedef 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.
 
typedef 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.
 

Functions

int onoff_manager_init (struct onoff_manager *mgr, const struct onoff_transitions *transitions)
 Initialize an on-off service to off state.
 
static bool onoff_has_error (const struct onoff_manager *mgr)
 Test whether an on-off service has recorded an error.
 
int onoff_request (struct onoff_manager *mgr, struct onoff_client *cli)
 Request a reservation to use an on-off service.
 
int onoff_release (struct onoff_manager *mgr)
 Release a reserved use of an on-off service.
 
int onoff_cancel (struct onoff_manager *mgr, struct onoff_client *cli)
 Attempt to cancel an in-progress client operation.
 
static int onoff_cancel_or_release (struct onoff_manager *mgr, struct onoff_client *cli)
 Helper function to safely cancel a request.
 
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.
 
int onoff_monitor_register (struct onoff_manager *mgr, struct onoff_monitor *mon)
 Add a monitor of state changes for a manager.
 
int onoff_monitor_unregister (struct onoff_manager *mgr, struct onoff_monitor *mon)
 Remove a monitor of state changes from a manager.
 
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_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.
 

Detailed Description

Macro Definition Documentation

◆ ONOFF_CLIENT_EXTENSION_POS

#define ONOFF_CLIENT_EXTENSION_POS   SYS_NOTIFY_EXTENSION_POS

#include <zephyr/sys/onoff.h>

Identify region of sys_notify flags available for containing services.

Bits of the flags field of the sys_notify structure contained within the queued_operation structure at and above this position may be used by extensions to the onoff_client structure.

These bits are intended for use by containing service implementations to record client-specific information and are subject to other conditions of use specified on the sys_notify API.

◆ ONOFF_FLAG_ERROR

#define ONOFF_FLAG_ERROR   BIT(0)

#include <zephyr/sys/onoff.h>

Flag indicating an error state.

Error states are cleared using onoff_reset().

◆ ONOFF_STATE_ERROR

#define ONOFF_STATE_ERROR   ONOFF_FLAG_ERROR

#include <zephyr/sys/onoff.h>

Value exposed by ONOFF_STATE_MASK when the service is in an error state (and not in the process of resetting its state).

◆ ONOFF_STATE_MASK

#define ONOFF_STATE_MASK

#include <zephyr/sys/onoff.h>

Value:
| ONOFF_FLAG_ONOFF \
| ONOFF_FLAG_TRANSITION)
#define ONOFF_FLAG_ERROR
Flag indicating an error state.
Definition: onoff.h:30

Mask used to isolate bits defining the service state.

Mask a value with this then test for ONOFF_FLAG_ERROR to determine whether the machine has an unfixed error, or compare against ONOFF_STATE_ON, ONOFF_STATE_OFF, ONOFF_STATE_TO_ON, ONOFF_STATE_TO_OFF, or ONOFF_STATE_RESETTING.

◆ ONOFF_STATE_OFF

#define ONOFF_STATE_OFF   0U

#include <zephyr/sys/onoff.h>

Value exposed by ONOFF_STATE_MASK when service is off.

◆ ONOFF_STATE_ON

#define ONOFF_STATE_ON   ONOFF_FLAG_ONOFF

#include <zephyr/sys/onoff.h>

Value exposed by ONOFF_STATE_MASK when service is on.

◆ ONOFF_STATE_RESETTING

#define ONOFF_STATE_RESETTING   (ONOFF_FLAG_TRANSITION | ONOFF_STATE_ERROR)

#include <zephyr/sys/onoff.h>

Value exposed by ONOFF_STATE_MASK when service is in the process of resetting.

◆ ONOFF_STATE_TO_OFF

#define ONOFF_STATE_TO_OFF   (ONOFF_FLAG_TRANSITION | ONOFF_STATE_OFF)

#include <zephyr/sys/onoff.h>

Value exposed by ONOFF_STATE_MASK when service is transitioning to off.

◆ ONOFF_STATE_TO_ON

#define ONOFF_STATE_TO_ON   (ONOFF_FLAG_TRANSITION | ONOFF_STATE_ON)

#include <zephyr/sys/onoff.h>

Value exposed by ONOFF_STATE_MASK when service is transitioning to on.

◆ ONOFF_TRANSITIONS_INITIALIZER

#define ONOFF_TRANSITIONS_INITIALIZER (   _start,
  _stop,
  _reset 
)

#include <zephyr/sys/onoff.h>

Value:
{ \
.start = (_start), \
.stop = (_stop), \
.reset = (_reset), \
}

Initializer for a onoff_transitions object.

Parameters
_starta function used to transition from off to on state.
_stopa function used to transition from on to off state.
_reseta function used to clear errors and force the service to an off state. Can be null.

Typedef Documentation

◆ onoff_client_callback

typedef void(* onoff_client_callback) (struct onoff_manager *mgr, struct onoff_client *cli, uint32_t state, int res)

#include <zephyr/sys/onoff.h>

Signature used to notify an on-off service client of the completion of an operation.

These functions 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
mgrthe manager for which the operation was initiated. This may be null if the on-off service uses synchronous transitions.
clithe client structure passed to the function that initiated the operation.
statethe state of the machine at the time of completion, restricted by ONOFF_STATE_MASK. ONOFF_FLAG_ERROR must be checked independently of whether res is negative as a machine error may indicate that all future operations except onoff_reset() will fail.
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. If res is negative ONOFF_FLAG_ERROR will be set in state, but if res is non-negative ONOFF_FLAG_ERROR may still be set in state.

◆ onoff_monitor_callback

typedef void(* onoff_monitor_callback) (struct onoff_manager *mgr, struct onoff_monitor *mon, uint32_t state, int res)

#include <zephyr/sys/onoff.h>

Signature used to notify a monitor of an onoff service of errors or completion of a state transition.

This is similar to onoff_client_callback but provides information about all transitions, not just ones associated with a specific client. Monitor callbacks are invoked before any completion notifications associated with the state change are made.

These functions 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.

The callback is permitted to unregister itself from the manager, but must not register or unregister any other monitors.

Parameters
mgrthe manager for which a transition has completed.
monthe monitor instance through which this notification arrived.
statethe state of the machine at the time of completion, restricted by ONOFF_STATE_MASK. All valid states may be observed.
resthe result of the operation. Expected values are service- and state-specific, but the value shall be non-negative if the operation succeeded, and negative if the operation failed.

◆ onoff_notify_fn

typedef void(* onoff_notify_fn) (struct onoff_manager *mgr, int res)

#include <zephyr/sys/onoff.h>

Signature used to notify an on-off manager that a transition has completed.

Functions of this type are passed to service-specific transition functions to be used to report the completion of the operation. The functions may be invoked from any context.

Parameters
mgrthe manager for which transition was requested.
resthe result of the transition. This shall be non-negative on success, or a negative error code. If an error is indicated the service shall enter an error state.

◆ onoff_transition_fn

typedef void(* onoff_transition_fn) (struct onoff_manager *mgr, onoff_notify_fn notify)

#include <zephyr/sys/onoff.h>

Signature used by service implementations to effect a transition.

Service definitions use two required function pointers of this type to be notified that a transition is required, and a third optional one to reset the service when it is in an error state.

The start function will be called only from the off state.

The stop function will be called only from the on state.

The reset function (where supported) will be called only when onoff_has_error() returns true.

Note
All transitions functions must be isr-ok.
Parameters
mgrthe manager for which transition was requested.
notifythe function to be invoked when the transition has completed. If the transition is synchronous, notify shall be invoked by the implementation before the transition function returns. Otherwise the implementation shall capture this parameter and invoke it when the transition completes.

Function Documentation

◆ onoff_cancel()

int onoff_cancel ( struct onoff_manager mgr,
struct onoff_client cli 
)

#include <zephyr/sys/onoff.h>

Attempt to cancel an in-progress client operation.

It may be that a client has initiated an operation but needs to shut down before the operation has completed. For example, when a request was made and the need is no longer present.

Cancelling is supported only for onoff_request() and onoff_reset() operations, and is a synchronous operation. Be aware that any transition that was initiated on behalf of the client will continue to progress to completion: it is only notification of transition completion that may be eliminated. If there are no active requests when a transition to on completes the manager will initiate a transition to off.

Client notification does not occur for cancelled operations.

Parameters
mgrthe manager for which an operation is to be cancelled.
clia pointer to the same client state that was provided when the operation to be cancelled was issued.
Return values
non-negativethe observed state of the machine at the time of the cancellation, if the cancellation succeeds. On successful cancellation ownership of *cli reverts to the client.
-EINVALif the parameters are invalid.
-EALREADYif cli was not a record of an uncompleted notification at the time the cancellation was processed. This likely indicates that the operation and client notification had already completed.

◆ onoff_cancel_or_release()

static int onoff_cancel_or_release ( struct onoff_manager mgr,
struct onoff_client cli 
)
inlinestatic

#include <zephyr/sys/onoff.h>

Helper function to safely cancel a request.

Some applications may want to issue requests on an asynchronous event (such as connection to a USB bus) and to release on a paired event (such as loss of connection to a USB bus). Applications cannot precisely determine that an in-progress request is still pending without using onoff_monitor and carefully avoiding race conditions.

This function is a helper that attempts to cancel the operation and issues a release if cancellation fails because the request was completed. This synchronously ensures that ownership of the client data reverts to the client so is available for a future request.

Parameters
mgrthe manager for which an operation is to be cancelled.
clia pointer to the same client state that was provided when onoff_request() was invoked. Behavior is undefined if this is a pointer to client data associated with an onoff_reset() request.
Return values
ONOFF_STATE_TO_ONif the cancellation occurred before the transition completed.
ONOFF_STATE_ONif the cancellation occurred after the transition completed.
-EINVALif the parameters are invalid.
negativeother errors produced by onoff_release().

◆ onoff_has_error()

static bool onoff_has_error ( const struct onoff_manager mgr)
inlinestatic

#include <zephyr/sys/onoff.h>

Test whether an on-off service has recorded an error.

This function can be used to determine whether the service has recorded an error. Errors may be cleared by invoking onoff_reset().

This is an unlocked convenience function suitable for use only when it is known that no other process might invoke an operation that transitions the service between an error and non-error state.

Returns
true if and only if the service has an uncleared error.

◆ onoff_manager_init()

int onoff_manager_init ( struct onoff_manager mgr,
const struct onoff_transitions transitions 
)

#include <zephyr/sys/onoff.h>

Initialize an on-off service to off state.

This function must be invoked exactly once per service instance, by the infrastructure that provides the service, and before any other on-off service API is invoked on the service.

This function should never be invoked by clients of an on-off service.

Parameters
mgrthe manager definition object to be initialized.
transitionspointer to a structure providing transition functions. The referenced object must persist as long as the manager can be referenced.
Return values
0on success
-EINVALif start, stop, or flags are invalid

◆ onoff_monitor_register()

int onoff_monitor_register ( struct onoff_manager mgr,
struct onoff_monitor mon 
)

#include <zephyr/sys/onoff.h>

Add a monitor of state changes for a manager.

Parameters
mgrthe manager for which a state changes are to be monitored.
mona linkable node providing a non-null callback to be invoked on state changes.
Returns
non-negative on successful addition, or a negative error code.

◆ onoff_monitor_unregister()

int onoff_monitor_unregister ( struct onoff_manager mgr,
struct onoff_monitor mon 
)

#include <zephyr/sys/onoff.h>

Remove a monitor of state changes from a manager.

Parameters
mgrthe manager for which a state changes are to be monitored.
mona linkable node providing the callback to be invoked on state changes.
Returns
non-negative on successful removal, or a negative error code.

◆ onoff_release()

int onoff_release ( struct onoff_manager mgr)

#include <zephyr/sys/onoff.h>

Release a reserved use of an on-off service.

This synchronously releases the caller's previous request. If the last request is released the manager will initiate a transition to off, which can be observed by registering an onoff_monitor.

Note
Behavior is undefined if this is not paired with a preceding onoff_request() call that completed successfully.
Parameters
mgrthe manager for which a request was successful.
Return values
non-negativethe observed state (ONOFF_STATE_ON) of the machine at the time of the release, if the release succeeds.
-EIOif service has recorded an error.
-ENOTSUPif the machine is not in a state that permits release.

◆ onoff_request()

int onoff_request ( struct onoff_manager mgr,
struct onoff_client cli 
)

#include <zephyr/sys/onoff.h>

Request a reservation to use an on-off service.

The return value indicates the success or failure of an attempt to initiate an operation to request the resource be made available. If initiation of the operation succeeds the result of the request operation is provided through the configured client notification method, possibly before this call returns.

Note that the call to this function may succeed in a case where the actual request fails. Always check the operation completion result.

Parameters
mgrthe manager that will be used.
clia non-null pointer to client state providing instructions on synchronous expectations and how to notify the client when the request completes. Behavior is undefined if client passes a pointer object associated with an incomplete service operation.
Return values
non-negativethe observed state of the machine at the time the request was processed, if successful.
-EIOif service has recorded an error.
-EINVALif the parameters are invalid.
-EAGAINif the reference count would overflow.

◆ onoff_reset()

int onoff_reset ( struct onoff_manager mgr,
struct onoff_client cli 
)

#include <zephyr/sys/onoff.h>

Clear errors on an on-off service and reset it to its off state.

A service can only be reset when it is in an error state as indicated by onoff_has_error().

The return value indicates the success or failure of an attempt to initiate an operation to reset the resource. If initiation of the operation succeeds the result of the reset operation itself is provided through the configured client notification method, possibly before this call returns. Multiple clients may request a reset; all are notified when it is complete.

Note that the call to this function may succeed in a case where the actual reset fails. Always check the operation completion result.

Note
Due to the conditions on state transition all incomplete asynchronous operations will have been informed of the error when it occurred. There need be no concern about dangling requests left after a reset completes.
Parameters
mgrthe manager to be reset.
clipointer to client state, including instructions on how to notify the client when reset completes. Behavior is undefined if cli references an object associated with an incomplete service operation.
Return values
non-negativethe observed state of the machine at the time of the reset, if the reset succeeds.
-ENOTSUPif reset is not supported by the service.
-EINVALif the parameters are invalid.
-EALREADYif the service does not have a recorded error.

◆ onoff_sync_finalize()

int onoff_sync_finalize ( struct onoff_sync_service srv,
k_spinlock_key_t  key,
struct onoff_client cli,
int  res,
bool  on 
)

#include <zephyr/sys/onoff.h>

Process the completion of a transition in a synchronous service and release lock.

This function updates the service state on the res and on parameters then releases the lock. If cli is not null it finalizes the client notification using res.

If the service was in an error state when locked, and res is non-negative when finalized, the count is reset to zero before completing finalization.

Parameters
srvpointer to the synchronous service state
keythe key returned by the preceding invocation of onoff_sync_lock().
clipointer to the onoff client through which completion information is returned. If a null pointer is passed only the state of the service is updated. For compatibility with the behavior of callbacks used with the manager API cli must be null when on is false (the manager does not support callbacks when turning off devices).
resthe result of the transition. A negative value places the service into an error state. A non-negative value increments or decrements the reference count as specified by on.
onOnly when res is non-negative, the service reference count will be incremented ifon is true, and decremented if on is false.
Returns
negative if the service is left or put into an error state, otherwise the number of active requests at the time the lock was released.

◆ onoff_sync_lock()

int onoff_sync_lock ( struct onoff_sync_service srv,
k_spinlock_key_t keyp 
)

#include <zephyr/sys/onoff.h>

Lock a synchronous onoff service and provide its state.

Note
If an error state is returned it is the caller's responsibility to decide whether to preserve it (finalize with the same error state) or clear the error (finalize with a non-error result).
Parameters
srvpointer to the synchronous service state.
keyppointer to where the lock key should be stored
Returns
negative if the service is in an error state, otherwise the number of active requests at the time the lock was taken. The lock is held on return regardless of whether a negative state is returned.