diff options
Diffstat (limited to 'Documentation/power/regulator')
| -rw-r--r-- | Documentation/power/regulator/consumer.rst (renamed from Documentation/power/regulator/consumer.txt) | 141 | ||||
| -rw-r--r-- | Documentation/power/regulator/design.rst (renamed from Documentation/power/regulator/design.txt) | 9 | ||||
| -rw-r--r-- | Documentation/power/regulator/machine.rst (renamed from Documentation/power/regulator/machine.txt) | 47 | ||||
| -rw-r--r-- | Documentation/power/regulator/overview.rst (renamed from Documentation/power/regulator/overview.txt) | 57 | ||||
| -rw-r--r-- | Documentation/power/regulator/regulator.rst | 32 | ||||
| -rw-r--r-- | Documentation/power/regulator/regulator.txt | 30 |
6 files changed, 171 insertions, 145 deletions
diff --git a/Documentation/power/regulator/consumer.txt b/Documentation/power/regulator/consumer.rst index e51564c1a140..0cd8cc1275a7 100644 --- a/Documentation/power/regulator/consumer.txt +++ b/Documentation/power/regulator/consumer.rst @@ -1,3 +1,4 @@ +=================================== Regulator Consumer Driver Interface =================================== @@ -8,73 +9,77 @@ 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 :- +A consumer driver can get access to its supply regulator by calling :: -regulator = regulator_get(dev, "Vcc"); + 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 :- +To release the regulator the consumer driver should call :: -regulator_put(regulator); + regulator_put(regulator); Consumers can be supplied by more than one regulator e.g. codec consumer with -analog and digital supplies :- +analog and digital supplies :: -digital = regulator_get(dev, "Vcc"); /* digital core */ -analog = regulator_get(dev, "Avdd"); /* analog */ + 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:- +A consumer can enable its power supply by calling:: -int regulator_enable(regulator); + 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. +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 :- +A consumer can determine if a regulator is enabled by calling:: -int regulator_is_enabled(regulator); + 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 :- +A consumer can disable its supply when no longer needed by calling:: -int regulator_disable(regulator); + 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. +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 :- +Finally, a regulator can be forcefully disabled in the case of an emergency:: -int regulator_force_disable(regulator); + int regulator_force_disable(regulator); -NOTE: this will immediately and forcefully shutdown the regulator output. All -consumers will be powered off. +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 :- +Consumers can control their supply voltage by calling:: -int regulator_set_voltage(regulator, min_uV, max_uV); + int regulator_set_voltage(regulator, min_uV, max_uV); Where min_uV and max_uV are the minimum and maximum acceptable voltages in microvolts. @@ -84,47 +89,50 @@ 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 :- +The regulators configured voltage output can be found by calling:: -int regulator_get_voltage(regulator); + 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. +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 :- +Consumers can control their supply current limit by calling:: -int regulator_set_current_limit(regulator, min_uA, max_uA); + 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. +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 :- +A regulators current limit can be found by calling:: -int regulator_get_current_limit(regulator); + 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. +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 @@ -135,9 +143,9 @@ 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 :- +by calling:: -int regulator_set_load(struct regulator *regulator, int load_uA); + int regulator_set_load(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) @@ -153,12 +161,13 @@ 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 :- +calling:: -int regulator_set_mode(struct regulator *regulator, unsigned int mode); -unsigned int regulator_get_mode(struct regulator *regulator); + 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. @@ -166,24 +175,26 @@ 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 :- +Consumers can register interest in regulator events by calling:: -int regulator_register_notifier(struct regulator *regulator, - struct notifier_block *nb); + int regulator_register_notifier(struct regulator *regulator, + struct notifier_block *nb); -Consumers can unregister interest by calling :- +Consumers can unregister interest by calling:: -int regulator_unregister_notifier(struct regulator *regulator, - struct notifier_block *nb); + int regulator_unregister_notifier(struct regulator *regulator, + struct notifier_block *nb); Regulators use the kernel notifier framework to send event to their interested consumers. 7. Regulator Direct Register Access =================================== + Some kinds of power management hardware or firmware are designed such that they need to do low-level hardware access to regulators, with no involvement from the kernel. Examples of such devices are: @@ -199,20 +210,20 @@ to it. The regulator framework provides the following helpers for querying these details. Bus-specific details, like I2C addresses or transfer rates are handled by the -regmap framework. To get the regulator's regmap (if supported), use :- +regmap framework. To get the regulator's regmap (if supported), use:: -struct regmap *regulator_get_regmap(struct regulator *regulator); + struct regmap *regulator_get_regmap(struct regulator *regulator); To obtain the hardware register offset and bitmask for the regulator's voltage -selector register, use :- +selector register, use:: -int regulator_get_hardware_vsel_register(struct regulator *regulator, - unsigned *vsel_reg, - unsigned *vsel_mask); + int regulator_get_hardware_vsel_register(struct regulator *regulator, + unsigned *vsel_reg, + unsigned *vsel_mask); To convert a regulator framework voltage selector code (used by regulator_list_voltage) to a hardware-specific voltage selector that can be -directly written to the voltage selector register, use :- +directly written to the voltage selector register, use:: -int regulator_list_hardware_vsel(struct regulator *regulator, - unsigned selector); + int regulator_list_hardware_vsel(struct regulator *regulator, + unsigned selector); diff --git a/Documentation/power/regulator/design.txt b/Documentation/power/regulator/design.rst index fdd919b96830..3b09c6841dc4 100644 --- a/Documentation/power/regulator/design.txt +++ b/Documentation/power/regulator/design.rst @@ -1,3 +1,4 @@ +========================== Regulator API design notes ========================== @@ -14,7 +15,9 @@ Safety have different power requirements, and not all components with power requirements are visible to software. - => The API should make no changes to the hardware state unless it has +.. note:: + + The API should make no changes to the hardware state unless it has specific knowledge that these changes are safe to perform on this particular system. @@ -28,6 +31,8 @@ Consumer use cases - 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 +.. note:: + + 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.rst index eff4dcaaa252..22fffefaa3ad 100644 --- a/Documentation/power/regulator/machine.txt +++ b/Documentation/power/regulator/machine.rst @@ -1,10 +1,11 @@ +================================== 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 :- +Consider the following machine:: Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V] | @@ -13,31 +14,31 @@ Consider the following machine :- The drivers for consumers A & B must be mapped to the correct regulator in order to control their power supplies. This mapping can be achieved in machine initialisation code by creating a struct regulator_consumer_supply for -each regulator. +each regulator:: -struct regulator_consumer_supply { + 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 +e.g. for the machine above:: -static struct regulator_consumer_supply regulator1_consumers[] = { + static struct regulator_consumer_supply regulator1_consumers[] = { REGULATOR_SUPPLY("Vcc", "consumer B"), -}; + }; -static struct regulator_consumer_supply regulator2_consumers[] = { + static struct regulator_consumer_supply regulator2_consumers[] = { REGULATOR_SUPPLY("Vcc", "consumer A"), -}; + }; 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 regulators :- +to their supply regulators:: -static struct regulator_init_data regulator1_data = { + static struct regulator_init_data regulator1_data = { .constraints = { .name = "Regulator-1", .min_uV = 3300000, @@ -46,7 +47,7 @@ static struct regulator_init_data regulator1_data = { }, .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 @@ -57,9 +58,9 @@ 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:- +field below and co:: -static struct regulator_init_data regulator2_data = { + static struct regulator_init_data regulator2_data = { .supply_regulator = "Regulator-1", .constraints = { .min_uV = 1800000, @@ -69,11 +70,11 @@ static struct regulator_init_data regulator2_data = { }, .num_consumer_supplies = ARRAY_SIZE(regulator2_consumers), .consumer_supplies = regulator2_consumers, -}; + }; -Finally the regulator devices must be registered in the usual manner. +Finally the regulator devices must be registered in the usual manner:: -static struct platform_device regulator_devices[] = { + static struct platform_device regulator_devices[] = { { .name = "regulator", .id = DCDC_1, @@ -88,9 +89,9 @@ static struct platform_device regulator_devices[] = { .platform_data = ®ulator2_data, }, }, -}; -/* register regulator 1 device */ -platform_device_register(®ulator_devices[0]); + }; + /* register regulator 1 device */ + platform_device_register(®ulator_devices[0]); -/* register regulator 2 device */ -platform_device_register(®ulator_devices[1]); + /* register regulator 2 device */ + platform_device_register(®ulator_devices[1]); diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.rst index 721b4739ec32..ee494c70a7c4 100644 --- a/Documentation/power/regulator/overview.txt +++ b/Documentation/power/regulator/overview.rst @@ -1,3 +1,4 @@ +============================================= Linux voltage and current regulator framework ============================================= @@ -13,26 +14,30 @@ 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:- +Some terms used in this document: - o Regulator - Electronic device that supplies power to other devices. + - 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 - o PMIC - Power Management IC. An IC that contains numerous regulators - and often contains other subsystems. + - 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. + - 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 @@ -44,46 +49,48 @@ Some terms used in this document:- current limit to meet operation demands. - o Power Domain - Electronic circuit that is supplied its input power by the + - 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. + 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] + 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. + - 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. + by other regulators. i.e.:: - Regulator-1 -+-> Regulator-2 -+-> [Consumer A] - | - +-> [Consumer B] + 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. + - 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 + - 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 @@ -141,7 +148,7 @@ relevant to non SoC devices and is split into the following four interfaces:- 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 + See Documentation/power/regulator/consumer.rst 2. Regulator driver interface. @@ -149,7 +156,7 @@ relevant to non SoC devices and is split into the following four interfaces:- operations to the core. It also has a notifier call chain for propagating regulator events to clients. - See Documentation/power/regulator/regulator.txt + See Documentation/power/regulator/regulator.rst 3. Machine interface. @@ -160,7 +167,7 @@ relevant to non SoC devices and is split into the following four interfaces:- 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 + See Documentation/power/regulator/machine.rst 4. Userspace ABI. diff --git a/Documentation/power/regulator/regulator.rst b/Documentation/power/regulator/regulator.rst new file mode 100644 index 000000000000..794b3256fbb9 --- /dev/null +++ b/Documentation/power/regulator/regulator.rst @@ -0,0 +1,32 @@ +========================== +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 regulator's 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. overtemperature, undervoltage, etc) to +consumer drivers by calling:: + + int regulator_notifier_call_chain(struct regulator_dev *rdev, + unsigned long event, void *data); diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt deleted file mode 100644 index b17e5833ce21..000000000000 --- 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 regulator's 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. overtemperature, undervoltage, etc) to -consumer drivers by calling :- - -int regulator_notifier_call_chain(struct regulator_dev *rdev, - unsigned long event, void *data); |