84 lines
3.7 KiB
ReStructuredText
84 lines
3.7 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.
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 2
|
|
|
|
|
|
On-Off Services
|
|
***************
|
|
|
|
An on-off service 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 service 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). 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 that may put a calling thread to
|
|
sleep must be flagged in the configuration to support safe invocation
|
|
from non-thread context.
|
|
* All operations are asynchronous, and are initiated by a function call
|
|
that references a specific service and is given client notification
|
|
data. The function call will succeed or fail. On success, the
|
|
operation is guaranteed to be initiated, but whether the operation
|
|
itself succeeds or fails is indicated through client notification.
|
|
The initiation functions can be invoked from pre-kernel, thread, or
|
|
ISR context. In contexts and states where the operation cannot
|
|
be started the function will result in an error.
|
|
* 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 service 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 service is reset. Pending requests are
|
|
notified (and cancelled) when errors are discovered.
|
|
|
|
Transition operation completion notifications are provided through any
|
|
of the following mechanisms:
|
|
|
|
* Signal: A pointer to a :c:type:`struct k_poll_signal` is provided, and
|
|
the signal is raised when the transition completes. The operation
|
|
completion code is stored as the signal value.
|
|
* Callback: a function pointer is provided by the client along with an
|
|
opaque pointer, and on completion of the operation the function is
|
|
invoked with the pointer and the operation completion code.
|
|
* Spin-wait: the client is required to check for operation completion
|
|
using the :cpp:func:`onoff_client_fetch_result()` function.
|
|
|
|
Synchronous transition may be implemented by a caller based on its
|
|
context, for example by using :cpp:func:`k_poll()` to wait until the
|
|
completion is signalled.
|
|
|
|
.. doxygengroup:: resource_mgmt_apis
|
|
:project: Zephyr
|