Linux voltage and current regulator framework

Framework 목적과 저작자

이 framework는 voltage regulator와 current regulator를 제어하는 표준 kernel interface를 제공합니다.

System이 regulator power output을 동적으로 제어해 power를 절약하고 battery life를 늘리게 하는 것이 목적입니다. Output voltage를 제어하는 voltage regulator와 current limit을 제어하는 current sink 모두에 적용됩니다.

Copyright는 2008 Wolfson Microelectronics PLC이고 저자는 Liam Girdwood `<lrg@slimlogic.co.uk>`입니다.

=============================================
Linux voltage and current regulator framework
=============================================

About
=====

This framework is designed to provide a standard kernel interface to control
voltage and current regulators.

The intention is to allow systems to dynamically control regulator power output
in order to save power and prolong battery life. This applies to both voltage
regulators (where voltage output is controllable) and current sinks (where
current limit is controllable).

(C) 2008  Wolfson Microelectronics PLC.

Author: Liam Girdwood <lrg@slimlogic.co.uk>

Regulator, PMIC와 consumer

Regulator는 다른 device에 power를 공급하는 electronic device입니다. 대부분 output을 enable/disable할 수 있고 일부는 output voltage 또는 current도 제어합니다. 흐름은 `Input Voltage -> Regulator -> Output Voltage`입니다.

PMIC는 Power Management IC로, 여러 regulator와 흔히 다른 subsystem까지 포함하는 IC입니다.

Consumer는 regulator에서 power를 공급받는 electronic device입니다. Static consumer는 supply voltage나 current limit을 바꾸지 않고 power enable/disable만 필요합니다. Supply voltage는 hardware, bootloader, firmware 또는 kernel board initialization code가 설정합니다.

Dynamic consumer는 동작 요구에 맞춰 supply voltage 또는 current limit을 바꿔야 합니다.

Nomenclature
============

Some terms used in this document:

  - Regulator
                 - Electronic device that supplies power to other devices.
                   Most regulators can enable and disable their output while
                   some can control their output voltage and or current.

                   Input Voltage -> Regulator -> Output Voltage


  - PMIC
                 - Power Management IC. An IC that contains numerous
                   regulators and often contains other subsystems.


  - Consumer
                 - Electronic device that is supplied power by a regulator.
                   Consumers can be classified into two types:-

                   Static: consumer does not change its supply voltage or
                   current limit. It only needs to enable or disable its
                   power supply. Its supply voltage is set by the hardware,
                   bootloader, firmware or kernel board initialisation code.

                   Dynamic: consumer needs to change its supply voltage or
                   current limit to meet operation demands.

Power domain과 supplies 관계

Power domain은 regulator, switch 또는 다른 power domain의 output power를 input으로 받는 electronic circuit입니다.

첫 예제에서 Regulator가 Switch-1과 Consumer D·E에 공급하고, Switch-1은 Switch-2와 Consumer B·C에, Switch-2는 Consumer A에 공급합니다. 이는 Domain 1 `Switch-1, Consumers D & E`, Domain 2 `Switch-2, Consumers B & C`, Domain 3 `Consumer A`이며 `Domain-1 -> Domain-2 -> Domain-3` supplies 관계입니다.

두 번째 예제에서는 Regulator-1이 Regulator-2와 Consumer B에 공급하고 Regulator-2가 Consumer A에 공급합니다. Domain 1은 `Regulator-2, Consumer B`, Domain 2는 `Consumer A`이고 supplies 관계는 `Domain-1 -> Domain-2`입니다.

  - Power Domain
                 - Electronic circuit that is supplied its input power by the
                   output power of a regulator, switch or by another power
                   domain.

                   The supply regulator may be behind a switch(s). i.e.::

                     Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
                                |             |
                                |             +-> [Consumer B], [Consumer C]
                                |
                                +-> [Consumer D], [Consumer E]

                   That is one regulator and three power domains:

                   - Domain 1: Switch-1, Consumers D & E.
                   - Domain 2: Switch-2, Consumers B & C.
                   - Domain 3: Consumer A.

                   and this represents a "supplies" relationship:

                   Domain-1 --> Domain-2 --> Domain-3.

                   A power domain may have regulators that are supplied power
                   by other regulators. i.e.::

                     Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
                                  |
                                  +-> [Consumer B]

                   This gives us two regulators and two power domains:

                   - Domain 1: Regulator-2, Consumer B.
                   - Domain 2: Consumer A.

                   and a "supplies" relationship:

                   Domain-1 --> Domain-2

세 단계 constraint

Constraint는 performance와 hardware protection을 위한 power level을 정의하며 regulator level, power-domain level, consumer level의 세 단계에 존재합니다.

Regulator-level constraint는 datasheet에 명시된 hardware operating parameter입니다. 예를 들어 voltage output 800~3500mV, current output limit 5V에서 20mA·10V에서 10mA입니다.

Power-domain-level constraint는 kernel board initialization code가 software로 정의하며 domain을 특정 power 범위로 제한합니다. 예로 Domain-1 3300mV, Domain-2 1400~1600mV, Domain-3 current limit 0~20mA가 있습니다.

Consumer-level constraint는 consumer driver가 voltage 또는 current-limit level을 동적으로 설정합니다. 예를 들어 backlight driver가 LCD 밝기를 높이려고 current를 5mA에서 10mA로 올리도록 요청합니다.

이 요청은 consumer가 brightness table에서 다음 current 값을 선택하고, power domain이 현재 battery/USB 같은 system state에서 domain limit 안인지 검사하고, regulator domain이 input/output voltage에 대한 hardware parameter 안인지 검사하는 순서로 통과합니다. 모든 constraint test를 통과해야 새 regulator 값을 적용합니다.

  - Constraints
                 - Constraints are used to define power levels for performance
                   and hardware protection. Constraints exist at three levels:

                   Regulator Level: This is defined by the regulator hardware
                   operating parameters and is specified in the regulator
                   datasheet. i.e.

                     - voltage output is in the range 800mV -> 3500mV.
                     - regulator current output limit is 20mA @ 5V but is
                       10mA @ 10V.

                   Power Domain Level: This is defined in software by kernel
                   level board initialisation code. It is used to constrain a
                   power domain to a particular power range. i.e.

                     - Domain-1 voltage is 3300mV
                     - Domain-2 voltage is 1400mV -> 1600mV
                     - Domain-3 current limit is 0mA -> 20mA.

                   Consumer Level: This is defined by consumer drivers
                   dynamically setting voltage or current limit levels.

                   e.g. a consumer backlight driver asks for a current increase
                   from 5mA to 10mA to increase LCD illumination. This passes
                   to through the levels as follows :-

                   Consumer: need to increase LCD brightness. Lookup and
                   request next current mA value in brightness table (the
                   consumer driver could be used on several different
                   personalities based upon the same reference device).

                   Power Domain: is the new current limit within the domain
                   operating limits for this domain and system state (e.g.
                   battery power, USB power)

                   Regulator Domains: is the new current limit within the
                   regulator operating parameters for input/output voltage.

                   If the regulator request passes all the constraint tests
                   then the new regulator value is applied.

네 가지 framework interface

Framework는 SoC device를 주 대상으로 설계됐지만 non-SoC device에도 관련될 수 있으며 네 interface로 나뉩니다.

Consumer driver interface는 kernel clock interface와 비슷하게 regulator get/put, voltage·current limit·mode get/set, enable/disable을 제공합니다. 사용하지 않을 때 compile out되므로 regulator 기반 power control이 없는 system에서도 driver를 재사용할 수 있습니다. 자세한 내용은 `Documentation/power/regulator/consumer.rst`를 봅니다.

Regulator driver interface는 regulator driver가 regulator와 operation을 core에 등록하게 하고 event를 client로 전달하는 notifier call chain을 제공합니다. `Documentation/power/regulator/regulator.rst`를 참고합니다.

Machine interface는 machine-specific code가 regulator별 voltage/current domain과 constraint를 만들게 합니다. Buggy client driver의 overvoltage·overcurrent로 인한 손상을 막고, regulator가 다른 regulator에서 공급받는 clock-tree 같은 regulator tree도 만들 수 있습니다. `Documentation/power/regulator/machine.rst`를 참고합니다.

Userspace ABI는 유용한 voltage, current, operating-mode data를 sysfs로 내보내 device power consumption과 상태 monitoring을 돕습니다. `Documentation/ABI/testing/sysfs-class-regulator`를 참고합니다.

Design
======

The framework is designed and targeted at SoC based devices but may also be
relevant to non SoC devices and is split into the following four interfaces:-


   1. Consumer driver interface.

      This uses a similar API to the kernel clock interface in that consumer
      drivers can get and put a regulator (like they can with clocks atm) and
      get/set voltage, current limit, mode, enable and disable. This should
      allow consumers complete control over their supply voltage and current
      limit. This also compiles out if not in use so drivers can be reused in
      systems with no regulator based power control.

        See Documentation/power/regulator/consumer.rst

   2. Regulator driver interface.

      This allows regulator drivers to register their regulators and provide
      operations to the core. It also has a notifier call chain for propagating
      regulator events to clients.

        See Documentation/power/regulator/regulator.rst

   3. Machine interface.

      This interface is for machine specific code and allows the creation of
      voltage/current domains (with constraints) for each regulator. It can
      provide regulator constraints that will prevent device damage through
      overvoltage or overcurrent caused by buggy client drivers. It also
      allows the creation of a regulator tree whereby some regulators are
      supplied by others (similar to a clock tree).

        See Documentation/power/regulator/machine.rst

   4. Userspace ABI.

      The framework also exports a lot of useful voltage/current/opmode data to
      userspace via sysfs. This could be used to help monitor device power
      consumption and status.

        See Documentation/ABI/testing/sysfs-class-regulator