diff options
Diffstat (limited to 'Documentation/power/regulator')
| -rw-r--r-- | Documentation/power/regulator/consumer.txt | 14 | ||||
| -rw-r--r-- | Documentation/power/regulator/design.txt | 33 | ||||
| -rw-r--r-- | Documentation/power/regulator/machine.txt | 27 | ||||
| -rw-r--r-- | Documentation/power/regulator/overview.txt | 14 | ||||
| -rw-r--r-- | Documentation/power/regulator/regulator.txt | 4 |
5 files changed, 66 insertions, 26 deletions
diff --git a/Documentation/power/regulator/consumer.txt b/Documentation/power/regulator/consumer.txt index 82b7a43aadb..55c4175d809 100644 --- a/Documentation/power/regulator/consumer.txt +++ b/Documentation/power/regulator/consumer.txt @@ -8,11 +8,11 @@ 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 it's supply regulator by calling :- +A consumer driver can get access to its supply regulator by calling :- regulator = regulator_get(dev, "Vcc"); -The consumer passes in it's struct device pointer and power supply ID. The core +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. @@ -34,7 +34,7 @@ usually be called in your device drivers probe() and remove() respectively. 2. Regulator Output Enable & Disable (static & dynamic drivers) ==================================================================== -A consumer can enable it's power supply by calling:- +A consumer can enable its power supply by calling:- int regulator_enable(regulator); @@ -49,7 +49,7 @@ int regulator_is_enabled(regulator); This will return > zero when the regulator is enabled. -A consumer can disable it's supply when no longer needed by calling :- +A consumer can disable its supply when no longer needed by calling :- int regulator_disable(regulator); @@ -104,7 +104,7 @@ 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_uV, max_uV); +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. @@ -140,7 +140,7 @@ 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 it's consumers) and change operating mode (if necessary and permitted) +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 @@ -178,5 +178,5 @@ 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 thier interested +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 new file mode 100644 index 00000000000..f9b56b72b78 --- /dev/null +++ b/Documentation/power/regulator/design.txt @@ -0,0 +1,33 @@ +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 index ce3487d99ab..ce63af0a8e3 100644 --- a/Documentation/power/regulator/machine.txt +++ b/Documentation/power/regulator/machine.txt @@ -16,7 +16,7 @@ initialisation code by creating a struct regulator_consumer_supply for each regulator. struct regulator_consumer_supply { - struct device *dev; /* consumer */ + const char *dev_name; /* consumer dev_name() */ const char *supply; /* consumer supply - e.g. "vcc" */ }; @@ -24,13 +24,13 @@ e.g. for the machine above static struct regulator_consumer_supply regulator1_consumers[] = { { - .dev = &platform_consumerB_device.dev, - .supply = "Vcc", + .dev_name = "dev_name(consumer B)", + .supply = "Vcc", },}; static struct regulator_consumer_supply regulator2_consumers[] = { { - .dev = &platform_consumerA_device.dev, + .dev = "dev_name(consumer A"), .supply = "Vcc", },}; @@ -43,6 +43,7 @@ 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, @@ -51,13 +52,19 @@ static struct regulator_init_data regulator1_data = { .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 it's -supply (Regulator-2). The supply regulator is set by the supply_regulator_dev -field below:- +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_dev = &platform_regulator1_device.dev, + .supply_regulator = "Regulator-1", .constraints = { .min_uV = 1800000, .max_uV = 2000000, @@ -87,7 +94,7 @@ static struct platform_device regulator_devices[] = { }, }; /* register regulator 1 device */ -platform_device_register(&wm8350_regulator_devices[0]); +platform_device_register(®ulator_devices[0]); /* register regulator 2 device */ -platform_device_register(&wm8350_regulator_devices[1]); +platform_device_register(®ulator_devices[1]); diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.txt index bdcb332bd7f..8ed17587a74 100644 --- a/Documentation/power/regulator/overview.txt +++ b/Documentation/power/regulator/overview.txt @@ -13,7 +13,7 @@ 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> +Author: Liam Girdwood <lrg@slimlogic.co.uk> Nomenclature @@ -29,22 +29,22 @@ Some terms used in this document:- o PMIC - Power Management IC. An IC that contains numerous regulators - and often contains other susbsystems. + 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 it's supply voltage or + Static: consumer does not change its 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, + 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 it's input power by the + o Power Domain - Electronic circuit that is supplied its input power by the output power of a regulator, switch or by another power domain. @@ -119,7 +119,7 @@ Some terms used in this document:- battery power, USB power) Regulator Domains: is the new current limit within the - regulator operating parameters for input/ouput voltage. + regulator operating parameters for input/output voltage. If the regulator request passes all the constraint tests then the new regulator value is applied. @@ -168,4 +168,4 @@ relevant to non SoC devices and is split into the following four interfaces:- userspace via sysfs. This could be used to help monitor device power consumption and status. - See Documentation/ABI/testing/regulator-sysfs.txt + See Documentation/ABI/testing/sysfs-class-regulator diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt index 4200accb9bb..13902778ae4 100644 --- a/Documentation/power/regulator/regulator.txt +++ b/Documentation/power/regulator/regulator.txt @@ -10,8 +10,8 @@ Registration Drivers can register a regulator by calling :- -struct regulator_dev *regulator_register(struct device *dev, - struct regulator_desc *regulator_desc); +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. |