1=============================================
2Linux voltage and current regulator framework
3=============================================
4
5About
6=====
7
8This framework is designed to provide a standard kernel interface to control
9voltage and current regulators.
10
11The intention is to allow systems to dynamically control regulator power output
12in order to save power and prolong battery life. This applies to both voltage
13regulators (where voltage output is controllable) and current sinks (where
14current limit is controllable).
15
16(C) 2008  Wolfson Microelectronics PLC.
17
18Author: Liam Girdwood <lrg@slimlogic.co.uk>
19
20
21Nomenclature
22============
23
24Some 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
135Design
136======
137
138The framework is designed and targeted at SoC based devices but may also be
139relevant 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
179