18c2ecf20Sopenharmony_ci========================== 28c2ecf20Sopenharmony_ciRegulator API design notes 38c2ecf20Sopenharmony_ci========================== 48c2ecf20Sopenharmony_ci 58c2ecf20Sopenharmony_ciThis document provides a brief, partially structured, overview of some 68c2ecf20Sopenharmony_ciof the design considerations which impact the regulator API design. 78c2ecf20Sopenharmony_ci 88c2ecf20Sopenharmony_ciSafety 98c2ecf20Sopenharmony_ci------ 108c2ecf20Sopenharmony_ci 118c2ecf20Sopenharmony_ci - Errors in regulator configuration can have very serious consequences 128c2ecf20Sopenharmony_ci for the system, potentially including lasting hardware damage. 138c2ecf20Sopenharmony_ci - It is not possible to automatically determine the power configuration 148c2ecf20Sopenharmony_ci of the system - software-equivalent variants of the same chip may 158c2ecf20Sopenharmony_ci have different power requirements, and not all components with power 168c2ecf20Sopenharmony_ci requirements are visible to software. 178c2ecf20Sopenharmony_ci 188c2ecf20Sopenharmony_ci.. note:: 198c2ecf20Sopenharmony_ci 208c2ecf20Sopenharmony_ci The API should make no changes to the hardware state unless it has 218c2ecf20Sopenharmony_ci specific knowledge that these changes are safe to perform on this 228c2ecf20Sopenharmony_ci particular system. 238c2ecf20Sopenharmony_ci 248c2ecf20Sopenharmony_ciConsumer use cases 258c2ecf20Sopenharmony_ci------------------ 268c2ecf20Sopenharmony_ci 278c2ecf20Sopenharmony_ci - The overwhelming majority of devices in a system will have no 288c2ecf20Sopenharmony_ci requirement to do any runtime configuration of their power beyond 298c2ecf20Sopenharmony_ci being able to turn it on or off. 308c2ecf20Sopenharmony_ci 318c2ecf20Sopenharmony_ci - Many of the power supplies in the system will be shared between many 328c2ecf20Sopenharmony_ci different consumers. 338c2ecf20Sopenharmony_ci 348c2ecf20Sopenharmony_ci.. note:: 358c2ecf20Sopenharmony_ci 368c2ecf20Sopenharmony_ci The consumer API should be structured so that these use cases are 378c2ecf20Sopenharmony_ci very easy to handle and so that consumers will work with shared 388c2ecf20Sopenharmony_ci supplies without any additional effort. 39