Orange Pi5 kernel

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