[linux-2.6-block.git] / Documentation / power / regulator / overview.txt

Linux voltage and current regulator framework
=============================================

About
=====

This framework is designed to provide a standard kernel interface to control
voltage and current regulators.

The intention is to allow systems to dynamically control regulator power output
in order to save power and prolong battery life. This applies to both voltage
regulators (where voltage output is controllable) and current sinks (where
current limit is controllable).

(C) 2008  Wolfson Microelectronics PLC.
Author: Liam Girdwood <lrg@slimlogic.co.uk>


Nomenclature
============

Some terms used in this document:-

  o Regulator    - Electronic device that supplies power to other devices.
                   Most regulators can enable and disable their output while
                   some can control their output voltage and or current.

                   Input Voltage -> Regulator -> Output Voltage


  o PMIC         - Power Management IC. An IC that contains numerous regulators
                   and often contains other subsystems.


  o Consumer     - Electronic device that is supplied power by a regulator.
                   Consumers can be classified into two types:-

                   Static: consumer does not change its supply voltage or
                   current limit. It only needs to enable or disable its
                   power supply. Its supply voltage is set by the hardware,
                   bootloader, firmware or kernel board initialisation code.

                   Dynamic: consumer needs to change its supply voltage or
                   current limit to meet operation demands.


  o Power Domain - Electronic circuit that is supplied its input power by the
                   output power of a regulator, switch or by another power
                   domain.

                   The supply regulator may be behind a switch(s). i.e.

                   Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
                              |             |
                              |             +-> [Consumer B], [Consumer C]
                              |
                              +-> [Consumer D], [Consumer E]

                   That is one regulator and three power domains:

                   Domain 1: Switch-1, Consumers D & E.
                   Domain 2: Switch-2, Consumers B & C.
                   Domain 3: Consumer A.

                   and this represents a "supplies" relationship:

                   Domain-1 --> Domain-2 --> Domain-3.

                   A power domain may have regulators that are supplied power
                   by other regulators. i.e.

                   Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
                                |
                                +-> [Consumer B]

                   This gives us two regulators and two power domains:

                   Domain 1: Regulator-2, Consumer B.
                   Domain 2: Consumer A.

                   and a "supplies" relationship:

                   Domain-1 --> Domain-2


  o Constraints  - Constraints are used to define power levels for performance
                   and hardware protection. Constraints exist at three levels:

                   Regulator Level: This is defined by the regulator hardware
                   operating parameters and is specified in the regulator
                   datasheet. i.e.

                     - voltage output is in the range 800mV -> 3500mV.
                     - regulator current output limit is 20mA @ 5V but is
                       10mA @ 10V.

                   Power Domain Level: This is defined in software by kernel
                   level board initialisation code. It is used to constrain a
                   power domain to a particular power range. i.e.

                     - Domain-1 voltage is 3300mV
                     - Domain-2 voltage is 1400mV -> 1600mV
                     - Domain-3 current limit is 0mA -> 20mA.

                   Consumer Level: This is defined by consumer drivers
                   dynamically setting voltage or current limit levels.

                   e.g. a consumer backlight driver asks for a current increase
                   from 5mA to 10mA to increase LCD illumination. This passes
                   to through the levels as follows :-

                   Consumer: need to increase LCD brightness. Lookup and
                   request next current mA value in brightness table (the
                   consumer driver could be used on several different
                   personalities based upon the same reference device).

                   Power Domain: is the new current limit within the domain
                   operating limits for this domain and system state (e.g.
                   battery power, USB power)

                   Regulator Domains: is the new current limit within the
                   regulator operating parameters for input/output voltage.

                   If the regulator request passes all the constraint tests
                   then the new regulator value is applied.


Design
======

The framework is designed and targeted at SoC based devices but may also be
relevant to non SoC devices and is split into the following four interfaces:-


   1. Consumer driver interface.

      This uses a similar API to the kernel clock interface in that consumer
      drivers can get and put a regulator (like they can with clocks atm) and
      get/set voltage, current limit, mode, enable and disable. This should
      allow consumers complete control over their supply voltage and current
      limit. This also compiles out if not in use so drivers can be reused in
      systems with no regulator based power control.

        See Documentation/power/regulator/consumer.txt

   2. Regulator driver interface.

      This allows regulator drivers to register their regulators and provide
      operations to the core. It also has a notifier call chain for propagating
      regulator events to clients.

        See Documentation/power/regulator/regulator.txt

   3. Machine interface.

      This interface is for machine specific code and allows the creation of
      voltage/current domains (with constraints) for each regulator. It can
      provide regulator constraints that will prevent device damage through
      overvoltage or overcurrent caused by buggy client drivers. It also
      allows the creation of a regulator tree whereby some regulators are
      supplied by others (similar to a clock tree).

        See Documentation/power/regulator/machine.txt

   4. Userspace ABI.

      The framework also exports a lot of useful voltage/current/opmode data to
      userspace via sysfs. This could be used to help monitor device power
      consumption and status.

        See Documentation/ABI/testing/sysfs-class-regulator
Commit	Line	Data
8e6f0848 LG	1	Linux voltage and current regulator framework
	2	=============================================
	3
	4	About
	5	=====
	6
	7	This framework is designed to provide a standard kernel interface to control
	8	voltage and current regulators.
	9
	10	The intention is to allow systems to dynamically control regulator power output
	11	in order to save power and prolong battery life. This applies to both voltage
	12	regulators (where voltage output is controllable) and current sinks (where
	13	current limit is controllable).
	14
	15	(C) 2008 Wolfson Microelectronics PLC.
606b2f49	16	Author: Liam Girdwood <lrg@slimlogic.co.uk>
8e6f0848 LG	17
	18
	19	Nomenclature
	20	============
	21
	22	Some terms used in this document:-
	23
	24	o Regulator - Electronic device that supplies power to other devices.
806654a9	25	Most regulators can enable and disable their output while
8e6f0848 LG	26	some can control their output voltage and or current.
	27
	28	Input Voltage -> Regulator -> Output Voltage
	29
	30
	31	o PMIC - Power Management IC. An IC that contains numerous regulators
040932cd	32	and often contains other subsystems.
8e6f0848 LG	33
	34
	35	o Consumer - Electronic device that is supplied power by a regulator.
	36	Consumers can be classified into two types:-
	37
a33f3224	38	Static: consumer does not change its supply voltage or
3a4c6959	39	current limit. It only needs to enable or disable its
a33f3224	40	power supply. Its supply voltage is set by the hardware,
8e6f0848 LG	41	bootloader, firmware or kernel board initialisation code.
8e6f0848 LG	42
3a4c6959	43	Dynamic: consumer needs to change its supply voltage or
8e6f0848 LG	44	current limit to meet operation demands.
	45
	46
a33f3224	47	o Power Domain - Electronic circuit that is supplied its input power by the
8e6f0848 LG	48	output power of a regulator, switch or by another power
	49	domain.
	50
	51	The supply regulator may be behind a switch(s). i.e.
	52
	53	Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
	54	\| \|
	55	\| +-> [Consumer B], [Consumer C]
	56	\|
	57	+-> [Consumer D], [Consumer E]
	58
	59	That is one regulator and three power domains:
	60
	61	Domain 1: Switch-1, Consumers D & E.
	62	Domain 2: Switch-2, Consumers B & C.
	63	Domain 3: Consumer A.
	64
	65	and this represents a "supplies" relationship:
	66
	67	Domain-1 --> Domain-2 --> Domain-3.
	68
	69	A power domain may have regulators that are supplied power
	70	by other regulators. i.e.
	71
	72	Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
	73	\|
	74	+-> [Consumer B]
	75
	76	This gives us two regulators and two power domains:
	77
	78	Domain 1: Regulator-2, Consumer B.
	79	Domain 2: Consumer A.
	80
	81	and a "supplies" relationship:
	82
	83	Domain-1 --> Domain-2
	84
	85
	86	o Constraints - Constraints are used to define power levels for performance
	87	and hardware protection. Constraints exist at three levels:
	88
	89	Regulator Level: This is defined by the regulator hardware
	90	operating parameters and is specified in the regulator
	91	datasheet. i.e.
	92
	93	- voltage output is in the range 800mV -> 3500mV.
	94	- regulator current output limit is 20mA @ 5V but is
	95	10mA @ 10V.
	96
	97	Power Domain Level: This is defined in software by kernel
	98	level board initialisation code. It is used to constrain a
	99	power domain to a particular power range. i.e.
	100
	101	- Domain-1 voltage is 3300mV
	102	- Domain-2 voltage is 1400mV -> 1600mV
	103	- Domain-3 current limit is 0mA -> 20mA.
	104
	105	Consumer Level: This is defined by consumer drivers
	106	dynamically setting voltage or current limit levels.
	107
	108	e.g. a consumer backlight driver asks for a current increase
	109	from 5mA to 10mA to increase LCD illumination. This passes
	110	to through the levels as follows :-
	111
112	Consumer: need to increase LCD brightness. Lookup and
113	request next current mA value in brightness table (the
114	consumer driver could be used on several different
115	personalities based upon the same reference device).
116
117	Power Domain: is the new current limit within the domain
118	operating limits for this domain and system state (e.g.
119	battery power, USB power)
120
121	Regulator Domains: is the new current limit within the
19f59460	122	regulator operating parameters for input/output voltage.
8e6f0848 LG	123
	124	If the regulator request passes all the constraint tests
	125	then the new regulator value is applied.
	126
	127
	128	Design
	129	======
	130
	131	The framework is designed and targeted at SoC based devices but may also be
	132	relevant to non SoC devices and is split into the following four interfaces:-
	133
	134
	135	1. Consumer driver interface.
	136
	137	This uses a similar API to the kernel clock interface in that consumer
	138	drivers can get and put a regulator (like they can with clocks atm) and
	139	get/set voltage, current limit, mode, enable and disable. This should
	140	allow consumers complete control over their supply voltage and current
	141	limit. This also compiles out if not in use so drivers can be reused in
	142	systems with no regulator based power control.
	143
	144	See Documentation/power/regulator/consumer.txt
	145
	146	2. Regulator driver interface.
	147
	148	This allows regulator drivers to register their regulators and provide
	149	operations to the core. It also has a notifier call chain for propagating
	150	regulator events to clients.
	151
	152	See Documentation/power/regulator/regulator.txt
	153
	154	3. Machine interface.
	155
	156	This interface is for machine specific code and allows the creation of
	157	voltage/current domains (with constraints) for each regulator. It can
	158	provide regulator constraints that will prevent device damage through
3a4c6959	159	overvoltage or overcurrent caused by buggy client drivers. It also
8e6f0848 LG	160	allows the creation of a regulator tree whereby some regulators are
	161	supplied by others (similar to a clock tree).
	162
	163	See Documentation/power/regulator/machine.txt
	164
	165	4. Userspace ABI.
	166
	167	The framework also exports a lot of useful voltage/current/opmode data to
	168	userspace via sysfs. This could be used to help monitor device power
	169	consumption and status.
	170
77bb8ff9	171	See Documentation/ABI/testing/sysfs-class-regulator