UIO: Documentation for UIO ioport info handling

This patch updates UIO documentation with the changes introduced by
previous UIO patch.

Signed-off-by: Hans J. Koch <hjk@linutronix.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl
index df87d1b93605ac54cf400bd7b8d44b0866d0789a..6116b93608df87246b30a845a37da3a86c1883ce 100644 (file)
--- a/Documentation/DocBook/uio-howto.tmpl
+++ b/Documentation/DocBook/uio-howto.tmpl
@@ -41,6 +41,12 @@ GPL version 2.
 </abstract>
 
 <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>
@@ -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>
 
@@ -355,6 +409,13 @@ mapping you need to fill one of the <varname>uio_mem</varname> structures.
 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
@@ -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">