docs: Convert the regulator docbook to RST
A fairly straightforward conversion to RST; the document is then added to the driver-api manual. Of course, this document has seen no substantive changes since 2008, so chances are it needs work in other areas as well. Cc: Mark Brown <broonie@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Jonathan Corbet
parent
8a8a602fdb
commit
028f25332c
|
|
@ -1,304 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
||||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
|
||||||
|
|
||||||
<book id="regulator-api">
|
|
||||||
<bookinfo>
|
|
||||||
<title>Voltage and current regulator API</title>
|
|
||||||
|
|
||||||
<authorgroup>
|
|
||||||
<author>
|
|
||||||
<firstname>Liam</firstname>
|
|
||||||
<surname>Girdwood</surname>
|
|
||||||
<affiliation>
|
|
||||||
<address>
|
|
||||||
<email>lrg@slimlogic.co.uk</email>
|
|
||||||
</address>
|
|
||||||
</affiliation>
|
|
||||||
</author>
|
|
||||||
<author>
|
|
||||||
<firstname>Mark</firstname>
|
|
||||||
<surname>Brown</surname>
|
|
||||||
<affiliation>
|
|
||||||
<orgname>Wolfson Microelectronics</orgname>
|
|
||||||
<address>
|
|
||||||
<email>broonie@opensource.wolfsonmicro.com</email>
|
|
||||||
</address>
|
|
||||||
</affiliation>
|
|
||||||
</author>
|
|
||||||
</authorgroup>
|
|
||||||
|
|
||||||
<copyright>
|
|
||||||
<year>2007-2008</year>
|
|
||||||
<holder>Wolfson Microelectronics</holder>
|
|
||||||
</copyright>
|
|
||||||
<copyright>
|
|
||||||
<year>2008</year>
|
|
||||||
<holder>Liam Girdwood</holder>
|
|
||||||
</copyright>
|
|
||||||
|
|
||||||
<legalnotice>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
For more details see the file COPYING in the source
|
|
||||||
distribution of Linux.
|
|
||||||
</para>
|
|
||||||
</legalnotice>
|
|
||||||
</bookinfo>
|
|
||||||
|
|
||||||
<toc></toc>
|
|
||||||
|
|
||||||
<chapter id="intro">
|
|
||||||
<title>Introduction</title>
|
|
||||||
<para>
|
|
||||||
This framework is designed to provide a standard kernel
|
|
||||||
interface to control voltage and current regulators.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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).
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Note that additional (and currently more complete) documentation
|
|
||||||
is available in the Linux kernel source under
|
|
||||||
<filename>Documentation/power/regulator</filename>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<sect1 id="glossary">
|
|
||||||
<title>Glossary</title>
|
|
||||||
<para>
|
|
||||||
The regulator API uses a number of terms which may not be
|
|
||||||
familiar:
|
|
||||||
</para>
|
|
||||||
<glossary>
|
|
||||||
|
|
||||||
<glossentry>
|
|
||||||
<glossterm>Regulator</glossterm>
|
|
||||||
<glossdef>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
</glossdef>
|
|
||||||
</glossentry>
|
|
||||||
|
|
||||||
<glossentry>
|
|
||||||
<glossterm>Consumer</glossterm>
|
|
||||||
<glossdef>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
</glossdef>
|
|
||||||
</glossentry>
|
|
||||||
|
|
||||||
<glossentry>
|
|
||||||
<glossterm>Power Domain</glossterm>
|
|
||||||
<glossdef>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
</glossdef>
|
|
||||||
</glossentry>
|
|
||||||
|
|
||||||
<glossentry>
|
|
||||||
<glossterm>Power Management Integrated Circuit</glossterm>
|
|
||||||
<acronym>PMIC</acronym>
|
|
||||||
<glossdef>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
</glossdef>
|
|
||||||
</glossentry>
|
|
||||||
</glossary>
|
|
||||||
</sect1>
|
|
||||||
</chapter>
|
|
||||||
|
|
||||||
<chapter id="consumer">
|
|
||||||
<title>Consumer driver interface</title>
|
|
||||||
<para>
|
|
||||||
This offers a similar API to the kernel clock framework.
|
|
||||||
Consumer drivers use <link
|
|
||||||
linkend='API-regulator-get'>get</link> and <link
|
|
||||||
linkend='API-regulator-put'>put</link> operations to acquire and
|
|
||||||
release regulators. Functions are
|
|
||||||
provided to <link linkend='API-regulator-enable'>enable</link>
|
|
||||||
and <link linkend='API-regulator-disable'>disable</link> the
|
|
||||||
regulator and to get and set the runtime parameters of the
|
|
||||||
regulator.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
When requesting regulators consumers use symbolic names for their
|
|
||||||
supplies, such as "Vcc", which are mapped into actual regulator
|
|
||||||
devices by the machine interface.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<sect1 id="consumer-enable">
|
|
||||||
<title>Enabling and disabling</title>
|
|
||||||
<para>
|
|
||||||
The regulator API provides reference counted enabling and
|
|
||||||
disabling of regulators. Consumer devices use the <function><link
|
|
||||||
linkend='API-regulator-enable'>regulator_enable</link></function>
|
|
||||||
and <function><link
|
|
||||||
linkend='API-regulator-disable'>regulator_disable</link>
|
|
||||||
</function> functions to enable and disable regulators. Calls
|
|
||||||
to the two functions must be balanced.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
<function>regulator_disable</function> 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.
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="consumer-config">
|
|
||||||
<title>Configuration</title>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The <function><link
|
|
||||||
linkend='API-regulator-set-voltage'>regulator_set_voltage</link>
|
|
||||||
</function> and <function><link
|
|
||||||
linkend='API-regulator-set-current-limit'
|
|
||||||
>regulator_set_current_limit</link>
|
|
||||||
</function> 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.
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="consumer-callback">
|
|
||||||
<title>Callbacks</title>
|
|
||||||
<para>
|
|
||||||
Callbacks may also be <link
|
|
||||||
linkend='API-regulator-register-notifier'>registered</link>
|
|
||||||
for events such as regulation failures.
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
</chapter>
|
|
||||||
|
|
||||||
<chapter id="driver">
|
|
||||||
<title>Regulator driver interface</title>
|
|
||||||
<para>
|
|
||||||
Drivers for regulator chips <link
|
|
||||||
linkend='API-regulator-register'>register</link> the regulators
|
|
||||||
with the regulator core, providing operations structures to the
|
|
||||||
core. A <link
|
|
||||||
linkend='API-regulator-notifier-call-chain'>notifier</link> interface
|
|
||||||
allows error conditions to be reported to the core.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Registration should be triggered by explicit setup done by the
|
|
||||||
platform, supplying a <link
|
|
||||||
linkend='API-struct-regulator-init-data'>struct
|
|
||||||
regulator_init_data</link> for the regulator containing
|
|
||||||
<link linkend='machine-constraint'>constraint</link> and
|
|
||||||
<link linkend='machine-supply'>supply</link> information.
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
||||||
|
|
||||||
<chapter id="machine">
|
|
||||||
<title>Machine interface</title>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<sect1 id="machine-supply">
|
|
||||||
<title>Supplies</title>
|
|
||||||
<para>
|
|
||||||
Regulator supplies are specified using <link
|
|
||||||
linkend='API-struct-regulator-consumer-supply'>struct
|
|
||||||
regulator_consumer_supply</link>. This is done at
|
|
||||||
<link linkend='driver'>driver registration
|
|
||||||
time</link> as part of the machine constraints.
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="machine-constraint">
|
|
||||||
<title>Constraints</title>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
This is done at <link linkend='driver'>driver
|
|
||||||
registration time</link> by providing a <link
|
|
||||||
linkend='API-struct-regulation-constraints'>struct
|
|
||||||
regulation_constraints</link>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The constraints may also specify an initial configuration for the
|
|
||||||
regulator in the constraints, which is particularly useful for
|
|
||||||
use with static consumers.
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
</chapter>
|
|
||||||
|
|
||||||
<chapter id="api">
|
|
||||||
<title>API reference</title>
|
|
||||||
<para>
|
|
||||||
Due to limitations of the kernel documentation framework and the
|
|
||||||
existing layout of the source code the entire regulator API is
|
|
||||||
documented here.
|
|
||||||
</para>
|
|
||||||
!Iinclude/linux/regulator/consumer.h
|
|
||||||
!Iinclude/linux/regulator/machine.h
|
|
||||||
!Iinclude/linux/regulator/driver.h
|
|
||||||
!Edrivers/regulator/core.c
|
|
||||||
</chapter>
|
|
||||||
</book>
|
|
||||||
|
|
@ -22,6 +22,7 @@ available subsections can be seen below.
|
||||||
message-based
|
message-based
|
||||||
sound
|
sound
|
||||||
frame-buffer
|
frame-buffer
|
||||||
|
regulator
|
||||||
iio/index
|
iio/index
|
||||||
input
|
input
|
||||||
usb
|
usb
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,170 @@
|
||||||
|
.. Copyright 2007-2008 Wolfson Microelectronics
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
=================================
|
||||||
|
Voltage and current regulator API
|
||||||
|
=================================
|
||||||
|
|
||||||
|
:Author: Liam Girdwood
|
||||||
|
:Author: Mark Brown
|
||||||
|
|
||||||
|
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 <#API-regulator-get>`__ and
|
||||||
|
`put <#API-regulator-put>`__ operations to acquire and release
|
||||||
|
regulators. Functions are provided to `enable <#API-regulator-enable>`__
|
||||||
|
and `disable <#API-regulator-disable>`__ the regulator 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 :c:func:`regulator_enable()` and
|
||||||
|
:c:func:`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 :c:func:`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 :c:func:`regulator_set_voltage()` and
|
||||||
|
:c:func:`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 :c:type:`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
|
||||||
|
:c:type:`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 :c:type:`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.
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/regulator/consumer.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/regulator/machine.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/regulator/driver.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/regulator/core.c
|
||||||
|
:export:
|
||||||
Loading…
Reference in New Issue