Documentation/power/regulator/overview.txt

   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 <lg@opensource.wolfsonmicro.com>
  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 it's supply voltage or
  39                    current limit. It only needs to enable or disable it's
  40                    power supply. It's supply voltage is set by the hardware,
  41                    bootloader, firmware or kernel board initialisation code.
  42
  43                    Dynamic: consumer needs to change it's supply voltage or
  44                    current limit to meet operation demands.
  45
  46
  47   o Power Domain - Electronic circuit that is supplied it's 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 over current 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