1.. _resource_mgmt:
2
3Resource Management
4###################
5
6There are various situations where it's necessary to coordinate resource
7use at runtime among multiple clients.  These include power rails,
8clocks, other peripherals, and binary device power management. The
9complexity of properly managing multiple consumers of a device in a
10multithreaded system, especially when transitions may be asynchronous,
11suggests that a shared implementation is desirable.
12
13Zephyr provides managers for several coordination policies.  These
14managers are embedded into services that use them for specific
15functions.
16
17.. contents::
18    :local:
19    :depth: 2
20
21.. _resource_mgmt_onoff:
22
23On-Off Manager
24**************
25
26An on-off manager supports an arbitrary number of clients of a service
27which has a binary state.  Example applications are power rails, clocks,
28and binary device power management.
29
30The manager has the following properties:
31
32* The stable states are off, on, and error.  The service always begins
33  in the off state.  The service may also be in a transition to a given
34  state.
35* The core operations are request (add a dependency) and release (remove
36  a dependency). Supporting operations are reset (to clear an error
37  state) and cancel (to reclaim client data from an in-progress
38  transition).  The service manages the state based on calls to
39  functions that initiate these operations.
40* The service transitions from off to on when first client request is
41  received.
42* The service transitions from on to off when last client release is
43  received.
44* Each service configuration provides functions that implement the
45  transition from off to on, from on to off, and optionally from an
46  error state to off.  Transitions must be invokable from both thread
47  and interrupt context.
48* The request and reset operations are asynchronous using
49  :ref:`async_notification`.  Both operations may be cancelled, but
50  cancellation has no effect on the in-progress transition.
51* Requests to turn on may be queued while a transition to off is in
52  progress: when the service has turned off successfully it will be
53  immediately turned on again (where context allows) and waiting clients
54  notified when the start completes.
55
56Requests are reference counted, but not tracked. That means clients are
57responsible for recording whether their requests were accepted, and for
58initiating a release only if they have previously successfully completed
59a request.  Improper use of the API can cause an active client to be
60shut out, and the manager does not maintain a record of specific clients
61that have been granted a request.
62
63Failures in executing a transition are recorded and inhibit further
64requests or releases until the manager is reset. Pending requests are
65notified (and cancelled) when errors are discovered.
66
67Transition operation completion notifications are provided through
68:ref:`async_notification`.
69
70Clients and other components interested in tracking all service state
71changes, including when a service begins turning off or enters an error
72state, can be informed of state transitions by registering a monitor
73with onoff_monitor_register().  Notification of changes are provided
74before issuing completion notifications associated with the new
75state.
76
77.. note::
78
79   A generic API may be implemented by multiple drivers where the common
80   case is asynchronous.  The on-off client structure may be an
81   appropriate solution for the generic API.  Where drivers that can
82   guarantee synchronous context-independent transitions a driver may
83   use :c:type:`onoff_sync_service` and its supporting API rather than
84   :c:type:`onoff_manager`, with only a small reduction in functionality
85   (primarily no support for the monitor API).
86
87.. doxygengroup:: resource_mgmt_onoff_apis
88