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