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