1=================================== 2Regulator Consumer Driver Interface 3=================================== 4 5This text describes the regulator interface for consumer device drivers. 6Please see overview.txt for a description of the terms used in this text. 7 8 91. Consumer Regulator Access (static & dynamic drivers) 10======================================================= 11 12A consumer driver can get access to its supply regulator by calling :: 13 14 regulator = regulator_get(dev, "Vcc"); 15 16The consumer passes in its struct device pointer and power supply ID. The core 17then finds the correct regulator by consulting a machine specific lookup table. 18If the lookup is successful then this call will return a pointer to the struct 19regulator that supplies this consumer. 20 21To release the regulator the consumer driver should call :: 22 23 regulator_put(regulator); 24 25Consumers can be supplied by more than one regulator e.g. codec consumer with 26analog and digital supplies by means of bulk operations :: 27 28 struct regulator_bulk_data supplies[2]; 29 30 supplies[0].supply = "Vcc"; /* digital core */ 31 supplies[1].supply = "Avdd"; /* analog */ 32 33 ret = regulator_bulk_get(dev, ARRAY_SIZE(supplies), supplies); 34 35 // convenience helper to call regulator_put() on multiple regulators 36 regulator_bulk_free(ARRAY_SIZE(supplies), supplies); 37 38 39The regulator access functions regulator_get() and regulator_put() will 40usually be called in your device drivers probe() and remove() respectively. 41 42 432. Regulator Output Enable & Disable (static & dynamic drivers) 44=============================================================== 45 46 47A consumer can enable its power supply by calling:: 48 49 int regulator_enable(regulator); 50 51NOTE: 52 The supply may already be enabled before regulator_enable() is called. 53 This may happen if the consumer shares the regulator or the regulator has been 54 previously enabled by bootloader or kernel board initialization code. 55 56A consumer can determine if a regulator is enabled by calling:: 57 58 int regulator_is_enabled(regulator); 59 60This will return > zero when the regulator is enabled. 61 62A set of regulators can be enabled with a single bulk operation :: 63 64 int regulator_bulk_enable(int num_consumers, 65 struct regulator_bulk_data *consumers); 66 67 68A consumer can disable its supply when no longer needed by calling:: 69 70 int regulator_disable(regulator); 71 72Or a number of them :: 73 74 int regulator_bulk_disable(int num_consumers, 75 struct regulator_bulk_data *consumers); 76 77NOTE: 78 This may not disable the supply if it's shared with other consumers. The 79 regulator will only be disabled when the enabled reference count is zero. 80 81Finally, a regulator can be forcefully disabled in the case of an emergency:: 82 83 int regulator_force_disable(regulator); 84 85This operation is also supported for multiple regulators :: 86 87 int regulator_bulk_force_disable(int num_consumers, 88 struct regulator_bulk_data *consumers); 89 90NOTE: 91 this will immediately and forcefully shutdown the regulator output. All 92 consumers will be powered off. 93 943. Regulator Voltage Control & Status (dynamic drivers) 95======================================================= 96 97Some consumer drivers need to be able to dynamically change their supply 98voltage to match system operating points. e.g. CPUfreq drivers can scale 99voltage along with frequency to save power, SD drivers may need to select the 100correct card voltage, etc. 101 102Consumers can control their supply voltage by calling:: 103 104 int regulator_set_voltage(regulator, min_uV, max_uV); 105 106Where min_uV and max_uV are the minimum and maximum acceptable voltages in 107microvolts. 108 109NOTE: this can be called when the regulator is enabled or disabled. If called 110when enabled, then the voltage changes instantly, otherwise the voltage 111configuration changes and the voltage is physically set when the regulator is 112next enabled. 113 114The regulators configured voltage output can be found by calling:: 115 116 int regulator_get_voltage(regulator); 117 118NOTE: 119 get_voltage() will return the configured output voltage whether the 120 regulator is enabled or disabled and should NOT be used to determine regulator 121 output state. However this can be used in conjunction with is_enabled() to 122 determine the regulator physical output voltage. 123 124 1254. Regulator Current Limit Control & Status (dynamic drivers) 126============================================================= 127 128Some consumer drivers need to be able to dynamically change their supply 129current limit to match system operating points. e.g. LCD backlight driver can 130change the current limit to vary the backlight brightness, USB drivers may want 131to set the limit to 500mA when supplying power. 132 133Consumers can control their supply current limit by calling:: 134 135 int regulator_set_current_limit(regulator, min_uA, max_uA); 136 137Where min_uA and max_uA are the minimum and maximum acceptable current limit in 138microamps. 139 140NOTE: 141 this can be called when the regulator is enabled or disabled. If called 142 when enabled, then the current limit changes instantly, otherwise the current 143 limit configuration changes and the current limit is physically set when the 144 regulator is next enabled. 145 146A regulators current limit can be found by calling:: 147 148 int regulator_get_current_limit(regulator); 149 150NOTE: 151 get_current_limit() will return the current limit whether the regulator 152 is enabled or disabled and should not be used to determine regulator current 153 load. 154 155 1565. Regulator Operating Mode Control & Status (dynamic drivers) 157============================================================== 158 159Some consumers can further save system power by changing the operating mode of 160their supply regulator to be more efficient when the consumers operating state 161changes. e.g. consumer driver is idle and subsequently draws less current 162 163Regulator operating mode can be changed indirectly or directly. 164 165Indirect operating mode control. 166-------------------------------- 167Consumer drivers can request a change in their supply regulator operating mode 168by calling:: 169 170 int regulator_set_load(struct regulator *regulator, int load_uA); 171 172This will cause the core to recalculate the total load on the regulator (based 173on all its consumers) and change operating mode (if necessary and permitted) 174to best match the current operating load. 175 176The load_uA value can be determined from the consumer's datasheet. e.g. most 177datasheets have tables showing the maximum current consumed in certain 178situations. 179 180Most consumers will use indirect operating mode control since they have no 181knowledge of the regulator or whether the regulator is shared with other 182consumers. 183 184Direct operating mode control. 185------------------------------ 186 187Bespoke or tightly coupled drivers may want to directly control regulator 188operating mode depending on their operating point. This can be achieved by 189calling:: 190 191 int regulator_set_mode(struct regulator *regulator, unsigned int mode); 192 unsigned int regulator_get_mode(struct regulator *regulator); 193 194Direct mode will only be used by consumers that *know* about the regulator and 195are not sharing the regulator with other consumers. 196 197 1986. Regulator Events 199=================== 200 201Regulators can notify consumers of external events. Events could be received by 202consumers under regulator stress or failure conditions. 203 204Consumers can register interest in regulator events by calling:: 205 206 int regulator_register_notifier(struct regulator *regulator, 207 struct notifier_block *nb); 208 209Consumers can unregister interest by calling:: 210 211 int regulator_unregister_notifier(struct regulator *regulator, 212 struct notifier_block *nb); 213 214Regulators use the kernel notifier framework to send event to their interested 215consumers. 216 2177. Regulator Direct Register Access 218=================================== 219 220Some kinds of power management hardware or firmware are designed such that 221they need to do low-level hardware access to regulators, with no involvement 222from the kernel. Examples of such devices are: 223 224- clocksource with a voltage-controlled oscillator and control logic to change 225 the supply voltage over I2C to achieve a desired output clock rate 226- thermal management firmware that can issue an arbitrary I2C transaction to 227 perform system poweroff during overtemperature conditions 228 229To set up such a device/firmware, various parameters like I2C address of the 230regulator, addresses of various regulator registers etc. need to be configured 231to it. The regulator framework provides the following helpers for querying 232these details. 233 234Bus-specific details, like I2C addresses or transfer rates are handled by the 235regmap framework. To get the regulator's regmap (if supported), use:: 236 237 struct regmap *regulator_get_regmap(struct regulator *regulator); 238 239To obtain the hardware register offset and bitmask for the regulator's voltage 240selector register, use:: 241 242 int regulator_get_hardware_vsel_register(struct regulator *regulator, 243 unsigned *vsel_reg, 244 unsigned *vsel_mask); 245 246To convert a regulator framework voltage selector code (used by 247regulator_list_voltage) to a hardware-specific voltage selector that can be 248directly written to the voltage selector register, use:: 249 250 int regulator_list_hardware_vsel(struct regulator *regulator, 251 unsigned selector); 252 253To access the hardware for enabling/disabling the regulator, consumers must 254use regulator_get_exclusive(), as it can't work if there's more than one 255consumer. To enable/disable regulator use:: 256 257 int regulator_hardware_enable(struct regulator *regulator, bool enable); 258