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