Commit 022992ee authored by Linus Torvalds's avatar Linus Torvalds
Browse files

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

* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/lrg/voltage-2.6:
  regulator: fix kernel-doc warnings
  regulator: catch some registration errors
  regulator: Add basic DocBook manual
  regulator: Fix some kerneldoc rendering issues
  regulator: Add missing kerneldoc
  regulator: Clean up kerneldoc warnings
  regulator: Remove extraneous kerneldoc annotations
  regulator: init/link earlier
  regulator: move set_machine_constraints after regulator device initialization
  regulator: da903x: make da903x_is_enabled return 0 or 1
  regulator: da903x: add '\n' to error messages
  regulator: sysfs attribute reduction (v2)
  regulator: code shrink (v2)
  regulator: improved mode error checks
  regulator: enable/disable refcounting
  regulator: struct device - replace bus_id with dev_name(), dev_set_name()
parents 5fbbf5f6 0ba4887c

Documentation/ABI/testing/sysfs-class-regulator

+60 −76
Original line number Diff line number Diff line
@@ -3,8 +3,9 @@ Date: April 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		state. This holds the regulator output state.

		Some regulator directories will contain a field called

		state. This reports the regulator enable status, for

		regulators which can report that value.



		This will be one of the following strings:
@@ -18,7 +19,8 @@ Description: 
		'disabled' means the regulator output is OFF and is not

		supplying power to the system..



		'unknown' means software cannot determine the state.

		'unknown' means software cannot determine the state, or

		the reported state is invalid.



		NOTE: this field can be used in conjunction with microvolts

		and microamps to determine regulator output levels.
@@ -53,9 +55,10 @@ Date: April 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories will contain a field called

		microvolts. This holds the regulator output voltage setting

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

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

		which can report that voltage.



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

		output voltage level as this value is the same regardless of
@@ -67,9 +70,10 @@ Date: April 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories will contain a field called

		microamps. This holds the regulator output current limit

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

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

		which can report that current.



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

		output current level as this value is the same regardless of
@@ -81,8 +85,9 @@ Date: April 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		opmode. This holds the regulator operating mode setting.

		Some regulator directories will contain a field called

		opmode. This holds the current regulator operating mode,

		for regulators which can report it.



		The opmode value can be one of the following strings:
@@ -92,7 +97,7 @@ Description: 
		'standby'

		'unknown'



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

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



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

		output operating mode as this value is the same regardless of
@@ -104,9 +109,10 @@ Date: April 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories will contain a field called

		min_microvolts. This holds the minimum safe working regulator

		output voltage setting for this domain measured in microvolts.

		output voltage setting for this domain measured in microvolts,

		for regulators which support voltage constraints.



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

		the power domain has no min microvolts constraint defined by
@@ -118,9 +124,10 @@ Date: April 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories will contain a field called

		max_microvolts. This holds the maximum safe working regulator

		output voltage setting for this domain measured in microvolts.

		output voltage setting for this domain measured in microvolts,

		for regulators which support voltage constraints.



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

		the power domain has no max microvolts constraint defined by
@@ -132,10 +139,10 @@ Date: April 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories will contain a field called

		min_microamps. This holds the minimum safe working regulator

		output current limit setting for this domain measured in

		microamps.

		microamps, for regulators which support current constraints.



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

		the power domain has no min microamps constraint defined by
@@ -147,10 +154,10 @@ Date: April 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories will contain a field called

		max_microamps. This holds the maximum safe working regulator

		output current limit setting for this domain measured in

		microamps.

		microamps, for regulators which support current constraints.



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

		the power domain has no max microamps constraint defined by
@@ -185,7 +192,7 @@ Date: April 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories will contain a field called

		requested_microamps. This holds the total requested load

		current in microamps for this regulator from all its consumer

		devices.
@@ -204,125 +211,102 @@ Date: May 2008 
KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories 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.

		the system is suspended to memory, for voltage regulators

		implementing suspend voltage configuration constraints.



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

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories 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.

		the system is suspended to disk, for voltage regulators

		implementing suspend voltage configuration constraints.



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

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories 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.

		the system is suspended to standby, for voltage regulators

		implementing suspend voltage configuration constraints.



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

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories 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.

		memory, for regulators implementing suspend mode

		configuration constraints.



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

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories 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.

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

		for regulators implementing suspend mode configuration

		constraints.



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

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories 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.

		standby, for regulators implementing suspend mode

		configuration constraints.



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

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories 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:

		when suspended to memory, for regulators implementing suspend

		configuration constraints.



		'enabled'

		'disabled'

		'not defined'

		This will be one of the same strings reported by

		the "state" attribute.



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

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories 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:

		when suspended to disk, for regulators implementing

		suspend configuration constraints.



		'enabled'

		'disabled'

		'not defined'

		This will be one of the same strings reported by

		the "state" attribute.



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

Date:		May 2008

KernelVersion:	2.6.26

Contact:	Liam Girdwood <lrg@slimlogic.co.uk>

Description:

		Each regulator directory will contain a field called

		Some regulator directories 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:

		state when suspended to standby, for regulators implementing

		suspend configuration constraints.



		'enabled'

		'disabled'

		'not defined'
 
		This will be one of the same strings reported by

		the "state" attribute.

Documentation/DocBook/Makefile

+1 −1
Original line number Diff line number Diff line
@@ -12,7 +12,7 @@ DOCBOOKS := z8530book.xml mcabook.xml \ 
	    kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \

	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \

	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \

	    mac80211.xml debugobjects.xml sh.xml

	    mac80211.xml debugobjects.xml sh.xml regulator.xml



###

# The build process is as follows (targets):

Documentation/DocBook/regulator.tmpl

0 → 100644
+304 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>



<book id="regulator-api">

 <bookinfo>

  <title>Voltage and current regulator API</title>



  <authorgroup>

   <author>

    <firstname>Liam</firstname>

    <surname>Girdwood</surname>

    <affiliation>

     <address>

      <email>lrg@slimlogic.co.uk</email>

     </address>

    </affiliation>

   </author>

   <author>

    <firstname>Mark</firstname>

    <surname>Brown</surname>

    <affiliation>

     <orgname>Wolfson Microelectronics</orgname>

     <address>

      <email>broonie@opensource.wolfsonmicro.com</email>

     </address>

    </affiliation>

   </author>

  </authorgroup>



  <copyright>

   <year>2007-2008</year>

   <holder>Wolfson Microelectronics</holder>

  </copyright>

  <copyright>

   <year>2008</year>

   <holder>Liam Girdwood</holder>

  </copyright>



  <legalnotice>

   <para>

     This documentation is free software; you can redistribute

     it and/or modify it under the terms of the GNU General Public

     License version 2 as published by the Free Software Foundation.

   </para>



   <para>

     This program is distributed in the hope that it will be

     useful, but WITHOUT ANY WARRANTY; without even the implied

     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

     See the GNU General Public License for more details.

   </para>



   <para>

     You should have received a copy of the GNU General Public

     License along with this program; if not, write to the Free

     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,

     MA 02111-1307 USA

   </para>



   <para>

     For more details see the file COPYING in the source

     distribution of Linux.

   </para>

  </legalnotice>

 </bookinfo>



<toc></toc>



  <chapter id="intro">

    <title>Introduction</title>

    <para>

	This framework is designed to provide a standard kernel

	interface to control voltage and current regulators.

    </para>

    <para>

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

    </para>

    <para>

	Note that additional (and currently more complete) documentation

	is available in the Linux kernel source under

	<filename>Documentation/power/regulator</filename>.

    </para>



    <sect1 id="glossary">

       <title>Glossary</title>

       <para>

	The regulator API uses a number of terms which may not be

	familiar:

       </para>

       <glossary>



         <glossentry>

	   <glossterm>Regulator</glossterm>

	   <glossdef>

	     <para>

	Electronic device that supplies power to other devices.  Most

	regulators can enable and disable their output and some can also

	control their output voltage or current.

	     </para>

	   </glossdef>

         </glossentry>



	 <glossentry>

	   <glossterm>Consumer</glossterm>

	   <glossdef>

	     <para>

	Electronic device which consumes power provided by a regulator.

	These may either be static, requiring only a fixed supply, or

	dynamic, requiring active management of the regulator at

	runtime.

	     </para>

	   </glossdef>

	 </glossentry>



	 <glossentry>

	   <glossterm>Power Domain</glossterm>

	   <glossdef>

	     <para>

	The electronic circuit supplied by a given regulator, including

	the regulator and all consumer devices.  The configuration of

	the regulator is shared between all the components in the

	circuit.

	     </para>

	   </glossdef>

	 </glossentry>



	 <glossentry>

	   <glossterm>Power Management Integrated Circuit</glossterm>

	   <acronym>PMIC</acronym>

	   <glossdef>

	     <para>

	An IC which contains numerous regulators and often also other

	subsystems.  In an embedded system the primary PMIC is often

	equivalent to a combination of the PSU and southbridge in a

	desktop system.

	     </para>

	   </glossdef>

	 </glossentry>

	</glossary>

     </sect1>

  </chapter>



  <chapter id="consumer">

     <title>Consumer driver interface</title>

     <para>

       This offers a similar API to the kernel clock framework.

       Consumer drivers use <link

       linkend='API-regulator-get'>get</link> and <link

       linkend='API-regulator-put'>put</link> operations to acquire and

       release regulators.  Functions are

       provided to <link linkend='API-regulator-enable'>enable</link>

       and <link linkend='API-regulator-disable'>disable</link> the

       reguator and to get and set the runtime parameters of the

       regulator.

     </para>

     <para>

       When requesting regulators consumers use symbolic names for their

       supplies, such as "Vcc", which are mapped into actual regulator

       devices by the machine interface.

     </para>

     <para>

	A stub version of this API is provided when the regulator

	framework is not in use in order to minimise the need to use

	ifdefs.

     </para>



     <sect1 id="consumer-enable">

       <title>Enabling and disabling</title>

       <para>

         The regulator API provides reference counted enabling and

	 disabling of regulators. Consumer devices use the <function><link

	 linkend='API-regulator-enable'>regulator_enable</link></function>

	 and <function><link

	 linkend='API-regulator-disable'>regulator_disable</link>

	 </function> functions to enable and disable regulators.  Calls

	 to the two functions must be balanced.

       </para>

       <para>

         Note that since multiple consumers may be using a regulator and

	 machine constraints may not allow the regulator to be disabled

	 there is no guarantee that calling

	 <function>regulator_disable</function> will actually cause the

	 supply provided by the regulator to be disabled. Consumer

	 drivers should assume that the regulator may be enabled at all

	 times.

       </para>

     </sect1>



     <sect1 id="consumer-config">

       <title>Configuration</title>

       <para>

         Some consumer devices may need to be able to dynamically

	 configure their supplies.  For example, MMC drivers may need to

	 select the correct operating voltage for their cards.  This may

	 be done while the regulator is enabled or disabled.

       </para>

       <para>

	 The <function><link

	 linkend='API-regulator-set-voltage'>regulator_set_voltage</link>

	 </function> and <function><link

	 linkend='API-regulator-set-current-limit'

	 >regulator_set_current_limit</link>

	 </function> functions provide the primary interface for this.

	 Both take ranges of voltages and currents, supporting drivers

	 that do not require a specific value (eg, CPU frequency scaling

	 normally permits the CPU to use a wider range of supply

	 voltages at lower frequencies but does not require that the

	 supply voltage be lowered).  Where an exact value is required

	 both minimum and maximum values should be identical.

       </para>

     </sect1>



     <sect1 id="consumer-callback">

       <title>Callbacks</title>

       <para>

	  Callbacks may also be <link

	  linkend='API-regulator-register-notifier'>registered</link>

	  for events such as regulation failures.

       </para>

     </sect1>

   </chapter>



   <chapter id="driver">

     <title>Regulator driver interface</title>

     <para>

       Drivers for regulator chips <link

       linkend='API-regulator-register'>register</link> the regulators

       with the regulator core, providing operations structures to the

       core.  A <link

       linkend='API-regulator-notifier-call-chain'>notifier</link> interface

       allows error conditions to be reported to the core.

     </para>

     <para>

       Registration should be triggered by explicit setup done by the

       platform, supplying a <link

       linkend='API-struct-regulator-init-data'>struct

       regulator_init_data</link> for the regulator containing

       <link linkend='machine-constraint'>constraint</link> and

       <link linkend='machine-supply'>supply</link> information.

     </para>

   </chapter>



   <chapter id="machine">

     <title>Machine interface</title>

     <para>

       This interface provides a way to define how regulators are

       connected to consumers on a given system and what the valid

       operating parameters are for the system.

     </para>



     <sect1 id="machine-supply">

       <title>Supplies</title>

       <para>

         Regulator supplies are specified using <link

	 linkend='API-struct-regulator-consumer-supply'>struct

	 regulator_consumer_supply</link>.  This is done at

	 <link linkend='driver'>driver registration

	 time</link> as part of the machine constraints.

       </para>

     </sect1>



     <sect1 id="machine-constraint">

       <title>Constraints</title>

       <para>

	 As well as definining the connections the machine interface

	 also provides constraints definining the operations that

	 clients are allowed to perform and the parameters that may be

	 set.  This is required since generally regulator devices will

	 offer more flexibility than it is safe to use on a given

	 system, for example supporting higher supply voltages than the

	 consumers are rated for.

       </para>

       <para>

	 This is done at <link linkend='driver'>driver

	 registration time</link> by providing a <link

	 linkend='API-struct-regulation-constraints'>struct

	 regulation_constraints</link>.

       </para>

       <para>

         The constraints may also specify an initial configuration for the

         regulator in the constraints, which is particularly useful for

         use with static consumers.

       </para>

     </sect1>

  </chapter>



  <chapter id="api">

    <title>API reference</title>

    <para>

      Due to limitations of the kernel documentation framework and the

      existing layout of the source code the entire regulator API is

      documented here.

    </para>

!Iinclude/linux/regulator/consumer.h

!Iinclude/linux/regulator/machine.h

!Iinclude/linux/regulator/driver.h

!Edrivers/regulator/core.c

  </chapter>

</book>

drivers/Makefile

+3 −1
Original line number Diff line number Diff line
@@ -18,6 +18,9 @@ obj-$(CONFIG_ARM_AMBA) += amba/ 


obj-$(CONFIG_XEN)		+= xen/



# regulators early, since some subsystems rely on them to initialize

obj-$(CONFIG_REGULATOR)		+= regulator/



# char/ comes before serial/ etc so that the VT console is the boot-time

# default.

obj-y				+= char/
@@ -101,5 +104,4 @@ obj-$(CONFIG_PPC_PS3) += ps3/ 
obj-$(CONFIG_OF)		+= of/

obj-$(CONFIG_SSB)		+= ssb/

obj-$(CONFIG_VIRTIO)		+= virtio/

obj-$(CONFIG_REGULATOR)		+= regulator/

obj-$(CONFIG_STAGING)		+= staging/

drivers/regulator/core.c

+291 −183

File changed.

Preview size limit exceeded, changes collapsed.

CRA Git | Maintained and supported by SUSTech CRA and CCSE