Liam Girdwood | 8e6f084 | 2008-04-30 17:16:51 +0100 | [diff] [blame] | 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. |
Mark Brown | 606b2f4 | 2010-08-27 22:33:38 +0100 | [diff] [blame^] | 16 | Author: Liam Girdwood <lrg@slimlogic.co.uk> |
Liam Girdwood | 8e6f084 | 2008-04-30 17:16:51 +0100 | [diff] [blame] | 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. |
| 25 | Most regulators can enable and disable their output whilst |
| 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 |
Linus Walleij | 040932c | 2009-08-21 14:00:57 +0200 | [diff] [blame] | 32 | and often contains other subsystems. |
Liam Girdwood | 8e6f084 | 2008-04-30 17:16:51 +0100 | [diff] [blame] | 33 | |
| 34 | |
| 35 | o Consumer - Electronic device that is supplied power by a regulator. |
| 36 | Consumers can be classified into two types:- |
| 37 | |
Francis Galiegue | a33f322 | 2010-04-23 00:08:02 +0200 | [diff] [blame] | 38 | Static: consumer does not change its supply voltage or |
Liam Girdwood | 8e6f084 | 2008-04-30 17:16:51 +0100 | [diff] [blame] | 39 | current limit. It only needs to enable or disable it's |
Francis Galiegue | a33f322 | 2010-04-23 00:08:02 +0200 | [diff] [blame] | 40 | power supply. Its supply voltage is set by the hardware, |
Liam Girdwood | 8e6f084 | 2008-04-30 17:16:51 +0100 | [diff] [blame] | 41 | bootloader, firmware or kernel board initialisation code. |
| 42 | |
| 43 | Dynamic: consumer needs to change it's supply voltage or |
| 44 | current limit to meet operation demands. |
| 45 | |
| 46 | |
Francis Galiegue | a33f322 | 2010-04-23 00:08:02 +0200 | [diff] [blame] | 47 | o Power Domain - Electronic circuit that is supplied its input power by the |
Liam Girdwood | 8e6f084 | 2008-04-30 17:16:51 +0100 | [diff] [blame] | 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 |
Matt LaPlante | 19f5946 | 2009-04-27 15:06:31 +0200 | [diff] [blame] | 122 | regulator operating parameters for input/output voltage. |
Liam Girdwood | 8e6f084 | 2008-04-30 17:16:51 +0100 | [diff] [blame] | 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 |
| 159 | overvoltage or over current caused by buggy client drivers. It also |
| 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 | |
Wolfram Sang | 77bb8ff | 2009-09-06 21:30:18 +0200 | [diff] [blame] | 171 | See Documentation/ABI/testing/sysfs-class-regulator |