[PATCH 0/5] regulator: kerneldoc cleanups

[PATCH 0/5] regulator: kerneldoc cleanups

[Mark Brown]

This patch series cleans up the kerneldoc for the regulator API and adds
a brief DocBook manual for it, based heavily on the existing plain text
documentation but much less complete.  I'm not sure that the manual
itself is actually worthwhile, the main benefit from it is the generated 
documentation rather than the text in the manual itself - I did the work
to help with generating the earlier fixes.

It may be worth considering the first four patches for 2.6.29 as fixes,
though it's questionable.

The following changes since commit b6fe1c783638104350147877f5823d8faa68f6a2:
  David Brownell (1):
        regulator: init/link earlier

are available in the git repository at:

  git://git.kernel.org/pub/scm/linux/kernel/git/broonie/regulator-2.6.git topic/doc

Mark Brown (5):
      regulator: Remove extraneous kerneldoc annotations
      regulator: Clean up kerneldoc warnings
      regulator: Add missing kerneldoc
      regulator: Fix some kerneldoc rendering issues
      regulator: Add basic DocBook manual

 Documentation/DocBook/Makefile       |    2 +-
 Documentation/DocBook/regulator.tmpl |  304 ++++++++++++++++++++++++++++++++++
 drivers/regulator/core.c             |   57 ++++---
 include/linux/regulator/consumer.h   |    8 +-
 include/linux/regulator/driver.h     |   40 +++++-
 include/linux/regulator/machine.h    |   41 +++++
 6 files changed, 420 insertions(+), 32 deletions(-)
 create mode 100644 Documentation/DocBook/regulator.tmpl

[PATCH 1/5] regulator: Remove extraneous kerneldoc annotations

[Mark Brown]

Some of the internal structures have no kerneldoc but the ** at the start
of the comment marking them for documentation.  Remove the annotation
until some is added.

Signed-off-by: Mark Brown <broonie@opensource.wolfsonmicro.com>
---
 drivers/regulator/core.c |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c
index 895f738..7ba9491 100644
--- a/drivers/regulator/core.c
+++ b/drivers/regulator/core.c
@@ -29,7 +29,7 @@ static DEFINE_MUTEX(regulator_list_mutex);
 static LIST_HEAD(regulator_list);
 static LIST_HEAD(regulator_map_list);
 
-/**
+/*
  * struct regulator_dev
  *
  * Voltage / Current regulator class device. One for each regulator.
@@ -56,7 +56,7 @@ struct regulator_dev {
 	void *reg_data;		/* regulator_dev data */
 };
 
-/**
+/*
  * struct regulator_map
  *
  * Used to provide symbolic supply names to devices.
-- 
1.5.6.3

[PATCH 2/5] regulator: Clean up kerneldoc warnings

[Mark Brown]

Remove kerneldoc warnings that don't relate to missing documentation,
mostly by renaming parameters in the documentation to match their
actual names.

Signed-off-by: Mark Brown <broonie@opensource.wolfsonmicro.com>
---
 drivers/regulator/core.c           |   44 ++++++++++++++++++------------------
 include/linux/regulator/consumer.h |    8 +++---
 2 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c
index 7ba9491..ea12c68 100644
--- a/drivers/regulator/core.c
+++ b/drivers/regulator/core.c
@@ -655,7 +655,7 @@ static void print_constraints(struct regulator_dev *rdev)
 
 /**
  * set_machine_constraints - sets regulator constraints
- * @regulator: regulator source
+ * @rdev: regulator source
  *
  * Allows platform initialisation code to define and constrain
  * regulator circuits e.g. valid voltage/current ranges, etc.  NOTE:
@@ -730,8 +730,8 @@ out:
 
 /**
  * set_supply - set regulator supply regulator
- * @regulator: regulator name
- * @supply: supply regulator name
+ * @rdev: regulator name
+ * @supply_rdev: supply regulator name
  *
  * Called by platform initialisation code to set the supply regulator for this
  * regulator. This ensures that a regulators supply will also be enabled by the
@@ -758,9 +758,9 @@ out:
 
 /**
  * set_consumer_device_supply: Bind a regulator to a symbolic supply
- * @regulator: regulator source
- * @dev:       device the supply applies to
- * @supply:    symbolic name for supply
+ * @rdev:         regulator source
+ * @consumer_dev: device the supply applies to
+ * @supply:       symbolic name for supply
  *
  * Allows platform initialisation code to map physical regulator
  * sources to symbolic names for supplies for use by devices.  Devices
@@ -1013,9 +1013,8 @@ static int _regulator_enable(struct regulator_dev *rdev)
  *
  * Enable the regulator output at the predefined voltage or current value.
  * NOTE: the output value can be set by other drivers, boot loader or may be
- * hardwired in the regulator.
- * NOTE: calls to regulator_enable() must be balanced with calls to
- * regulator_disable().
+ * hardwired in the regulator.  Calls to regulator_enable() must be balanced
+ * with calls to regulator_disable().
  */
 int regulator_enable(struct regulator *regulator)
 {
@@ -1074,10 +1073,10 @@ static int _regulator_disable(struct regulator_dev *rdev)
  * @regulator: regulator source
  *
  * Disable the regulator output voltage or current.
+ *
  * NOTE: this will only disable the regulator output if no other consumer
- * devices have it enabled.
- * NOTE: calls to regulator_enable() must be balanced with calls to
- * regulator_disable().
+ * devices have it enabled.  Calls to regulator_enable() must be balanced with
+ * calls to regulator_disable().
  */
 int regulator_disable(struct regulator *regulator)
 {
@@ -1200,7 +1199,7 @@ EXPORT_SYMBOL_GPL(regulator_is_enabled);
  *
  * NOTE: If the regulator is shared between several devices then the lowest
  * request voltage that meets the system constraints will be used.
- * NOTE: Regulator system constraints must be set for this regulator before
+ * Regulator system constraints must be set for this regulator before
  * calling this function otherwise this call will fail.
  */
 int regulator_set_voltage(struct regulator *regulator, int min_uV, int max_uV)
@@ -1498,7 +1497,7 @@ EXPORT_SYMBOL_GPL(regulator_set_optimum_mode);
 /**
  * regulator_register_notifier - register regulator event notifier
  * @regulator: regulator source
- * @notifier_block: notifier block
+ * @nb: notifier block
  *
  * Register notifier block to receive regulator events.
  */
@@ -1513,7 +1512,7 @@ EXPORT_SYMBOL_GPL(regulator_register_notifier);
 /**
  * regulator_unregister_notifier - unregister regulator event notifier
  * @regulator: regulator source
- * @notifier_block: notifier block
+ * @nb: notifier block
  *
  * Unregister regulator event notifier block.
  */
@@ -1679,9 +1678,9 @@ EXPORT_SYMBOL_GPL(regulator_bulk_free);
 
 /**
  * regulator_notifier_call_chain - call regulator event notifier
- * @regulator: regulator source
+ * @rdev: regulator source
  * @event: notifier block
- * @data:
+ * @data: callback-specific data.
  *
  * Called by regulator drivers to notify clients a regulator event has
  * occurred. We also notify regulator clients downstream.
@@ -1808,8 +1807,9 @@ static int add_regulator_attributes(struct regulator_dev *rdev)
 
 /**
  * regulator_register - register regulator
- * @regulator: regulator source
- * @reg_data: private regulator data
+ * @regulator_desc: regulator to register
+ * @dev: struct device for the regulator
+ * @driver_data: private regulator data
  *
  * Called by regulator drivers to register a regulator.
  * Returns 0 on success.
@@ -1916,7 +1916,7 @@ EXPORT_SYMBOL_GPL(regulator_register);
 
 /**
  * regulator_unregister - unregister regulator
- * @regulator: regulator source
+ * @rdev: regulator to unregister
  *
  * Called by regulator drivers to unregister a regulator.
  */
@@ -1971,7 +1971,7 @@ EXPORT_SYMBOL_GPL(regulator_suspend_prepare);
 
 /**
  * rdev_get_drvdata - get rdev regulator driver data
- * @regulator: regulator
+ * @rdev: regulator
  *
  * Get rdev regulator driver private data. This call can be used in the
  * regulator driver context.
@@ -2008,7 +2008,7 @@ EXPORT_SYMBOL_GPL(regulator_set_drvdata);
 
 /**
  * regulator_get_id - get regulator ID
- * @regulator: regulator
+ * @rdev: regulator
  */
 int rdev_get_id(struct regulator_dev *rdev)
 {
diff --git a/include/linux/regulator/consumer.h b/include/linux/regulator/consumer.h
index afdc455..801bf77 100644
--- a/include/linux/regulator/consumer.h
+++ b/include/linux/regulator/consumer.h
@@ -104,10 +104,10 @@ struct regulator;
 /**
  * struct regulator_bulk_data - Data used for bulk regulator operations.
  *
- * @supply   The name of the supply.  Initialised by the user before
- *           using the bulk regulator APIs.
- * @consumer The regulator consumer for the supply.  This will be managed
- *           by the bulk API.
+ * @supply:   The name of the supply.  Initialised by the user before
+ *            using the bulk regulator APIs.
+ * @consumer: The regulator consumer for the supply.  This will be managed
+ *            by the bulk API.
  *
  * The regulator APIs provide a series of regulator_bulk_() API calls as
  * a convenience to consumers which require multiple supplies.  This
-- 
1.5.6.3

[PATCH 3/5] regulator: Add missing kerneldoc

[Mark Brown]

This is only the documentation that the kerneldoc system warns about.

Signed-off-by: Mark Brown <broonie@opensource.wolfsonmicro.com>
---
 drivers/regulator/core.c          |    1 +
 include/linux/regulator/driver.h  |   40 +++++++++++++++++++++++++++++++++++-
 include/linux/regulator/machine.h |   41 +++++++++++++++++++++++++++++++++++++
 3 files changed, 81 insertions(+), 1 deletions(-)

diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c
index ea12c68..fda4400 100644
--- a/drivers/regulator/core.c
+++ b/drivers/regulator/core.c
@@ -656,6 +656,7 @@ static void print_constraints(struct regulator_dev *rdev)
 /**
  * set_machine_constraints - sets regulator constraints
  * @rdev: regulator source
+ * @constraints: constraints to apply
  *
  * Allows platform initialisation code to define and constrain
  * regulator circuits e.g. valid voltage/current ranges, etc.  NOTE:
diff --git a/include/linux/regulator/driver.h b/include/linux/regulator/driver.h
index e37d805..84c3737 100644
--- a/include/linux/regulator/driver.h
+++ b/include/linux/regulator/driver.h
@@ -24,7 +24,37 @@ struct regulator_init_data;
 /**
  * struct regulator_ops - regulator operations.
  *
- * This struct describes regulator operations.
+ * This struct describes regulator operations which can be implemented by
+ * regulator chip drivers.
+ *
+ * @enable: Enable the regulator.
+ * @disable: Disable the regulator.
+ * @is_enabled: Return 1 if the reguator is enabled, 0 otherwise.
+ *
+ * @set_voltage: Set the voltage for the regulator within the range specified.
+ *               The driver should select the voltage closest to min_uV.
+ * @get_voltage: Return the currently configured voltage for the regulator.
+ *
+ * @set_current: Set the current for the regulator within the range specified.
+ *               The driver should select the current closest to min_uA.
+ * @get_current: Return the currently configured current for the regulator.
+ *
+ * @set_current_limit: Configure a limit for a current-limited regulator.
+ * @get_current_limit: Get the limit for a current-limited regulator.
+ *
+ * @set_mode: Set the operating mode for the regulator.
+ * @get_mode: Get the current operating mode for the regulator.
+ * @get_optimum_mode: Get the most efficient operating mode for the regulator
+ *                    when running with the specified parameters.
+ *
+ * @set_suspend_voltage: Set the voltage for the regulator when the system
+ *                       is suspended.
+ * @set_suspend_enable: Mark the regulator as enabled when the system is
+ *                      suspended.
+ * @set_suspend_disable: Mark the regulator as disabled when the system is
+ *                       suspended.
+ * @set_suspend_mode: Set the operating mode for the regulator when the
+ *                    system is suspended.
  */
 struct regulator_ops {
 
@@ -75,6 +105,14 @@ enum regulator_type {
 /**
  * struct regulator_desc - Regulator descriptor
  *
+ * Each regulator registered with the core is described with a structure of
+ * this type.
+ *
+ * @name: Identifying name for the regulator.
+ * @id: Numerical identifier for the regulator.
+ * @ops: Regulator operations table.
+ * @type: Indicates if the regulator is a voltage or current regulator.
+ * @owner: Module providing the regulator, used for refcounting.
  */
 struct regulator_desc {
 	const char *name;
diff --git a/include/linux/regulator/machine.h b/include/linux/regulator/machine.h
index c6d6933..3794773 100644
--- a/include/linux/regulator/machine.h
+++ b/include/linux/regulator/machine.h
@@ -44,6 +44,10 @@ struct regulator;
  * struct regulator_state - regulator state during low power syatem states
  *
  * This describes a regulators state during a system wide low power state.
+ *
+ * @uV: Operating voltage during suspend.
+ * @mode: Operating mode during suspend.
+ * @enabled: Enabled during suspend.
  */
 struct regulator_state {
 	int uV;	/* suspend voltage */
@@ -55,6 +59,30 @@ struct regulator_state {
  * struct regulation_constraints - regulator operating constraints.
  *
  * This struct describes regulator and board/machine specific constraints.
+ *
+ * @name: Descriptive name for the constraints, used for display purposes.
+ *
+ * @min_uV: Smallest voltage consumers may set.
+ * @max_uV: Largest voltage consumers may set.
+ *
+ * @min_uA: Smallest consumers consumers may set.
+ * @max_uA: Largest current consumers may set.
+ *
+ * @valid_modes_mask: Mask of modes which may be configured by consumers.
+ * @valid_ops_mask: Operations which may be performed by consumers.
+ *
+ * @always_on: Set if the regulator should never be disabled.
+ * @boot_on: Set if the regulator is enabled when the system is initially
+ *           started.
+ * @apply_uV: Apply the voltage constraint when initialising.
+ *
+ * @input_uV: Input voltage for regulator when supplied by another regulator.
+ *
+ * @state_disk: State for regulator when system is suspended in disk mode.
+ * @state_mem: State for regulator when system is suspended in mem mode.
+ * @state_standby: State for regulator when system is suspended in standby
+ *                 mode.
+ * @initial_state: Suspend state to set by default.
  */
 struct regulation_constraints {
 
@@ -93,6 +121,9 @@ struct regulation_constraints {
  * struct regulator_consumer_supply - supply -> device mapping
  *
  * This maps a supply name to a device.
+ *
+ * @dev: Device structure for the consumer.
+ * @supply: Name for the supply.
  */
 struct regulator_consumer_supply {
 	struct device *dev;	/* consumer */
@@ -103,6 +134,16 @@ struct regulator_consumer_supply {
  * struct regulator_init_data - regulator platform initialisation data.
  *
  * Initialisation constraints, our supply and consumers supplies.
+ *
+ * @supply_regulator_dev: Parent regulator (if any).
+ *
+ * @constraints: Constraints.  These must be specified for the regulator to
+ *               be usable.
+ * @num_consumer_supplies: Number of consumer device supplies.
+ * @consumer_supplies: Consumer device supply configuration.
+ *
+ * @regulator_init: Callback invoked when the regulator has been registered.
+ * @driver_data: Data passed to regulator_init.
  */
 struct regulator_init_data {
 	struct device *supply_regulator_dev; /* or NULL for LINE */
-- 
1.5.6.3

[PATCH 4/5] regulator: Fix some kerneldoc rendering issues

[Mark Brown]

There are some minor textual changes in here as well, mostly to enable()
and disable() but the primary goal of these changes is to fix
misrenderings of the kerneldoc documentation for the regulator API.

Signed-off-by: Mark Brown <broonie@opensource.wolfsonmicro.com>
---
 drivers/regulator/core.c |   18 +++++++++++-------
 1 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c
index fda4400..7341c97 100644
--- a/drivers/regulator/core.c
+++ b/drivers/regulator/core.c
@@ -1012,10 +1012,12 @@ static int _regulator_enable(struct regulator_dev *rdev)
  * regulator_enable - enable regulator output
  * @regulator: regulator source
  *
- * Enable the regulator output at the predefined voltage or current value.
+ * Request that the regulator be enabled with the regulator output at
+ * the predefined voltage or current value.  Calls to regulator_enable()
+ * must be balanced with calls to regulator_disable().
+ *
  * NOTE: the output value can be set by other drivers, boot loader or may be
- * hardwired in the regulator.  Calls to regulator_enable() must be balanced
- * with calls to regulator_disable().
+ * hardwired in the regulator.
  */
 int regulator_enable(struct regulator *regulator)
 {
@@ -1073,11 +1075,13 @@ static int _regulator_disable(struct regulator_dev *rdev)
  * regulator_disable - disable regulator output
  * @regulator: regulator source
  *
- * Disable the regulator output voltage or current.
+ * Disable the regulator output voltage or current.  Calls to
+ * regulator_enable() must be balanced with calls to
+ * regulator_disable().
  *
  * NOTE: this will only disable the regulator output if no other consumer
- * devices have it enabled.  Calls to regulator_enable() must be balanced with
- * calls to regulator_disable().
+ * devices have it enabled, the regulator device supports disabling and
+ * machine constraints permit this operation.
  */
 int regulator_disable(struct regulator *regulator)
 {
@@ -1936,7 +1940,7 @@ void regulator_unregister(struct regulator_dev *rdev)
 EXPORT_SYMBOL_GPL(regulator_unregister);
 
 /**
- * regulator_suspend_prepare: prepare regulators for system wide suspend
+ * regulator_suspend_prepare - prepare regulators for system wide suspend
  * @state: system suspend state
  *
  * Configure each regulator with it's suspend operating parameters for state.
-- 
1.5.6.3

[PATCH 5/5] regulator: Add basic DocBook manual

[Mark Brown]

Add a basic DocBook manual for the regulator API. This is much more
skeletal than the existing text documentation, the main benefit is to
provide a skeleton for automatic generation of a manual based on the
kerneldoc for the API.

Since large portions of the text are lifted from the existing text format
documentation written by Liam Girdwood much of the credit belongs to
him.

Signed-off-by: Mark Brown <broonie@opensource.wolfsonmicro.com>
---

As I said in the covering message for the series I'm not sure if this is
worthwhile or not - the plain text documentation is more complete, the
main purpose of this was to make it easier to generate the kerneldoc so
I could do the earlier parts of the series.

I'm also fairly hopeless at proofreading my own text.

 Documentation/DocBook/Makefile       |    2 +-
 Documentation/DocBook/regulator.tmpl |  304 ++++++++++++++++++++++++++++++++++
 2 files changed, 305 insertions(+), 1 deletions(-)
 create mode 100644 Documentation/DocBook/regulator.tmpl

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 9b1f6ca..4b29634 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -12,7 +12,7 @@ DOCBOOKS := wanbook.xml 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):
diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl
new file mode 100644
index 0000000..d70f9d0
--- /dev/null
+++ b/Documentation/DocBook/regulator.tmpl
@@ -0,0 +1,304 @@
+<?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>
-- 
1.5.6.3

Re: [PATCH 0/5] regulator: kerneldoc cleanups

[Liam Girdwood]

On Wed, 2008-12-31 at 12:51 +0000, Mark Brown wrote:
> This patch series cleans up the kerneldoc for the regulator API and adds
> a brief DocBook manual for it, based heavily on the existing plain text
> documentation but much less complete.  I'm not sure that the manual
> itself is actually worthwhile, the main benefit from it is the generated 
> documentation rather than the text in the manual itself - I did the work
> to help with generating the earlier fixes.
> 
> It may be worth considering the first four patches for 2.6.29 as fixes,
> though it's questionable.

Applied.

Thanks

Liam