Commit | Line | Data |
---|---|---|
028f2533 JC |
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: |