^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. Copyright 2007-2008 Wolfson Microelectronics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) .. This documentation is free software; you can redistribute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. it and/or modify it under the terms of the GNU General Public
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) .. License version 2 as published by the Free Software Foundation.
^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) Voltage and current regulator API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) =================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) :Author: Liam Girdwood
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) :Author: Mark Brown
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) This framework is designed to provide a standard kernel interface to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) control voltage and current regulators.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) The intention is to allow systems to dynamically control regulator power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) output in order to save power and prolong battery life. This applies to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) both voltage regulators (where voltage output is controllable) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) current sinks (where current limit is controllable).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) Note that additional (and currently more complete) documentation is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) available in the Linux kernel source under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) ``Documentation/power/regulator``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Glossary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) The regulator API uses a number of terms which may not be familiar:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Regulator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Electronic device that supplies power to other devices. Most regulators
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) can enable and disable their output and some can also control their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) output voltage or current.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) Consumer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) Electronic device which consumes power provided by a regulator. These
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) may either be static, requiring only a fixed supply, or dynamic,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) requiring active management of the regulator at runtime.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Power Domain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) The electronic circuit supplied by a given regulator, including the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) regulator and all consumer devices. The configuration of the regulator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) is shared between all the components in the circuit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Power Management Integrated Circuit (PMIC)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) An IC which contains numerous regulators and often also other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) subsystems. In an embedded system the primary PMIC is often equivalent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) to a combination of the PSU and southbridge in a desktop system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Consumer driver interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) This offers a similar API to the kernel clock framework. Consumer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) drivers use `get <#API-regulator-get>`__ and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) `put <#API-regulator-put>`__ operations to acquire and release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) regulators. Functions are provided to `enable <#API-regulator-enable>`__
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) and `disable <#API-regulator-disable>`__ the regulator and to get and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) set the runtime parameters of the regulator.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) When requesting regulators consumers use symbolic names for their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) supplies, such as "Vcc", which are mapped into actual regulator devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) by the machine interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) A stub version of this API is provided when the regulator framework is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) not in use in order to minimise the need to use ifdefs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) Enabling and disabling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) The regulator API provides reference counted enabling and disabling of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) regulators. Consumer devices use the :c:func:`regulator_enable()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) :c:func:`regulator_disable()` functions to enable and disable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) regulators. Calls to the two functions must be balanced.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) Note that since multiple consumers may be using a regulator and machine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) constraints may not allow the regulator to be disabled there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) guarantee that calling :c:func:`regulator_disable()` will actually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) cause the supply provided by the regulator to be disabled. Consumer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) drivers should assume that the regulator may be enabled at all times.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) Configuration
^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) Some consumer devices may need to be able to dynamically configure their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) supplies. For example, MMC drivers may need to select the correct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) operating voltage for their cards. This may be done while the regulator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) is enabled or disabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) The :c:func:`regulator_set_voltage()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) :c:func:`regulator_set_current_limit()` functions provide the primary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) interface for this. Both take ranges of voltages and currents, supporting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) drivers that do not require a specific value (eg, CPU frequency scaling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) normally permits the CPU to use a wider range of supply voltages at lower
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) frequencies but does not require that the supply voltage be lowered). Where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) an exact value is required both minimum and maximum values should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) identical.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) Callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Callbacks may also be registered for events such as regulation failures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) Regulator driver interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Drivers for regulator chips register the regulators with the regulator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) core, providing operations structures to the core. A notifier interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) allows error conditions to be reported to the core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) Registration should be triggered by explicit setup done by the platform,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) supplying a struct regulator_init_data for the regulator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) containing constraint and supply information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) Machine interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) This interface provides a way to define how regulators are connected to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) consumers on a given system and what the valid operating parameters are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) for the system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) Supplies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) Regulator supplies are specified using struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) :c:type:`regulator_consumer_supply`. This is done at driver registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) time as part of the machine constraints.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) Constraints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) As well as defining the connections the machine interface also provides
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) constraints defining the operations that clients are allowed to perform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) and the parameters that may be set. This is required since generally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) regulator devices will offer more flexibility than it is safe to use on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) a given system, for example supporting higher supply voltages than the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) consumers are rated for.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) This is done at driver registration time` by providing a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) struct regulation_constraints.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) The constraints may also specify an initial configuration for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) regulator in the constraints, which is particularly useful for use with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) static consumers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) API reference
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) Due to limitations of the kernel documentation framework and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) existing layout of the source code the entire regulator API is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) documented here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) .. kernel-doc:: include/linux/regulator/consumer.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) .. kernel-doc:: include/linux/regulator/machine.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) .. kernel-doc:: include/linux/regulator/driver.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) .. kernel-doc:: drivers/regulator/core.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) :export:
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags