0001 =============================================
0002 Linux voltage and current regulator framework
0003 =============================================
0004
0005 About
0006 =====
0007
0008 This framework is designed to provide a standard kernel interface to control
0009 voltage and current regulators.
0010
0011 The intention is to allow systems to dynamically control regulator power output
0012 in order to save power and prolong battery life. This applies to both voltage
0013 regulators (where voltage output is controllable) and current sinks (where
0014 current limit is controllable).
0015
0016 (C) 2008 Wolfson Microelectronics PLC.
0017
0018 Author: Liam Girdwood <lrg@slimlogic.co.uk>
0019
0020
0021 Nomenclature
0022 ============
0023
0024 Some terms used in this document:
0025
0026 - Regulator
0027 - Electronic device that supplies power to other devices.
0028 Most regulators can enable and disable their output while
0029 some can control their output voltage and or current.
0030
0031 Input Voltage -> Regulator -> Output Voltage
0032
0033
0034 - PMIC
0035 - Power Management IC. An IC that contains numerous
0036 regulators and often contains other subsystems.
0037
0038
0039 - Consumer
0040 - Electronic device that is supplied power by a regulator.
0041 Consumers can be classified into two types:-
0042
0043 Static: consumer does not change its supply voltage or
0044 current limit. It only needs to enable or disable its
0045 power supply. Its supply voltage is set by the hardware,
0046 bootloader, firmware or kernel board initialisation code.
0047
0048 Dynamic: consumer needs to change its supply voltage or
0049 current limit to meet operation demands.
0050
0051
0052 - Power Domain
0053 - Electronic circuit that is supplied its input power by the
0054 output power of a regulator, switch or by another power
0055 domain.
0056
0057 The supply regulator may be behind a switch(s). i.e.::
0058
0059 Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
0060 | |
0061 | +-> [Consumer B], [Consumer C]
0062 |
0063 +-> [Consumer D], [Consumer E]
0064
0065 That is one regulator and three power domains:
0066
0067 - Domain 1: Switch-1, Consumers D & E.
0068 - Domain 2: Switch-2, Consumers B & C.
0069 - Domain 3: Consumer A.
0070
0071 and this represents a "supplies" relationship:
0072
0073 Domain-1 --> Domain-2 --> Domain-3.
0074
0075 A power domain may have regulators that are supplied power
0076 by other regulators. i.e.::
0077
0078 Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
0079 |
0080 +-> [Consumer B]
0081
0082 This gives us two regulators and two power domains:
0083
0084 - Domain 1: Regulator-2, Consumer B.
0085 - Domain 2: Consumer A.
0086
0087 and a "supplies" relationship:
0088
0089 Domain-1 --> Domain-2
0090
0091
0092 - Constraints
0093 - Constraints are used to define power levels for performance
0094 and hardware protection. Constraints exist at three levels:
0095
0096 Regulator Level: This is defined by the regulator hardware
0097 operating parameters and is specified in the regulator
0098 datasheet. i.e.
0099
0100 - voltage output is in the range 800mV -> 3500mV.
0101 - regulator current output limit is 20mA @ 5V but is
0102 10mA @ 10V.
0103
0104 Power Domain Level: This is defined in software by kernel
0105 level board initialisation code. It is used to constrain a
0106 power domain to a particular power range. i.e.
0107
0108 - Domain-1 voltage is 3300mV
0109 - Domain-2 voltage is 1400mV -> 1600mV
0110 - Domain-3 current limit is 0mA -> 20mA.
0111
0112 Consumer Level: This is defined by consumer drivers
0113 dynamically setting voltage or current limit levels.
0114
0115 e.g. a consumer backlight driver asks for a current increase
0116 from 5mA to 10mA to increase LCD illumination. This passes
0117 to through the levels as follows :-
0118
0119 Consumer: need to increase LCD brightness. Lookup and
0120 request next current mA value in brightness table (the
0121 consumer driver could be used on several different
0122 personalities based upon the same reference device).
0123
0124 Power Domain: is the new current limit within the domain
0125 operating limits for this domain and system state (e.g.
0126 battery power, USB power)
0127
0128 Regulator Domains: is the new current limit within the
0129 regulator operating parameters for input/output voltage.
0130
0131 If the regulator request passes all the constraint tests
0132 then the new regulator value is applied.
0133
0134
0135 Design
0136 ======
0137
0138 The framework is designed and targeted at SoC based devices but may also be
0139 relevant to non SoC devices and is split into the following four interfaces:-
0140
0141
0142 1. Consumer driver interface.
0143
0144 This uses a similar API to the kernel clock interface in that consumer
0145 drivers can get and put a regulator (like they can with clocks atm) and
0146 get/set voltage, current limit, mode, enable and disable. This should
0147 allow consumers complete control over their supply voltage and current
0148 limit. This also compiles out if not in use so drivers can be reused in
0149 systems with no regulator based power control.
0150
0151 See Documentation/power/regulator/consumer.rst
0152
0153 2. Regulator driver interface.
0154
0155 This allows regulator drivers to register their regulators and provide
0156 operations to the core. It also has a notifier call chain for propagating
0157 regulator events to clients.
0158
0159 See Documentation/power/regulator/regulator.rst
0160
0161 3. Machine interface.
0162
0163 This interface is for machine specific code and allows the creation of
0164 voltage/current domains (with constraints) for each regulator. It can
0165 provide regulator constraints that will prevent device damage through
0166 overvoltage or overcurrent caused by buggy client drivers. It also
0167 allows the creation of a regulator tree whereby some regulators are
0168 supplied by others (similar to a clock tree).
0169
0170 See Documentation/power/regulator/machine.rst
0171
0172 4. Userspace ABI.
0173
0174 The framework also exports a lot of useful voltage/current/opmode data to
0175 userspace via sysfs. This could be used to help monitor device power
0176 consumption and status.
0177
0178 See Documentation/ABI/testing/sysfs-class-regulator
