overview.rst 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178
  1. =============================================
  2. Linux voltage and current regulator framework
  3. =============================================
  4. About
  5. =====
  6. This framework is designed to provide a standard kernel interface to control
  7. voltage and current regulators.
  8. The intention is to allow systems to dynamically control regulator power output
  9. in order to save power and prolong battery life. This applies to both voltage
  10. regulators (where voltage output is controllable) and current sinks (where
  11. current limit is controllable).
  12. (C) 2008 Wolfson Microelectronics PLC.
  13. Author: Liam Girdwood <lrg@slimlogic.co.uk>
  14. Nomenclature
  15. ============
  16. Some terms used in this document:
  17. - Regulator
  18. - Electronic device that supplies power to other devices.
  19. Most regulators can enable and disable their output while
  20. some can control their output voltage and or current.
  21. Input Voltage -> Regulator -> Output Voltage
  22. - PMIC
  23. - Power Management IC. An IC that contains numerous
  24. regulators and often contains other subsystems.
  25. - Consumer
  26. - Electronic device that is supplied power by a regulator.
  27. Consumers can be classified into two types:-
  28. Static: consumer does not change its supply voltage or
  29. current limit. It only needs to enable or disable its
  30. power supply. Its supply voltage is set by the hardware,
  31. bootloader, firmware or kernel board initialisation code.
  32. Dynamic: consumer needs to change its supply voltage or
  33. current limit to meet operation demands.
  34. - Power Domain
  35. - Electronic circuit that is supplied its input power by the
  36. output power of a regulator, switch or by another power
  37. domain.
  38. The supply regulator may be behind a switch(s). i.e.::
  39. Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
  40. | |
  41. | +-> [Consumer B], [Consumer C]
  42. |
  43. +-> [Consumer D], [Consumer E]
  44. That is one regulator and three power domains:
  45. - Domain 1: Switch-1, Consumers D & E.
  46. - Domain 2: Switch-2, Consumers B & C.
  47. - Domain 3: Consumer A.
  48. and this represents a "supplies" relationship:
  49. Domain-1 --> Domain-2 --> Domain-3.
  50. A power domain may have regulators that are supplied power
  51. by other regulators. i.e.::
  52. Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
  53. |
  54. +-> [Consumer B]
  55. This gives us two regulators and two power domains:
  56. - Domain 1: Regulator-2, Consumer B.
  57. - Domain 2: Consumer A.
  58. and a "supplies" relationship:
  59. Domain-1 --> Domain-2
  60. - Constraints
  61. - Constraints are used to define power levels for performance
  62. and hardware protection. Constraints exist at three levels:
  63. Regulator Level: This is defined by the regulator hardware
  64. operating parameters and is specified in the regulator
  65. datasheet. i.e.
  66. - voltage output is in the range 800mV -> 3500mV.
  67. - regulator current output limit is 20mA @ 5V but is
  68. 10mA @ 10V.
  69. Power Domain Level: This is defined in software by kernel
  70. level board initialisation code. It is used to constrain a
  71. power domain to a particular power range. i.e.
  72. - Domain-1 voltage is 3300mV
  73. - Domain-2 voltage is 1400mV -> 1600mV
  74. - Domain-3 current limit is 0mA -> 20mA.
  75. Consumer Level: This is defined by consumer drivers
  76. dynamically setting voltage or current limit levels.
  77. e.g. a consumer backlight driver asks for a current increase
  78. from 5mA to 10mA to increase LCD illumination. This passes
  79. to through the levels as follows :-
  80. Consumer: need to increase LCD brightness. Lookup and
  81. request next current mA value in brightness table (the
  82. consumer driver could be used on several different
  83. personalities based upon the same reference device).
  84. Power Domain: is the new current limit within the domain
  85. operating limits for this domain and system state (e.g.
  86. battery power, USB power)
  87. Regulator Domains: is the new current limit within the
  88. regulator operating parameters for input/output voltage.
  89. If the regulator request passes all the constraint tests
  90. then the new regulator value is applied.
  91. Design
  92. ======
  93. The framework is designed and targeted at SoC based devices but may also be
  94. relevant to non SoC devices and is split into the following four interfaces:-
  95. 1. Consumer driver interface.
  96. This uses a similar API to the kernel clock interface in that consumer
  97. drivers can get and put a regulator (like they can with clocks atm) and
  98. get/set voltage, current limit, mode, enable and disable. This should
  99. allow consumers complete control over their supply voltage and current
  100. limit. This also compiles out if not in use so drivers can be reused in
  101. systems with no regulator based power control.
  102. See Documentation/power/regulator/consumer.rst
  103. 2. Regulator driver interface.
  104. This allows regulator drivers to register their regulators and provide
  105. operations to the core. It also has a notifier call chain for propagating
  106. regulator events to clients.
  107. See Documentation/power/regulator/regulator.rst
  108. 3. Machine interface.
  109. This interface is for machine specific code and allows the creation of
  110. voltage/current domains (with constraints) for each regulator. It can
  111. provide regulator constraints that will prevent device damage through
  112. overvoltage or overcurrent caused by buggy client drivers. It also
  113. allows the creation of a regulator tree whereby some regulators are
  114. supplied by others (similar to a clock tree).
  115. See Documentation/power/regulator/machine.rst
  116. 4. Userspace ABI.
  117. The framework also exports a lot of useful voltage/current/opmode data to
  118. userspace via sysfs. This could be used to help monitor device power
  119. consumption and status.
  120. See Documentation/ABI/testing/sysfs-class-regulator