Messages in this thread | | | Date | Mon, 22 Dec 2008 11:03:32 -0800 | From | Randy Dunlap <> | Subject | Re: [PATCH 2/2] UIO: Documentation for UIO ioport info handling |
| |
On Sat, 6 Dec 2008 02:25:13 +0100 Hans J. Koch wrote:
> This patch updates UIO documentation with the changes introduced by > PATCH 1/2. > > Signed-off-by: Hans J. Koch <hjk@linutronix.de> > > --- > Documentation/DocBook/uio-howto.tmpl | 97 +++++++++++++++++++++++++++++++++++ > 1 file changed, 97 insertions(+) > > Index: linux-2.6.28-rc/Documentation/DocBook/uio-howto.tmpl > =================================================================== > --- linux-2.6.28-rc.orig/Documentation/DocBook/uio-howto.tmpl 2008-12-06 01:13:56.000000000 +0100 > +++ linux-2.6.28-rc/Documentation/DocBook/uio-howto.tmpl 2008-12-06 01:54:14.000000000 +0100 > @@ -42,6 +42,12 @@ > > <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 @@ > offset = N * getpagesize(); > </programlisting> > > +<para> > + Sometimes there is hardware with memory-like regions that can not be
cannot
> + 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
ditto
> + <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> > > @@ -356,6 +410,13 @@ > </para></listitem> > > <listitem><para> > +<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required
odd spacing: port[ MAX_UIO_PORTS_REGIONS ]
> +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 @@ > <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
cannot
> +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">
--- ~Randy
| |