cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

regulator.rst (6007B)


      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=================================
      8Voltage and current regulator API
      9=================================
     10
     11:Author: Liam Girdwood
     12:Author: Mark Brown
     13
     14Introduction
     15============
     16
     17This framework is designed to provide a standard kernel interface to
     18control voltage and current regulators.
     19
     20The intention is to allow systems to dynamically control regulator power
     21output in order to save power and prolong battery life. This applies to
     22both voltage regulators (where voltage output is controllable) and
     23current sinks (where current limit is controllable).
     24
     25Note that additional (and currently more complete) documentation is
     26available in the Linux kernel source under
     27``Documentation/power/regulator``.
     28
     29Glossary
     30--------
     31
     32The regulator API uses a number of terms which may not be familiar:
     33
     34Regulator
     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
     40Consumer
     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
     46Power 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
     52Power 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
     58Consumer driver interface
     59=========================
     60
     61This offers a similar API to the kernel clock framework. Consumer
     62drivers use `get <#API-regulator-get>`__ and
     63`put <#API-regulator-put>`__ operations to acquire and release
     64regulators. Functions are provided to `enable <#API-regulator-enable>`__
     65and `disable <#API-regulator-disable>`__ the regulator and to get and
     66set the runtime parameters of the regulator.
     67
     68When requesting regulators consumers use symbolic names for their
     69supplies, such as "Vcc", which are mapped into actual regulator devices
     70by the machine interface.
     71
     72A stub version of this API is provided when the regulator framework is
     73not in use in order to minimise the need to use ifdefs.
     74
     75Enabling and disabling
     76----------------------
     77
     78The regulator API provides reference counted enabling and disabling of
     79regulators. Consumer devices use the :c:func:`regulator_enable()` and
     80:c:func:`regulator_disable()` functions to enable and disable
     81regulators. Calls to the two functions must be balanced.
     82
     83Note that since multiple consumers may be using a regulator and machine
     84constraints may not allow the regulator to be disabled there is no
     85guarantee that calling :c:func:`regulator_disable()` will actually
     86cause the supply provided by the regulator to be disabled. Consumer
     87drivers should assume that the regulator may be enabled at all times.
     88
     89Configuration
     90-------------
     91
     92Some consumer devices may need to be able to dynamically configure their
     93supplies. For example, MMC drivers may need to select the correct
     94operating voltage for their cards. This may be done while the regulator
     95is enabled or disabled.
     96
     97The :c:func:`regulator_set_voltage()` and
     98:c:func:`regulator_set_current_limit()` functions provide the primary
     99interface for this. Both take ranges of voltages and currents, supporting
    100drivers that do not require a specific value (eg, CPU frequency scaling
    101normally permits the CPU to use a wider range of supply voltages at lower
    102frequencies but does not require that the supply voltage be lowered). Where
    103an exact value is required both minimum and maximum values should be
    104identical.
    105
    106Callbacks
    107---------
    108
    109Callbacks may also be registered for events such as regulation failures.
    110
    111Regulator driver interface
    112==========================
    113
    114Drivers for regulator chips register the regulators with the regulator
    115core, providing operations structures to the core. A notifier interface
    116allows error conditions to be reported to the core.
    117
    118Registration should be triggered by explicit setup done by the platform,
    119supplying a struct regulator_init_data for the regulator
    120containing constraint and supply information.
    121
    122Machine interface
    123=================
    124
    125This interface provides a way to define how regulators are connected to
    126consumers on a given system and what the valid operating parameters are
    127for the system.
    128
    129Supplies
    130--------
    131
    132Regulator supplies are specified using struct
    133:c:type:`regulator_consumer_supply`. This is done at driver registration
    134time as part of the machine constraints.
    135
    136Constraints
    137-----------
    138
    139As well as defining the connections the machine interface also provides
    140constraints defining the operations that clients are allowed to perform
    141and the parameters that may be set. This is required since generally
    142regulator devices will offer more flexibility than it is safe to use on
    143a given system, for example supporting higher supply voltages than the
    144consumers are rated for.
    145
    146This is done at driver registration time` by providing a
    147struct regulation_constraints.
    148
    149The constraints may also specify an initial configuration for the
    150regulator in the constraints, which is particularly useful for use with
    151static consumers.
    152
    153API reference
    154=============
    155
    156Due to limitations of the kernel documentation framework and the
    157existing layout of the source code the entire regulator API is
    158documented 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: