Documentation/power/regulator/consumer.txt

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