Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
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. 16 Author: Liam Girdwood <lrg@slimlogic.co.uk> 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 32 and often contains other subsystems. 33 34 35 o Consumer - Electronic device that is supplied power by a regulator. 36 Consumers can be classified into two types:- 37 38 Static: consumer does not change its supply voltage or 39 current limit. It only needs to enable or disable its 40 power supply. Its supply voltage is set by the hardware, 41 bootloader, firmware or kernel board initialisation code. 42 43 Dynamic: consumer needs to change its supply voltage or 44 current limit to meet operation demands. 45 46 47 o Power Domain - Electronic circuit that is supplied its input power by the 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 122 regulator operating parameters for input/output voltage. 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 overcurrent 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 171 See Documentation/ABI/testing/sysfs-class-regulator