regulator.rst 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170
  1. .. Copyright 2007-2008 Wolfson Microelectronics
  2. .. This documentation is free software; you can redistribute
  3. .. it and/or modify it under the terms of the GNU General Public
  4. .. License version 2 as published by the Free Software Foundation.
  5. =================================
  6. Voltage and current regulator API
  7. =================================
  8. :Author: Liam Girdwood
  9. :Author: Mark Brown
  10. Introduction
  11. ============
  12. This framework is designed to provide a standard kernel interface to
  13. control voltage and current regulators.
  14. The intention is to allow systems to dynamically control regulator power
  15. output in order to save power and prolong battery life. This applies to
  16. both voltage regulators (where voltage output is controllable) and
  17. current sinks (where current limit is controllable).
  18. Note that additional (and currently more complete) documentation is
  19. available in the Linux kernel source under
  20. ``Documentation/power/regulator``.
  21. Glossary
  22. --------
  23. The regulator API uses a number of terms which may not be familiar:
  24. Regulator
  25. Electronic device that supplies power to other devices. Most regulators
  26. can enable and disable their output and some can also control their
  27. output voltage or current.
  28. Consumer
  29. Electronic device which consumes power provided by a regulator. These
  30. may either be static, requiring only a fixed supply, or dynamic,
  31. requiring active management of the regulator at runtime.
  32. Power Domain
  33. The electronic circuit supplied by a given regulator, including the
  34. regulator and all consumer devices. The configuration of the regulator
  35. is shared between all the components in the circuit.
  36. Power Management Integrated Circuit (PMIC)
  37. An IC which contains numerous regulators and often also other
  38. subsystems. In an embedded system the primary PMIC is often equivalent
  39. to a combination of the PSU and southbridge in a desktop system.
  40. Consumer driver interface
  41. =========================
  42. This offers a similar API to the kernel clock framework. Consumer
  43. drivers use `get <#API-regulator-get>`__ and
  44. `put <#API-regulator-put>`__ operations to acquire and release
  45. regulators. Functions are provided to `enable <#API-regulator-enable>`__
  46. and `disable <#API-regulator-disable>`__ the regulator and to get and
  47. set the runtime parameters of the regulator.
  48. When requesting regulators consumers use symbolic names for their
  49. supplies, such as "Vcc", which are mapped into actual regulator devices
  50. by the machine interface.
  51. A stub version of this API is provided when the regulator framework is
  52. not in use in order to minimise the need to use ifdefs.
  53. Enabling and disabling
  54. ----------------------
  55. The regulator API provides reference counted enabling and disabling of
  56. regulators. Consumer devices use the :c:func:`regulator_enable()` and
  57. :c:func:`regulator_disable()` functions to enable and disable
  58. regulators. Calls to the two functions must be balanced.
  59. Note that since multiple consumers may be using a regulator and machine
  60. constraints may not allow the regulator to be disabled there is no
  61. guarantee that calling :c:func:`regulator_disable()` will actually
  62. cause the supply provided by the regulator to be disabled. Consumer
  63. drivers should assume that the regulator may be enabled at all times.
  64. Configuration
  65. -------------
  66. Some consumer devices may need to be able to dynamically configure their
  67. supplies. For example, MMC drivers may need to select the correct
  68. operating voltage for their cards. This may be done while the regulator
  69. is enabled or disabled.
  70. The :c:func:`regulator_set_voltage()` and
  71. :c:func:`regulator_set_current_limit()` functions provide the primary
  72. interface for this. Both take ranges of voltages and currents, supporting
  73. drivers that do not require a specific value (eg, CPU frequency scaling
  74. normally permits the CPU to use a wider range of supply voltages at lower
  75. frequencies but does not require that the supply voltage be lowered). Where
  76. an exact value is required both minimum and maximum values should be
  77. identical.
  78. Callbacks
  79. ---------
  80. Callbacks may also be registered for events such as regulation failures.
  81. Regulator driver interface
  82. ==========================
  83. Drivers for regulator chips register the regulators with the regulator
  84. core, providing operations structures to the core. A notifier interface
  85. allows error conditions to be reported to the core.
  86. Registration should be triggered by explicit setup done by the platform,
  87. supplying a struct regulator_init_data for the regulator
  88. containing constraint and supply information.
  89. Machine interface
  90. =================
  91. This interface provides a way to define how regulators are connected to
  92. consumers on a given system and what the valid operating parameters are
  93. for the system.
  94. Supplies
  95. --------
  96. Regulator supplies are specified using struct
  97. :c:type:`regulator_consumer_supply`. This is done at driver registration
  98. time as part of the machine constraints.
  99. Constraints
  100. -----------
  101. As well as defining the connections the machine interface also provides
  102. constraints defining the operations that clients are allowed to perform
  103. and the parameters that may be set. This is required since generally
  104. regulator devices will offer more flexibility than it is safe to use on
  105. a given system, for example supporting higher supply voltages than the
  106. consumers are rated for.
  107. This is done at driver registration time` by providing a
  108. struct regulation_constraints.
  109. The constraints may also specify an initial configuration for the
  110. regulator in the constraints, which is particularly useful for use with
  111. static consumers.
  112. API reference
  113. =============
  114. Due to limitations of the kernel documentation framework and the
  115. existing layout of the source code the entire regulator API is
  116. documented here.
  117. .. kernel-doc:: include/linux/regulator/consumer.h
  118. :internal:
  119. .. kernel-doc:: include/linux/regulator/machine.h
  120. :internal:
  121. .. kernel-doc:: include/linux/regulator/driver.h
  122. :internal:
  123. .. kernel-doc:: drivers/regulator/core.c
  124. :export: