171 lines · plain
1.. Copyright 2007-2008 Wolfson Microelectronics2 3.. This documentation is free software; you can redistribute4.. it and/or modify it under the terms of the GNU General Public5.. License version 2 as published by the Free Software Foundation.6 7=================================8Voltage and current regulator API9=================================10 11:Author: Liam Girdwood12:Author: Mark Brown13 14Introduction15============16 17This framework is designed to provide a standard kernel interface to18control voltage and current regulators.19 20The intention is to allow systems to dynamically control regulator power21output in order to save power and prolong battery life. This applies to22both voltage regulators (where voltage output is controllable) and23current sinks (where current limit is controllable).24 25Note that additional (and currently more complete) documentation is26available in the Linux kernel source under27``Documentation/power/regulator``.28 29Glossary30--------31 32The regulator API uses a number of terms which may not be familiar:33 34Regulator35 36 Electronic device that supplies power to other devices. Most regulators37 can enable and disable their output and some can also control their38 output voltage or current.39 40Consumer41 42 Electronic device which consumes power provided by a regulator. These43 may either be static, requiring only a fixed supply, or dynamic,44 requiring active management of the regulator at runtime.45 46Power Domain47 48 The electronic circuit supplied by a given regulator, including the49 regulator and all consumer devices. The configuration of the regulator50 is shared between all the components in the circuit.51 52Power Management Integrated Circuit (PMIC)53 54 An IC which contains numerous regulators and often also other55 subsystems. In an embedded system the primary PMIC is often equivalent56 to a combination of the PSU and southbridge in a desktop system.57 58Consumer driver interface59=========================60 61This offers a similar API to the kernel clock framework. Consumer62drivers use `get <#API-regulator-get>`__ and63`put <#API-regulator-put>`__ operations to acquire and release64regulators. Functions are provided to `enable <#API-regulator-enable>`__65and `disable <#API-regulator-disable>`__ the regulator and to get and66set the runtime parameters of the regulator.67 68When requesting regulators consumers use symbolic names for their69supplies, such as "Vcc", which are mapped into actual regulator devices70by the machine interface.71 72A stub version of this API is provided when the regulator framework is73not in use in order to minimise the need to use ifdefs.74 75Enabling and disabling76----------------------77 78The regulator API provides reference counted enabling and disabling of79regulators. Consumer devices use the :c:func:`regulator_enable()` and80:c:func:`regulator_disable()` functions to enable and disable81regulators. Calls to the two functions must be balanced.82 83Note that since multiple consumers may be using a regulator and machine84constraints may not allow the regulator to be disabled there is no85guarantee that calling :c:func:`regulator_disable()` will actually86cause the supply provided by the regulator to be disabled. Consumer87drivers should assume that the regulator may be enabled at all times.88 89Configuration90-------------91 92Some consumer devices may need to be able to dynamically configure their93supplies. For example, MMC drivers may need to select the correct94operating voltage for their cards. This may be done while the regulator95is enabled or disabled.96 97The :c:func:`regulator_set_voltage()` and98:c:func:`regulator_set_current_limit()` functions provide the primary99interface for this. Both take ranges of voltages and currents, supporting100drivers that do not require a specific value (eg, CPU frequency scaling101normally permits the CPU to use a wider range of supply voltages at lower102frequencies but does not require that the supply voltage be lowered). Where103an exact value is required both minimum and maximum values should be104identical.105 106Callbacks107---------108 109Callbacks may also be registered for events such as regulation failures.110 111Regulator driver interface112==========================113 114Drivers for regulator chips register the regulators with the regulator115core, providing operations structures to the core. A notifier interface116allows error conditions to be reported to the core.117 118Registration should be triggered by explicit setup done by the platform,119supplying a struct regulator_init_data for the regulator120containing constraint and supply information.121 122Machine interface123=================124 125This interface provides a way to define how regulators are connected to126consumers on a given system and what the valid operating parameters are127for the system.128 129Supplies130--------131 132Regulator supplies are specified using struct133:c:type:`regulator_consumer_supply`. This is done at driver registration134time as part of the machine constraints.135 136Constraints137-----------138 139As well as defining the connections the machine interface also provides140constraints defining the operations that clients are allowed to perform141and the parameters that may be set. This is required since generally142regulator devices will offer more flexibility than it is safe to use on143a given system, for example supporting higher supply voltages than the144consumers are rated for.145 146This is done at driver registration time` by providing a147struct regulation_constraints.148 149The constraints may also specify an initial configuration for the150regulator in the constraints, which is particularly useful for use with151static consumers.152 153API reference154=============155 156Due to limitations of the kernel documentation framework and the157existing layout of the source code the entire regulator API is158documented here.159 160.. kernel-doc:: include/linux/regulator/consumer.h161 :internal:162 163.. kernel-doc:: include/linux/regulator/machine.h164 :internal:165 166.. kernel-doc:: include/linux/regulator/driver.h167 :internal:168 169.. kernel-doc:: drivers/regulator/core.c170 :export:171