.. 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 tocontrol voltage and current regulators. The intention is to allow systems to dynamically control regulator poweroutput in order to save power and prolong battery life. This applies toboth voltage regulators (where voltage output is controllable) andcurrent sinks (where current limit is controllable). Note that additional (and currently more complete) documentation isavailable 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. Consumerdrivers use `get <#API-regulator-get>`__ and`put <#API-regulator-put>`__ operations to acquire and releaseregulators. Functions are provided to `enable <#API-regulator-enable>`__and `disable <#API-regulator-disable>`__ the regulator and to get andset the runtime parameters of the regulator. When requesting regulators consumers use symbolic names for theirsupplies, such as "Vcc", which are mapped into actual regulator devicesby the machine interface. A stub version of this API is provided when the regulator framework isnot in use in order to minimise the need to use ifdefs. Enabling and disabling---------------------- The regulator API provides reference counted enabling and disabling ofregulators. Consumer devices use the :c:func:`regulator_enable()` and:c:func:`regulator_disable()` functions to enable and disableregulators. Calls to the two functions must be balanced. Note that since multiple consumers may be using a regulator and machineconstraints may not allow the regulator to be disabled there is noguarantee that calling :c:func:`regulator_disable()` will actuallycause the supply provided by the regulator to be disabled. Consumerdrivers should assume that the regulator may be enabled at all times. Configuration------------- Some consumer devices may need to be able to dynamically configure theirsupplies. For example, MMC drivers may need to select the correctoperating voltage for their cards. This may be done while the regulatoris enabled or disabled. The :c:func:`regulator_set_voltage()` and:c:func:`regulator_set_current_limit()` functions provide the primaryinterface for this. Both take ranges of voltages and currents, supportingdrivers that do not require a specific value (eg, CPU frequency scalingnormally permits the CPU to use a wider range of supply voltages at lowerfrequencies but does not require that the supply voltage be lowered). Wherean exact value is required both minimum and maximum values should beidentical. Callbacks--------- Callbacks may also be registered for events such as regulation failures. Regulator driver interface========================== Drivers for regulator chips register the regulators with the regulatorcore, providing operations structures to the core. A notifier interfaceallows error conditions to be reported to the core. Registration should be triggered by explicit setup done by the platform,supplying a struct regulator_init_data for the regulatorcontaining constraint and supply information. Machine interface================= This interface provides a way to define how regulators are connected toconsumers on a given system and what the valid operating parameters arefor the system. Supplies-------- Regulator supplies are specified using struct:c:type:`regulator_consumer_supply`. This is done at driver registrationtime as part of the machine constraints. Constraints----------- As well as defining the connections the machine interface also providesconstraints defining the operations that clients are allowed to performand the parameters that may be set. This is required since generallyregulator devices will offer more flexibility than it is safe to use ona given system, for example supporting higher supply voltages than theconsumers are rated for. This is done at driver registration time` by providing astruct regulation_constraints. The constraints may also specify an initial configuration for theregulator in the constraints, which is particularly useful for use withstatic consumers. API reference============= Due to limitations of the kernel documentation framework and theexisting layout of the source code the entire regulator API isdocumented 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: