Documentation/power/regulator/overview.rst

   1 =============================================
   2 Linux voltage and current regulator framework
   3 =============================================
   4
   5 About
   6 =====
   7
   8 This framework is designed to provide a standard kernel interface to control
   9 voltage and current regulators.
  10
  11 The intention is to allow systems to dynamically control regulator power output
  12 in order to save power and prolong battery life. This applies to both voltage
  13 regulators (where voltage output is controllable) and current sinks (where
  14 current limit is controllable).
  15
  16 (C) 2008  Wolfson Microelectronics PLC.
  17
  18 Author: Liam Girdwood <lrg@slimlogic.co.uk>
  19
  20
  21 Nomenclature
  22 ============
  23
  24 Some terms used in this document:
  25
  26   - Regulator
  27                  - Electronic device that supplies power to other devices.
  28                    Most regulators can enable and disable their output while
  29                    some can control their output voltage and or current.
  30
  31                    Input Voltage -> Regulator -> Output Voltage
  32
  33
  34   - PMIC
  35                  - Power Management IC. An IC that contains numerous
  36                    regulators and often contains other subsystems.
  37
  38
  39   - Consumer
  40                  - Electronic device that is supplied power by a regulator.
  41                    Consumers can be classified into two types:-
  42
  43                    Static: consumer does not change its supply voltage or
  44                    current limit. It only needs to enable or disable its
  45                    power supply. Its supply voltage is set by the hardware,
  46                    bootloader, firmware or kernel board initialisation code.
  47
  48                    Dynamic: consumer needs to change its supply voltage or
  49                    current limit to meet operation demands.
  50
  51
  52   - Power Domain
  53                  - Electronic circuit that is supplied its input power by the
  54                    output power of a regulator, switch or by another power
  55                    domain.
  56
  57                    The supply regulator may be behind a switch(s). i.e.::
  58
  59                      Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
  60                                 |             |
  61                                 |             +-> [Consumer B], [Consumer C]
  62                                 |
  63                                 +-> [Consumer D], [Consumer E]
  64
  65                    That is one regulator and three power domains:
  66
  67                    - Domain 1: Switch-1, Consumers D & E.
  68                    - Domain 2: Switch-2, Consumers B & C.
  69                    - Domain 3: Consumer A.
  70
  71                    and this represents a "supplies" relationship:
  72
  73                    Domain-1 --> Domain-2 --> Domain-3.
  74
  75                    A power domain may have regulators that are supplied power
  76                    by other regulators. i.e.::
  77
  78                      Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
  79                                   |
  80                                   +-> [Consumer B]
  81
  82                    This gives us two regulators and two power domains:
  83
  84                    - Domain 1: Regulator-2, Consumer B.
  85                    - Domain 2: Consumer A.
  86
  87                    and a "supplies" relationship:
  88
  89                    Domain-1 --> Domain-2
  90
  91
  92   - Constraints
  93                  - Constraints are used to define power levels for performance
  94                    and hardware protection. Constraints exist at three levels:
  95
  96                    Regulator Level: This is defined by the regulator hardware
  97                    operating parameters and is specified in the regulator
  98                    datasheet. i.e.
  99
 100                      - voltage output is in the range 800mV -> 3500mV.
 101                      - regulator current output limit is 20mA @ 5V but is
 102                        10mA @ 10V.
 103
 104                    Power Domain Level: This is defined in software by kernel
 105                    level board initialisation code. It is used to constrain a
 106                    power domain to a particular power range. i.e.
 107
 108                      - Domain-1 voltage is 3300mV
 109                      - Domain-2 voltage is 1400mV -> 1600mV
 110                      - Domain-3 current limit is 0mA -> 20mA.
 111
 112                    Consumer Level: This is defined by consumer drivers
 113                    dynamically setting voltage or current limit levels.
 114
 115                    e.g. a consumer backlight driver asks for a current increase
 116                    from 5mA to 10mA to increase LCD illumination. This passes
 117                    to through the levels as follows :-
 118
 119                    Consumer: need to increase LCD brightness. Lookup and
 120                    request next current mA value in brightness table (the
 121                    consumer driver could be used on several different
 122                    personalities based upon the same reference device).
 123
 124                    Power Domain: is the new current limit within the domain
 125                    operating limits for this domain and system state (e.g.
 126                    battery power, USB power)
 127
 128                    Regulator Domains: is the new current limit within the
 129                    regulator operating parameters for input/output voltage.
 130
 131                    If the regulator request passes all the constraint tests
 132                    then the new regulator value is applied.
 133
 134
 135 Design
 136 ======
 137
 138 The framework is designed and targeted at SoC based devices but may also be
 139 relevant to non SoC devices and is split into the following four interfaces:-
 140
 141
 142    1. Consumer driver interface.
 143
 144       This uses a similar API to the kernel clock interface in that consumer
 145       drivers can get and put a regulator (like they can with clocks atm) and
 146       get/set voltage, current limit, mode, enable and disable. This should
 147       allow consumers complete control over their supply voltage and current
 148       limit. This also compiles out if not in use so drivers can be reused in
 149       systems with no regulator based power control.
 150
 151         See Documentation/power/regulator/consumer.rst
 152
 153    2. Regulator driver interface.
 154
 155       This allows regulator drivers to register their regulators and provide
 156       operations to the core. It also has a notifier call chain for propagating
 157       regulator events to clients.
 158
 159         See Documentation/power/regulator/regulator.rst
 160
 161    3. Machine interface.
 162
 163       This interface is for machine specific code and allows the creation of
 164       voltage/current domains (with constraints) for each regulator. It can
 165       provide regulator constraints that will prevent device damage through
 166       overvoltage or overcurrent caused by buggy client drivers. It also
 167       allows the creation of a regulator tree whereby some regulators are
 168       supplied by others (similar to a clock tree).
 169
 170         See Documentation/power/regulator/machine.rst
 171
 172    4. Userspace ABI.
 173
 174       The framework also exports a lot of useful voltage/current/opmode data to
 175       userspace via sysfs. This could be used to help monitor device power
 176       consumption and status.
 177
 178         See Documentation/ABI/testing/sysfs-class-regulator