Documentation/power/regulator/consumer.rst

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