Re: [PATCH 2/2] UIO: Documentation for UIO ioport info handling

Randy Dunlap
2008-12-22T19:04:16Z

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>
>
> +
> + 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.
> +
> +
> + 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.
> +
> +
> + 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>.
> +
> +
> + Each <filename>portX/</filename> directory contains three read-only
> + files that show start, size, and type of the port region:
> +
> +
> +
> +
> + <filename>start</filename>: The first port of this region.
> +
> +
> +
> +
> + <filename>size</filename>: The number of ports in this region.
> +
> +
> +
> +
> + <filename>porttype</filename>: A string describing the type of port.
> +
> +
> +
> +
> +
> </sect1>
> </chapter>
>
> @@ -356,6 +410,13 @@
>
>
>
> +<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.
> +
> +
> +
> <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.
>
> +
> +
> +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>:
> +
> +
> +
> +
> +<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.
> +
> +
> +
> +<varname>unsigned long start</varname>: Required if the port region is used.
> +Fill in the number of the first port of this region.
> +
> +
> +
> +<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 must initialize <varname>size</varname>
> +with zero for all unused regions.
> +
> +
> +
> +
> +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.
> +
> +
> </sect1>
>
> <sect1 id="adding_irq_handler">

---
~Randy