0001 ==========================
0002 Regulator API design notes
0003 ==========================
0004
0005 This document provides a brief, partially structured, overview of some
0006 of the design considerations which impact the regulator API design.
0007
0008 Safety
0009 ------
0010
0011 - Errors in regulator configuration can have very serious consequences
0012 for the system, potentially including lasting hardware damage.
0013 - It is not possible to automatically determine the power configuration
0014 of the system - software-equivalent variants of the same chip may
0015 have different power requirements, and not all components with power
0016 requirements are visible to software.
0017
0018 .. note::
0019
0020 The API should make no changes to the hardware state unless it has
0021 specific knowledge that these changes are safe to perform on this
0022 particular system.
0023
0024 Consumer use cases
0025 ------------------
0026
0027 - The overwhelming majority of devices in a system will have no
0028 requirement to do any runtime configuration of their power beyond
0029 being able to turn it on or off.
0030
0031 - Many of the power supplies in the system will be shared between many
0032 different consumers.
0033
0034 .. note::
0035
0036 The consumer API should be structured so that these use cases are
0037 very easy to handle and so that consumers will work with shared
0038 supplies without any additional effort.
