From 849369d6c66d3054688672f97d31fceb8e8230fb Mon Sep 17 00:00:00 2001 From: root Date: Fri, 25 Dec 2015 04:40:36 +0000 Subject: initial_commit --- Documentation/DocBook/regulator.tmpl | 304 +++++++++++++++++++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 Documentation/DocBook/regulator.tmpl (limited to 'Documentation/DocBook/regulator.tmpl') diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl new file mode 100644 index 00000000..346e552f --- /dev/null +++ b/Documentation/DocBook/regulator.tmpl @@ -0,0 +1,304 @@ + + + + + + Voltage and current regulator API + + + + Liam + Girdwood + +
+ lrg@slimlogic.co.uk +
+ + + + Mark + Brown + + Wolfson Microelectronics +
+ broonie@opensource.wolfsonmicro.com +
+ + + + + + 2007-2008 + Wolfson Microelectronics + + + 2008 + Liam Girdwood + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + + + + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + + + + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + + + + For more details see the file COPYING in the source + distribution of Linux. + + + + + + + + Introduction + + This framework is designed to provide a standard kernel + interface to control voltage and current regulators. + + + The intention is to allow systems to dynamically control + regulator power output in order to save power and prolong + battery life. This applies to both voltage regulators (where + voltage output is controllable) and current sinks (where current + limit is controllable). + + + Note that additional (and currently more complete) documentation + is available in the Linux kernel source under + Documentation/power/regulator. + + + + Glossary + + The regulator API uses a number of terms which may not be + familiar: + + + + + Regulator + + + Electronic device that supplies power to other devices. Most + regulators can enable and disable their output and some can also + control their output voltage or current. + + + + + + Consumer + + + Electronic device which consumes power provided by a regulator. + These may either be static, requiring only a fixed supply, or + dynamic, requiring active management of the regulator at + runtime. + + + + + + Power Domain + + + The electronic circuit supplied by a given regulator, including + the regulator and all consumer devices. The configuration of + the regulator is shared between all the components in the + circuit. + + + + + + Power Management Integrated Circuit + PMIC + + + An IC which contains numerous regulators and often also other + subsystems. In an embedded system the primary PMIC is often + equivalent to a combination of the PSU and southbridge in a + desktop system. + + + + + + + + + Consumer driver interface + + This offers a similar API to the kernel clock framework. + Consumer drivers use get and put operations to acquire and + release regulators. Functions are + provided to enable + and disable the + reguator and to get and set the runtime parameters of the + regulator. + + + When requesting regulators consumers use symbolic names for their + supplies, such as "Vcc", which are mapped into actual regulator + devices by the machine interface. + + + A stub version of this API is provided when the regulator + framework is not in use in order to minimise the need to use + ifdefs. + + + + Enabling and disabling + + The regulator API provides reference counted enabling and + disabling of regulators. Consumer devices use the regulator_enable + and regulator_disable + functions to enable and disable regulators. Calls + to the two functions must be balanced. + + + Note that since multiple consumers may be using a regulator and + machine constraints may not allow the regulator to be disabled + there is no guarantee that calling + regulator_disable will actually cause the + supply provided by the regulator to be disabled. Consumer + drivers should assume that the regulator may be enabled at all + times. + + + + + Configuration + + Some consumer devices may need to be able to dynamically + configure their supplies. For example, MMC drivers may need to + select the correct operating voltage for their cards. This may + be done while the regulator is enabled or disabled. + + + The regulator_set_voltage + and regulator_set_current_limit + functions provide the primary interface for this. + Both take ranges of voltages and currents, supporting drivers + that do not require a specific value (eg, CPU frequency scaling + normally permits the CPU to use a wider range of supply + voltages at lower frequencies but does not require that the + supply voltage be lowered). Where an exact value is required + both minimum and maximum values should be identical. + + + + + Callbacks + + Callbacks may also be registered + for events such as regulation failures. + + + + + + Regulator driver interface + + Drivers for regulator chips register the regulators + with the regulator core, providing operations structures to the + core. A notifier interface + allows error conditions to be reported to the core. + + + Registration should be triggered by explicit setup done by the + platform, supplying a struct + regulator_init_data for the regulator containing + constraint and + supply information. + + + + + Machine interface + + This interface provides a way to define how regulators are + connected to consumers on a given system and what the valid + operating parameters are for the system. + + + + Supplies + + Regulator supplies are specified using struct + regulator_consumer_supply. This is done at + driver registration + time as part of the machine constraints. + + + + + Constraints + + As well as defining the connections the machine interface + also provides constraints defining the operations that + clients are allowed to perform and the parameters that may be + set. This is required since generally regulator devices will + offer more flexibility than it is safe to use on a given + system, for example supporting higher supply voltages than the + consumers are rated for. + + + This is done at driver + registration time by providing a struct + regulation_constraints. + + + The constraints may also specify an initial configuration for the + regulator in the constraints, which is particularly useful for + use with static consumers. + + + + + + API reference + + Due to limitations of the kernel documentation framework and the + existing layout of the source code the entire regulator API is + documented here. + +!Iinclude/linux/regulator/consumer.h +!Iinclude/linux/regulator/machine.h +!Iinclude/linux/regulator/driver.h +!Edrivers/regulator/core.c + + -- cgit v1.2.3