14e2ca4f16
The previous architecture proved unable to support user expectations, so the API has been rebuilt from first principles. Backward compatibility cannot be maintained for this change. Key changes include: * Formerly the service-provided transition functions were allowed to sleep, and the manager took care to not invoke them from ISR context, instead returning an error if unable to initiate a transition. In the new architecture transition functions are required to work regardless of calling context: it is the service's responsibility to guarantee the transition will proceed even if it needs to be transferred to a thread. This eliminates state machine complexities related to calling context. * Constants identifying the visible state of the manager are exposed to clients through both notification callbacks and a new monitor API that allows clients to be notified of all state changes. * Formerly the release operation was async, and would be delayed for the last release to ensure a client would exist to be notified of any failures. It is now synchronous. * Formerly the cancel operation would fail on the last client associated with a transition. The cancel operation is now synchronous. * A helper function is provided to safely synchronously release a request regardless of whether it has completed or is in progress, satisfying the use case underlying #22974. * The user-data parameter to asynchronous notification callbacks has been removed as user data can be retrieved from the CONTAINER_OF the client data. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
79 lines
3.2 KiB
ReStructuredText
79 lines
3.2 KiB
ReStructuredText
.. _resource_mgmt:
|
|
|
|
Resource Management
|
|
###################
|
|
|
|
There are various situations where it's necessary to coordinate resource
|
|
use at runtime among multiple clients. These include power rails,
|
|
clocks, other peripherals, and binary device power management. The
|
|
complexity of properly managing multiple consumers of a device in a
|
|
multithreaded system, especially when transitions may be asynchronous,
|
|
suggests that a shared implementation is desirable.
|
|
|
|
Zephyr provides managers for several coordination policies. These
|
|
managers are embedded into services that use them for specific
|
|
functions.
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 2
|
|
|
|
.. _resource_mgmt_onoff:
|
|
|
|
On-Off Manager
|
|
**************
|
|
|
|
An on-off manager supports an arbitrary number of clients of a service
|
|
which has a binary state. Example applications are power rails, clocks,
|
|
and binary device power management.
|
|
|
|
The manager has the following properties:
|
|
|
|
* The stable states are off, on, and error. The service always begins
|
|
in the off state. The service may also be in a transition to a given
|
|
state.
|
|
* The core operations are request (add a dependency) and release (remove
|
|
a dependency). Supporting operations are reset (to clear an error
|
|
state) and cancel (to reclaim client data from an in-progress
|
|
transition). The service manages the state based on calls to
|
|
functions that initiate these operations.
|
|
* The service transitions from off to on when first client request is
|
|
received.
|
|
* The service transitions from on to off when last client release is
|
|
received.
|
|
* Each service configuration provides functions that implement the
|
|
transition from off to on, from on to off, and optionally from an
|
|
error state to off. Transitions must be invokable from both thread
|
|
and interrupt context.
|
|
* The request and reset operations are asynchronous using
|
|
:ref:`async_notification`. Both operations may be cancelled, but
|
|
cancellation has no effect on the in-progress transition.
|
|
* Requests to turn on may be queued while a transition to off is in
|
|
progress: when the service has turned off successfully it will be
|
|
immediately turned on again (where context allows) and waiting clients
|
|
notified when the start completes.
|
|
|
|
Requests are reference counted, but not tracked. That means clients are
|
|
responsible for recording whether their requests were accepted, and for
|
|
initiating a release only if they have previously successfully completed
|
|
a request. Improper use of the API can cause an active client to be
|
|
shut out, and the manager does not maintain a record of specific clients
|
|
that have been granted a request.
|
|
|
|
Failures in executing a transition are recorded and inhibit further
|
|
requests or releases until the manager is reset. Pending requests are
|
|
notified (and cancelled) when errors are discovered.
|
|
|
|
Transition operation completion notifications are provided through
|
|
:ref:`async_notification`.
|
|
|
|
Clients and other components interested in tracking all service state
|
|
changes, including when a service begins turning off or enters an error
|
|
state, can be informed of state transitions by registering a monitor
|
|
with onoff_monitor_register(). Notification of changes are provided
|
|
before issuing completion notifications associated with the new
|
|
state.
|
|
|
|
.. doxygengroup:: resource_mgmt_onoff_apis
|
|
:project: Zephyr
|