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 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 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:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.