diff options
Diffstat (limited to 'Documentation/DocBook')
| -rw-r--r-- | Documentation/DocBook/Makefile | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/networking.tmpl | 8 | ||||
| -rw-r--r-- | Documentation/DocBook/regulator.tmpl | 304 | ||||
| -rw-r--r-- | Documentation/DocBook/uio-howto.tmpl | 101 |
4 files changed, 412 insertions, 3 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 0a08126d309..dc3154e4927 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -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): diff --git a/Documentation/DocBook/networking.tmpl b/Documentation/DocBook/networking.tmpl index 627707a3cb9..59ad69a9d77 100644 --- a/Documentation/DocBook/networking.tmpl +++ b/Documentation/DocBook/networking.tmpl @@ -74,6 +74,14 @@ !Enet/sunrpc/rpcb_clnt.c !Enet/sunrpc/clnt.c </sect1> + <sect1><title>WiMAX</title> +!Enet/wimax/op-msg.c +!Enet/wimax/op-reset.c +!Enet/wimax/op-rfkill.c +!Enet/wimax/stack.c +!Iinclude/net/wimax.h +!Iinclude/linux/wimax.h + </sect1> </chapter> <chapter id="netdev"> diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl new file mode 100644 index 00000000000..53f4f8d3b81 --- /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> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index df87d1b9360..b787e4721c9 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -42,6 +42,12 @@ GPL version 2. <revhistory> <revision> + <revnumber>0.6</revnumber> + <date>2008-12-05</date> + <authorinitials>hjk</authorinitials> + <revremark>Added description of portio sysfs attributes.</revremark> + </revision> + <revision> <revnumber>0.5</revnumber> <date>2008-05-22</date> <authorinitials>hjk</authorinitials> @@ -318,6 +324,54 @@ interested in translating it, please email me offset = N * getpagesize(); </programlisting> +<para> + Sometimes there is hardware with memory-like regions that can not be + mapped with the technique described here, but there are still ways to + access them from userspace. The most common example are x86 ioports. + On x86 systems, userspace can access these ioports using + <function>ioperm()</function>, <function>iopl()</function>, + <function>inb()</function>, <function>outb()</function>, and similar + functions. +</para> +<para> + Since these ioport regions can not be mapped, they will not appear under + <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory + described above. Without information about the port regions a hardware + has to offer, it becomes difficult for the userspace part of the + driver to find out which ports belong to which UIO device. +</para> +<para> + To address this situation, the new directory + <filename>/sys/class/uio/uioX/portio/</filename> was added. It only + exists if the driver wants to pass information about one or more port + regions to userspace. If that is the case, subdirectories named + <filename>port0</filename>, <filename>port1</filename>, and so on, + will appear underneath + <filename>/sys/class/uio/uioX/portio/</filename>. +</para> +<para> + Each <filename>portX/</filename> directory contains three read-only + files that show start, size, and type of the port region: +</para> +<itemizedlist> +<listitem> + <para> + <filename>start</filename>: The first port of this region. + </para> +</listitem> +<listitem> + <para> + <filename>size</filename>: The number of ports in this region. + </para> +</listitem> +<listitem> + <para> + <filename>porttype</filename>: A string describing the type of port. + </para> +</listitem> +</itemizedlist> + + </sect1> </chapter> @@ -339,12 +393,12 @@ offset = N * getpagesize(); <itemizedlist> <listitem><para> -<varname>char *name</varname>: Required. The name of your driver as +<varname>const char *name</varname>: Required. The name of your driver as it will appear in sysfs. I recommend using the name of your module for this. </para></listitem> <listitem><para> -<varname>char *version</varname>: Required. This string appears in +<varname>const char *version</varname>: Required. This string appears in <filename>/sys/class/uio/uioX/version</filename>. </para></listitem> @@ -356,6 +410,13 @@ See the description below for details. </para></listitem> <listitem><para> +<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required +if you want to pass information about ioports to userspace. For each port +region you need to fill one of the <varname>uio_port</varname> structures. +See the description below for details. +</para></listitem> + +<listitem><para> <varname>long irq</varname>: Required. If your hardware generates an interrupt, it's your modules task to determine the irq number during initialization. If you don't have a hardware generated interrupt but @@ -448,6 +509,42 @@ Please do not touch the <varname>kobj</varname> element of <varname>struct uio_mem</varname>! It is used by the UIO framework to set up sysfs files for this mapping. Simply leave it alone. </para> + +<para> +Sometimes, your device can have one or more port regions which can not be +mapped to userspace. But if there are other possibilities for userspace to +access these ports, it makes sense to make information about the ports +available in sysfs. For each region, you have to set up a +<varname>struct uio_port</varname> in the <varname>port[]</varname> array. +Here's a description of the fields of <varname>struct uio_port</varname>: +</para> + +<itemizedlist> +<listitem><para> +<varname>char *porttype</varname>: Required. Set this to one of the predefined +constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86 +architectures. +</para></listitem> + +<listitem><para> +<varname>unsigned long start</varname>: Required if the port region is used. +Fill in the number of the first port of this region. +</para></listitem> + +<listitem><para> +<varname>unsigned long size</varname>: Fill in the number of ports in this +region. If <varname>size</varname> is zero, the region is considered unused. +Note that you <emphasis>must</emphasis> initialize <varname>size</varname> +with zero for all unused regions. +</para></listitem> +</itemizedlist> + +<para> +Please do not touch the <varname>portio</varname> element of +<varname>struct uio_port</varname>! It is used internally by the UIO +framework to set up sysfs files for this region. Simply leave it alone. +</para> + </sect1> <sect1 id="adding_irq_handler"> |