0001 .. Copyright 2007-2008 Wolfson Microelectronics
0002
0003 .. This documentation is free software; you can redistribute
0004 .. it and/or modify it under the terms of the GNU General Public
0005 .. License version 2 as published by the Free Software Foundation.
0006
0007 =================================
0008 Voltage and current regulator API
0009 =================================
0010
0011 :Author: Liam Girdwood
0012 :Author: Mark Brown
0013
0014 Introduction
0015 ============
0016
0017 This framework is designed to provide a standard kernel interface to
0018 control voltage and current regulators.
0019
0020 The intention is to allow systems to dynamically control regulator power
0021 output in order to save power and prolong battery life. This applies to
0022 both voltage regulators (where voltage output is controllable) and
0023 current sinks (where current limit is controllable).
0024
0025 Note that additional (and currently more complete) documentation is
0026 available in the Linux kernel source under
0027 ``Documentation/power/regulator``.
0028
0029 Glossary
0030 --------
0031
0032 The regulator API uses a number of terms which may not be familiar:
0033
0034 Regulator
0035
0036 Electronic device that supplies power to other devices. Most regulators
0037 can enable and disable their output and some can also control their
0038 output voltage or current.
0039
0040 Consumer
0041
0042 Electronic device which consumes power provided by a regulator. These
0043 may either be static, requiring only a fixed supply, or dynamic,
0044 requiring active management of the regulator at runtime.
0045
0046 Power Domain
0047
0048 The electronic circuit supplied by a given regulator, including the
0049 regulator and all consumer devices. The configuration of the regulator
0050 is shared between all the components in the circuit.
0051
0052 Power Management Integrated Circuit (PMIC)
0053
0054 An IC which contains numerous regulators and often also other
0055 subsystems. In an embedded system the primary PMIC is often equivalent
0056 to a combination of the PSU and southbridge in a desktop system.
0057
0058 Consumer driver interface
0059 =========================
0060
0061 This offers a similar API to the kernel clock framework. Consumer
0062 drivers use `get <#API-regulator-get>`__ and
0063 `put <#API-regulator-put>`__ operations to acquire and release
0064 regulators. Functions are provided to `enable <#API-regulator-enable>`__
0065 and `disable <#API-regulator-disable>`__ the regulator and to get and
0066 set the runtime parameters of the regulator.
0067
0068 When requesting regulators consumers use symbolic names for their
0069 supplies, such as "Vcc", which are mapped into actual regulator devices
0070 by the machine interface.
0071
0072 A stub version of this API is provided when the regulator framework is
0073 not in use in order to minimise the need to use ifdefs.
0074
0075 Enabling and disabling
0076 ----------------------
0077
0078 The regulator API provides reference counted enabling and disabling of
0079 regulators. Consumer devices use the :c:func:`regulator_enable()` and
0080 :c:func:`regulator_disable()` functions to enable and disable
0081 regulators. Calls to the two functions must be balanced.
0082
0083 Note that since multiple consumers may be using a regulator and machine
0084 constraints may not allow the regulator to be disabled there is no
0085 guarantee that calling :c:func:`regulator_disable()` will actually
0086 cause the supply provided by the regulator to be disabled. Consumer
0087 drivers should assume that the regulator may be enabled at all times.
0088
0089 Configuration
0090 -------------
0091
0092 Some consumer devices may need to be able to dynamically configure their
0093 supplies. For example, MMC drivers may need to select the correct
0094 operating voltage for their cards. This may be done while the regulator
0095 is enabled or disabled.
0096
0097 The :c:func:`regulator_set_voltage()` and
0098 :c:func:`regulator_set_current_limit()` functions provide the primary
0099 interface for this. Both take ranges of voltages and currents, supporting
0100 drivers that do not require a specific value (eg, CPU frequency scaling
0101 normally permits the CPU to use a wider range of supply voltages at lower
0102 frequencies but does not require that the supply voltage be lowered). Where
0103 an exact value is required both minimum and maximum values should be
0104 identical.
0105
0106 Callbacks
0107 ---------
0108
0109 Callbacks may also be registered for events such as regulation failures.
0110
0111 Regulator driver interface
0112 ==========================
0113
0114 Drivers for regulator chips register the regulators with the regulator
0115 core, providing operations structures to the core. A notifier interface
0116 allows error conditions to be reported to the core.
0117
0118 Registration should be triggered by explicit setup done by the platform,
0119 supplying a struct regulator_init_data for the regulator
0120 containing constraint and supply information.
0121
0122 Machine interface
0123 =================
0124
0125 This interface provides a way to define how regulators are connected to
0126 consumers on a given system and what the valid operating parameters are
0127 for the system.
0128
0129 Supplies
0130 --------
0131
0132 Regulator supplies are specified using struct
0133 :c:type:`regulator_consumer_supply`. This is done at driver registration
0134 time as part of the machine constraints.
0135
0136 Constraints
0137 -----------
0138
0139 As well as defining the connections the machine interface also provides
0140 constraints defining the operations that clients are allowed to perform
0141 and the parameters that may be set. This is required since generally
0142 regulator devices will offer more flexibility than it is safe to use on
0143 a given system, for example supporting higher supply voltages than the
0144 consumers are rated for.
0145
0146 This is done at driver registration time` by providing a
0147 struct regulation_constraints.
0148
0149 The constraints may also specify an initial configuration for the
0150 regulator in the constraints, which is particularly useful for use with
0151 static consumers.
0152
0153 API reference
0154 =============
0155
0156 Due to limitations of the kernel documentation framework and the
0157 existing layout of the source code the entire regulator API is
0158 documented here.
0159
0160 .. kernel-doc:: include/linux/regulator/consumer.h
0161 :internal:
0162
0163 .. kernel-doc:: include/linux/regulator/machine.h
0164 :internal:
0165
0166 .. kernel-doc:: include/linux/regulator/driver.h
0167 :internal:
0168
0169 .. kernel-doc:: drivers/regulator/core.c
0170 :export:
