| ========================== |
| 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. |
