Commit 561b35b3 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge branch 'reg-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/lrg/voltage-2.6 

* 'reg-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/lrg/voltage-2.6:
  regulator: TI bq24022 Li-Ion Charger driver
  regulator: maintainers - add maintainers for regulator framework.
  regulator: documentation - ABI
  regulator: documentation - machine
  regulator: documentation - regulator driver
  regulator: documentation - consumer interface
  regulator: documentation - overview
  regulator: core kbuild files
  regulator: regulator test harness
  regulator: add support for fixed regulators.
  regulator: regulator framework core
  regulator: fixed regulator interface
  regulator: machine driver interface
  regulator: regulator driver interface
  regulator: consumer device interface
parents a7c2a10d 0eb5d5ab

Documentation/ABI/testing/sysfs-class-regulator

0 → 100644
+315 −0
Original line number Original line Diff line number Diff line 
What:		/sys/class/regulator/.../state

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		state. This holds the regulator output state.



		This will be one of the following strings:



		'enabled'

		'disabled'

		'unknown'



		'enabled' means the regulator output is ON and is supplying

		power to the system.



		'disabled' means the regulator output is OFF and is not

		supplying power to the system..



		'unknown' means software cannot determine the state.



		NOTE: this field can be used in conjunction with microvolts

		and microamps to determine regulator output levels.





What:		/sys/class/regulator/.../type

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		type. This holds the regulator type.



		This will be one of the following strings:



		'voltage'

		'current'

		'unknown'



		'voltage' means the regulator output voltage can be controlled

		by software.



		'current' means the regulator output current limit can be

		controlled by software.



		'unknown' means software cannot control either voltage or

		current limit.





What:		/sys/class/regulator/.../microvolts

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		microvolts. This holds the regulator output voltage setting

		measured in microvolts (i.e. E-6 Volts).



		NOTE: This value should not be used to determine the regulator

		output voltage level as this value is the same regardless of

		whether the regulator is enabled or disabled.





What:		/sys/class/regulator/.../microamps

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		microamps. This holds the regulator output current limit

		setting measured in microamps (i.e. E-6 Amps).



		NOTE: This value should not be used to determine the regulator

		output current level as this value is the same regardless of

		whether the regulator is enabled or disabled.





What:		/sys/class/regulator/.../opmode

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		opmode. This holds the regulator operating mode setting.



		The opmode value can be one of the following strings:



		'fast'

		'normal'

		'idle'

		'standby'

		'unknown'



		The modes are described in include/linux/regulator/regulator.h



		NOTE: This value should not be used to determine the regulator

		output operating mode as this value is the same regardless of

		whether the regulator is enabled or disabled.





What:		/sys/class/regulator/.../min_microvolts

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		min_microvolts. This holds the minimum safe working regulator

		output voltage setting for this domain measured in microvolts.



		NOTE: this will return the string 'constraint not defined' if

		the power domain has no min microvolts constraint defined by

		platform code.





What:		/sys/class/regulator/.../max_microvolts

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		max_microvolts. This holds the maximum safe working regulator

		output voltage setting for this domain measured in microvolts.



		NOTE: this will return the string 'constraint not defined' if

		the power domain has no max microvolts constraint defined by

		platform code.





What:		/sys/class/regulator/.../min_microamps

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		min_microamps. This holds the minimum safe working regulator

		output current limit setting for this domain measured in

		microamps.



		NOTE: this will return the string 'constraint not defined' if

		the power domain has no min microamps constraint defined by

		platform code.





What:		/sys/class/regulator/.../max_microamps

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		max_microamps. This holds the maximum safe working regulator

		output current limit setting for this domain measured in

		microamps.



		NOTE: this will return the string 'constraint not defined' if

		the power domain has no max microamps constraint defined by

		platform code.





What:		/sys/class/regulator/.../num_users

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		num_users. This holds the number of consumer devices that

		have called regulator_enable() on this regulator.





What:		/sys/class/regulator/.../requested_microamps

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		requested_microamps. This holds the total requested load

		current in microamps for this regulator from all its consumer

		devices.





What:		/sys/class/regulator/.../parent

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Some regulator directories will contain a link called parent.

		This points to the parent or supply regulator if one exists.



What:		/sys/class/regulator/.../suspend_mem_microvolts

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		suspend_mem_microvolts. This holds the regulator output

		voltage setting for this domain measured in microvolts when

		the system is suspended to memory.



		NOTE: this will return the string 'not defined' if

		the power domain has no suspend to memory voltage defined by

		platform code.



What:		/sys/class/regulator/.../suspend_disk_microvolts

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		suspend_disk_microvolts. This holds the regulator output

		voltage setting for this domain measured in microvolts when

		the system is suspended to disk.



		NOTE: this will return the string 'not defined' if

		the power domain has no suspend to disk voltage defined by

		platform code.



What:		/sys/class/regulator/.../suspend_standby_microvolts

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		suspend_standby_microvolts. This holds the regulator output

		voltage setting for this domain measured in microvolts when

		the system is suspended to standby.



		NOTE: this will return the string 'not defined' if

		the power domain has no suspend to standby voltage defined by

		platform code.



What:		/sys/class/regulator/.../suspend_mem_mode

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		suspend_mem_mode. This holds the regulator operating mode

		setting for this domain when the system is suspended to

		memory.



		NOTE: this will return the string 'not defined' if

		the power domain has no suspend to memory mode defined by

		platform code.



What:		/sys/class/regulator/.../suspend_disk_mode

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		suspend_disk_mode. This holds the regulator operating mode

		setting for this domain when the system is suspended to disk.



		NOTE: this will return the string 'not defined' if

		the power domain has no suspend to disk mode defined by

		platform code.



What:		/sys/class/regulator/.../suspend_standby_mode

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		suspend_standby_mode. This holds the regulator operating mode

		setting for this domain when the system is suspended to

		standby.



		NOTE: this will return the string 'not defined' if

		the power domain has no suspend to standby mode defined by

		platform code.



What:		/sys/class/regulator/.../suspend_mem_state

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		suspend_mem_state. This holds the regulator operating state

		when suspended to memory.



		This will be one of the following strings:



		'enabled'

		'disabled'

		'not defined'



What:		/sys/class/regulator/.../suspend_disk_state

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		suspend_disk_state. This holds the regulator operating state

		when suspended to disk.



		This will be one of the following strings:



		'enabled'

		'disabled'

		'not defined'



What:		/sys/class/regulator/.../suspend_standby_state

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lg@opensource.wolfsonmicro.com>

Description:

		Each regulator directory will contain a field called

		suspend_standby_state. This holds the regulator operating

		state when suspended to standby.



		This will be one of the following strings:



		'enabled'

		'disabled'

		'not defined'

Documentation/power/regulator/consumer.txt

0 → 100644
+182 −0
Original line number Original line Diff line number Diff line 
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 it's supply regulator by calling :-



regulator = regulator_get(dev, "Vcc");



The consumer passes in it's 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 it's 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 it's 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_uV, max_uV);



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 it's 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 thier interested

consumers.

Documentation/power/regulator/machine.txt

0 → 100644
+101 −0
Original line number Original line Diff line number Diff line 
Regulator Machine Driver Interface

===================================



The regulator machine driver interface is intended for board/machine specific

initialisation code to configure the regulator subsystem. Typical things that

machine drivers would do are :-



 1. Regulator -> Device mapping.

 2. Regulator supply configuration.

 3. Power Domain constraint setting.







1. Regulator -> device mapping

==============================

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 calling :-



int regulator_set_device_supply(const char *regulator, struct device *dev,

				const char *supply);



and is shown with the following code :-



regulator_set_device_supply("Regulator-1", devB, "Vcc");

regulator_set_device_supply("Regulator-2", devA, "Vcc");



This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2

to the 'Vcc' supply for Consumer A.





2. Regulator supply configuration.

==================================

Consider the following machine (again) :-



  Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]

               |

               +-> [Consumer B @ 3.3V]



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).



This relationship can be register with the core via :-



int regulator_set_supply(const char *regulator, const char *regulator_supply);



In this example we would use the following code :-



regulator_set_supply("Regulator-2", "Regulator-1");



Relationships can be queried by calling :-



const char *regulator_get_supply(const char *regulator);





3. Power Domain constraint setting.

===================================

Each power domain within a system has physical constraints on voltage and

current. This must be defined in software so that the power domain is always

operated within specifications.



Consider the following machine (again) :-



  Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]

               |

               +-> [Consumer B @ 3.3V]



This gives us two regulators and two power domains:



                   Domain 1: Regulator-2, Consumer B.

                   Domain 2: Consumer A.



Constraints can be registered by calling :-



int regulator_set_platform_constraints(const char *regulator,

	struct regulation_constraints *constraints);



The example is defined as follows :-



struct regulation_constraints domain_1 = {

	.min_uV = 3300000,

	.max_uV = 3300000,

	.valid_modes_mask = REGULATOR_MODE_NORMAL,

};



struct regulation_constraints domain_2 = {

	.min_uV = 1800000,

	.max_uV = 2000000,

	.valid_ops_mask = REGULATOR_CHANGE_VOLTAGE,

	.valid_modes_mask = REGULATOR_MODE_NORMAL,

};



regulator_set_platform_constraints("Regulator-1", &domain_1);

regulator_set_platform_constraints("Regulator-2", &domain_2);

Documentation/power/regulator/overview.txt

0 → 100644
+171 −0

File added.

Preview size limit exceeded, changes collapsed.

Documentation/power/regulator/regulator.txt

0 → 100644
+30 −0
Original line number Original line Diff line number Diff line 
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,

					  void *reg_data);



This will register the regulators capabilities and operations the regulator

core. The core does not touch reg_data (private to regulator driver).



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);

CRA Git | Maintained and supported by SUSTech CRA and CCSE