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