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