|
|
@@ -0,0 +1,171 @@
|
|
|
+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 <lg@opensource.wolfsonmicro.com>
|
|
|
+
|
|
|
+
|
|
|
+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 whilst
|
|
|
+ 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 susbsystems.
|
|
|
+
|
|
|
+
|
|
|
+ o Consumer - Electronic device that is supplied power by a regulator.
|
|
|
+ Consumers can be classified into two types:-
|
|
|
+
|
|
|
+ Static: consumer does not change it's supply voltage or
|
|
|
+ current limit. It only needs to enable or disable it's
|
|
|
+ power supply. It's supply voltage is set by the hardware,
|
|
|
+ bootloader, firmware or kernel board initialisation code.
|
|
|
+
|
|
|
+ Dynamic: consumer needs to change it's supply voltage or
|
|
|
+ current limit to meet operation demands.
|
|
|
+
|
|
|
+
|
|
|
+ o Power Domain - Electronic circuit that is supplied it's 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/ouput 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 over current 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/regulator-sysfs.txt
|
Liam Girdwood