Documentation/driver-api/regulator.rst

   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: