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