1==========================
2Regulator API design notes
3==========================
4
5This document provides a brief, partially structured, overview of some
6of the design considerations which impact the regulator API design.
7
8Safety
9------
10
11 - Errors in regulator configuration can have very serious consequences
12   for the system, potentially including lasting hardware damage.
13 - It is not possible to automatically determine the power configuration
14   of the system - software-equivalent variants of the same chip may
15   have different power requirements, and not all components with power
16   requirements are visible to software.
17
18.. note::
19
20     The API should make no changes to the hardware state unless it has
21     specific knowledge that these changes are safe to perform on this
22     particular system.
23
24Consumer use cases
25------------------
26
27 - The overwhelming majority of devices in a system will have no
28   requirement to do any runtime configuration of their power beyond
29   being able to turn it on or off.
30
31 - Many of the power supplies in the system will be shared between many
32   different consumers.
33
34.. note::
35
36     The consumer API should be structured so that these use cases are
37     very easy to handle and so that consumers will work with shared
38     supplies without any additional effort.
39