summaryrefslogtreecommitdiffstats
path: root/Documentation/power/regulator
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/power/regulator')
-rw-r--r--Documentation/power/regulator/consumer.txt182
-rw-r--r--Documentation/power/regulator/design.txt33
-rw-r--r--Documentation/power/regulator/machine.txt100
-rw-r--r--Documentation/power/regulator/overview.txt171
-rw-r--r--Documentation/power/regulator/regulator.txt30
5 files changed, 0 insertions, 516 deletions
diff --git a/Documentation/power/regulator/consumer.txt b/Documentation/power/regulator/consumer.txt
deleted file mode 100644
index 55c4175d809..00000000000
--- a/Documentation/power/regulator/consumer.txt
+++ /dev/null
@@ -1,182 +0,0 @@
-Regulator Consumer Driver Interface
-===================================
-
-This text describes the regulator interface for consumer device drivers.
-Please see overview.txt for a description of the terms used in this text.
-
-
-1. Consumer Regulator Access (static & dynamic drivers)
-=======================================================
-
-A consumer driver can get access to its supply regulator by calling :-
-
-regulator = regulator_get(dev, "Vcc");
-
-The consumer passes in its struct device pointer and power supply ID. The core
-then finds the correct regulator by consulting a machine specific lookup table.
-If the lookup is successful then this call will return a pointer to the struct
-regulator that supplies this consumer.
-
-To release the regulator the consumer driver should call :-
-
-regulator_put(regulator);
-
-Consumers can be supplied by more than one regulator e.g. codec consumer with
-analog and digital supplies :-
-
-digital = regulator_get(dev, "Vcc"); /* digital core */
-analog = regulator_get(dev, "Avdd"); /* analog */
-
-The regulator access functions regulator_get() and regulator_put() will
-usually be called in your device drivers probe() and remove() respectively.
-
-
-2. Regulator Output Enable & Disable (static & dynamic drivers)
-====================================================================
-
-A consumer can enable its power supply by calling:-
-
-int regulator_enable(regulator);
-
-NOTE: The supply may already be enabled before regulator_enabled() is called.
-This may happen if the consumer shares the regulator or the regulator has been
-previously enabled by bootloader or kernel board initialization code.
-
-A consumer can determine if a regulator is enabled by calling :-
-
-int regulator_is_enabled(regulator);
-
-This will return > zero when the regulator is enabled.
-
-
-A consumer can disable its supply when no longer needed by calling :-
-
-int regulator_disable(regulator);
-
-NOTE: This may not disable the supply if it's shared with other consumers. The
-regulator will only be disabled when the enabled reference count is zero.
-
-Finally, a regulator can be forcefully disabled in the case of an emergency :-
-
-int regulator_force_disable(regulator);
-
-NOTE: this will immediately and forcefully shutdown the regulator output. All
-consumers will be powered off.
-
-
-3. Regulator Voltage Control & Status (dynamic drivers)
-======================================================
-
-Some consumer drivers need to be able to dynamically change their supply
-voltage to match system operating points. e.g. CPUfreq drivers can scale
-voltage along with frequency to save power, SD drivers may need to select the
-correct card voltage, etc.
-
-Consumers can control their supply voltage by calling :-
-
-int regulator_set_voltage(regulator, min_uV, max_uV);
-
-Where min_uV and max_uV are the minimum and maximum acceptable voltages in
-microvolts.
-
-NOTE: this can be called when the regulator is enabled or disabled. If called
-when enabled, then the voltage changes instantly, otherwise the voltage
-configuration changes and the voltage is physically set when the regulator is
-next enabled.
-
-The regulators configured voltage output can be found by calling :-
-
-int regulator_get_voltage(regulator);
-
-NOTE: get_voltage() will return the configured output voltage whether the
-regulator is enabled or disabled and should NOT be used to determine regulator
-output state. However this can be used in conjunction with is_enabled() to
-determine the regulator physical output voltage.
-
-
-4. Regulator Current Limit Control & Status (dynamic drivers)
-===========================================================
-
-Some consumer drivers need to be able to dynamically change their supply
-current limit to match system operating points. e.g. LCD backlight driver can
-change the current limit to vary the backlight brightness, USB drivers may want
-to set the limit to 500mA when supplying power.
-
-Consumers can control their supply current limit by calling :-
-
-int regulator_set_current_limit(regulator, min_uA, max_uA);
-
-Where min_uA and max_uA are the minimum and maximum acceptable current limit in
-microamps.
-
-NOTE: this can be called when the regulator is enabled or disabled. If called
-when enabled, then the current limit changes instantly, otherwise the current
-limit configuration changes and the current limit is physically set when the
-regulator is next enabled.
-
-A regulators current limit can be found by calling :-
-
-int regulator_get_current_limit(regulator);
-
-NOTE: get_current_limit() will return the current limit whether the regulator
-is enabled or disabled and should not be used to determine regulator current
-load.
-
-
-5. Regulator Operating Mode Control & Status (dynamic drivers)
-=============================================================
-
-Some consumers can further save system power by changing the operating mode of
-their supply regulator to be more efficient when the consumers operating state
-changes. e.g. consumer driver is idle and subsequently draws less current
-
-Regulator operating mode can be changed indirectly or directly.
-
-Indirect operating mode control.
---------------------------------
-Consumer drivers can request a change in their supply regulator operating mode
-by calling :-
-
-int regulator_set_optimum_mode(struct regulator *regulator, int load_uA);
-
-This will cause the core to recalculate the total load on the regulator (based
-on all its consumers) and change operating mode (if necessary and permitted)
-to best match the current operating load.
-
-The load_uA value can be determined from the consumers datasheet. e.g.most
-datasheets have tables showing the max current consumed in certain situations.
-
-Most consumers will use indirect operating mode control since they have no
-knowledge of the regulator or whether the regulator is shared with other
-consumers.
-
-Direct operating mode control.
-------------------------------
-Bespoke or tightly coupled drivers may want to directly control regulator
-operating mode depending on their operating point. This can be achieved by
-calling :-
-
-int regulator_set_mode(struct regulator *regulator, unsigned int mode);
-unsigned int regulator_get_mode(struct regulator *regulator);
-
-Direct mode will only be used by consumers that *know* about the regulator and
-are not sharing the regulator with other consumers.
-
-
-6. Regulator Events
-===================
-Regulators can notify consumers of external events. Events could be received by
-consumers under regulator stress or failure conditions.
-
-Consumers can register interest in regulator events by calling :-
-
-int regulator_register_notifier(struct regulator *regulator,
- struct notifier_block *nb);
-
-Consumers can uregister interest by calling :-
-
-int regulator_unregister_notifier(struct regulator *regulator,
- struct notifier_block *nb);
-
-Regulators use the kernel notifier framework to send event to their interested
-consumers.
diff --git a/Documentation/power/regulator/design.txt b/Documentation/power/regulator/design.txt
deleted file mode 100644
index f9b56b72b78..00000000000
--- a/Documentation/power/regulator/design.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-Regulator API design notes
-==========================
-
-This document provides a brief, partially structured, overview of some
-of the design considerations which impact the regulator API design.
-
-Safety
-------
-
- - Errors in regulator configuration can have very serious consequences
- for the system, potentially including lasting hardware damage.
- - It is not possible to automatically determine the power confugration
- of the system - software-equivalent variants of the same chip may
- have different power requirments, and not all components with power
- requirements are visible to software.
-
- => The API should make no changes to the hardware state unless it has
- specific knowledge that these changes are safe to do perform on
- this particular system.
-
-Consumer use cases
-------------------
-
- - The overwhelming majority of devices in a system will have no
- requirement to do any runtime configuration of their power beyond
- being able to turn it on or off.
-
- - Many of the power supplies in the system will be shared between many
- different consumers.
-
- => The consumer API should be structured so that these use cases are
- very easy to handle and so that consumers will work with shared
- supplies without any additional effort.
diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.txt
deleted file mode 100644
index ce63af0a8e3..00000000000
--- a/Documentation/power/regulator/machine.txt
+++ /dev/null
@@ -1,100 +0,0 @@
-Regulator Machine Driver Interface
-===================================
-
-The regulator machine driver interface is intended for board/machine specific
-initialisation code to configure the regulator subsystem.
-
-Consider the following machine :-
-
- Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
- |
- +-> [Consumer B @ 3.3V]
-
-The drivers for consumers A & B must be mapped to the correct regulator in
-order to control their power supply. This mapping can be achieved in machine
-initialisation code by creating a struct regulator_consumer_supply for
-each regulator.
-
-struct regulator_consumer_supply {
- const char *dev_name; /* consumer dev_name() */
- const char *supply; /* consumer supply - e.g. "vcc" */
-};
-
-e.g. for the machine above
-
-static struct regulator_consumer_supply regulator1_consumers[] = {
-{
- .dev_name = "dev_name(consumer B)",
- .supply = "Vcc",
-},};
-
-static struct regulator_consumer_supply regulator2_consumers[] = {
-{
- .dev = "dev_name(consumer A"),
- .supply = "Vcc",
-},};
-
-This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2
-to the 'Vcc' supply for Consumer A.
-
-Constraints can now be registered by defining a struct regulator_init_data
-for each regulator power domain. This structure also maps the consumers
-to their supply regulator :-
-
-static struct regulator_init_data regulator1_data = {
- .constraints = {
- .name = "Regulator-1",
- .min_uV = 3300000,
- .max_uV = 3300000,
- .valid_modes_mask = REGULATOR_MODE_NORMAL,
- },
- .num_consumer_supplies = ARRAY_SIZE(regulator1_consumers),
- .consumer_supplies = regulator1_consumers,
-};
-
-The name field should be set to something that is usefully descriptive
-for the board for configuration of supplies for other regulators and
-for use in logging and other diagnostic output. Normally the name
-used for the supply rail in the schematic is a good choice. If no
-name is provided then the subsystem will choose one.
-
-Regulator-1 supplies power to Regulator-2. This relationship must be registered
-with the core so that Regulator-1 is also enabled when Consumer A enables its
-supply (Regulator-2). The supply regulator is set by the supply_regulator
-field below and co:-
-
-static struct regulator_init_data regulator2_data = {
- .supply_regulator = "Regulator-1",
- .constraints = {
- .min_uV = 1800000,
- .max_uV = 2000000,
- .valid_ops_mask = REGULATOR_CHANGE_VOLTAGE,
- .valid_modes_mask = REGULATOR_MODE_NORMAL,
- },
- .num_consumer_supplies = ARRAY_SIZE(regulator2_consumers),
- .consumer_supplies = regulator2_consumers,
-};
-
-Finally the regulator devices must be registered in the usual manner.
-
-static struct platform_device regulator_devices[] = {
-{
- .name = "regulator",
- .id = DCDC_1,
- .dev = {
- .platform_data = &regulator1_data,
- },
-},
-{
- .name = "regulator",
- .id = DCDC_2,
- .dev = {
- .platform_data = &regulator2_data,
- },
-},
-};
-/* register regulator 1 device */
-platform_device_register(&regulator_devices[0]);
-
-/* register regulator 2 device */
-platform_device_register(&regulator_devices[1]);
diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.txt
deleted file mode 100644
index 8ed17587a74..00000000000
--- a/Documentation/power/regulator/overview.txt
+++ /dev/null
@@ -1,171 +0,0 @@
-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>
-
-
-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 subsystems.
-
-
- o 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 it's
- power supply. Its 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 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
-
-
- 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/output 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/sysfs-class-regulator
diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt
deleted file mode 100644
index 13902778ae4..00000000000
--- a/Documentation/power/regulator/regulator.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-Regulator Driver Interface
-==========================
-
-The regulator driver interface is relatively simple and designed to allow
-regulator drivers to register their services with the core framework.
-
-
-Registration
-============
-
-Drivers can register a regulator by calling :-
-
-struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
- const struct regulator_config *config);
-
-This will register the regulators capabilities and operations to the regulator
-core.
-
-Regulators can be unregistered by calling :-
-
-void regulator_unregister(struct regulator_dev *rdev);
-
-
-Regulator Events
-================
-Regulators can send events (e.g. over temp, under voltage, etc) to consumer
-drivers by calling :-
-
-int regulator_notifier_call_chain(struct regulator_dev *rdev,
- unsigned long event, void *data);