lkml.org 
[lkml]   [2008]   [May]   [2]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Subject[PATCH 09/13] regulator: documentation - overview
    From
    Date
    This adds overview documentation describing the regulator framework and
    nomenclature used in the interface specific documentation and code.

    Signed-off-by: Liam Girdwood <lg@opensource.wolfsonmicro.com>
    ---
    Documentation/power/regulator/overview.txt | 171 ++++++++++++++++++++++++++++
    1 files changed, 171 insertions(+), 0 deletions(-)
    create mode 100644 Documentation/power/regulator/overview.txt

    diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.txt
    new file mode 100644
    index 0000000..bdcb332
    --- /dev/null
    +++ b/Documentation/power/regulator/overview.txt
    @@ -0,0 +1,171 @@
    +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 <lg@opensource.wolfsonmicro.com>
    +
    +
    +Nomenclature
    +============
    +
    +Some terms used in this document:-
    +
    + o Regulator - Electronic device that supplies power to other devices.
    + Most regulators can enable and disable their output whilst
    + some can control their output voltage and or current.
    +
    + Input Voltage -> Regulator -> Output Voltage
    +
    +
    + o PMIC - Power Management IC. An IC that contains numerous regulators
    + and often contains other susbsystems.
    +
    +
    + o Consumer - Electronic device that is supplied power by a regulator.
    + Consumers can be classified into two types:-
    +
    + Static: consumer does not change it's supply voltage or
    + current limit. It only needs to enable or disable it's
    + power supply. It's supply voltage is set by the hardware,
    + bootloader, firmware or kernel board initialisation code.
    +
    + Dynamic: consumer needs to change it's supply voltage or
    + current limit to meet operation demands.
    +
    +
    + o Power Domain - Electronic circuit that is supplied it's 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
    +
    +
    + o 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/ouput voltage.
    +
    + If the regulator request passes all the constraint tests
    + then the new regulator value is applied.
    +
    +
    +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.txt
    +
    + 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.txt
    +
    + 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 over current 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.txt
    +
    + 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/regulator-sysfs.txt
    --
    1.5.4.3



    \
     
     \ /
      Last update: 2008-05-02 17:55    [W:0.037 / U:0.816 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site