[deliverable/linux.git] / Documentation / power / regulator / design.txt

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.

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

  => 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.
Commit	Line	Data
63209a71 MB	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.
3a4c6959	12	- It is not possible to automatically determine the power configuration
63209a71	13	of the system - software-equivalent variants of the same chip may
3a4c6959	14	have different power requirements, and not all components with power
63209a71 MB	15	requirements are visible to software.
	16
	17	=> The API should make no changes to the hardware state unless it has
3a4c6959 GU	18	specific knowledge that these changes are safe to perform on this
3a4c6959 GU	19	particular system.
63209a71 MB	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.