========================== Regulator API design notes ========================== This document provides a brief, partially structured, overview of some of the design considerations which impact the regulator API design. Safety ------ - Errors in regulator configuration can have very serious consequences for the system, potentially including lasting hardware damage. - It is not possible to automatically determine the power configuration of the system - software-equivalent variants of the same chip may have different power requirements, and not all components with power requirements are visible to software. .. note:: The API should make no changes to the hardware state unless it has specific knowledge that these changes are safe to perform on this particular system. Consumer use cases ------------------ - The overwhelming majority of devices in a system will have no requirement to do any runtime configuration of their power beyond being able to turn it on or off. - Many of the power supplies in the system will be shared between many different consumers. .. note:: The consumer API should be structured so that these use cases are very easy to handle and so that consumers will work with shared supplies without any additional effort.