aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/uio-howto.tmpl
diff options
context:
space:
mode:
authorHans J. Koch <hjk@linutronix.de>2008-12-05 20:25:13 -0500
committerGreg Kroah-Hartman <gregkh@suse.de>2009-01-06 13:44:44 -0500
commita2ab3d30005cdce45c2c7e31ad6743ad7975609a (patch)
tree6f82b66bd7145401b187ab9cff7a078b894d639b /Documentation/DocBook/uio-howto.tmpl
parente70c412ee45332db2636a8f5a35a0685efb0e4aa (diff)
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>
Diffstat (limited to 'Documentation/DocBook/uio-howto.tmpl')
-rw-r--r--Documentation/DocBook/uio-howto.tmpl97
1 files changed, 97 insertions, 0 deletions
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl
index df87d1b93605..6116b93608df 100644
--- a/Documentation/DocBook/uio-howto.tmpl
+++ b/Documentation/DocBook/uio-howto.tmpl
@@ -42,6 +42,12 @@ GPL version 2.
42 42
43<revhistory> 43<revhistory>
44 <revision> 44 <revision>
45 <revnumber>0.6</revnumber>
46 <date>2008-12-05</date>
47 <authorinitials>hjk</authorinitials>
48 <revremark>Added description of portio sysfs attributes.</revremark>
49 </revision>
50 <revision>
45 <revnumber>0.5</revnumber> 51 <revnumber>0.5</revnumber>
46 <date>2008-05-22</date> 52 <date>2008-05-22</date>
47 <authorinitials>hjk</authorinitials> 53 <authorinitials>hjk</authorinitials>
@@ -318,6 +324,54 @@ interested in translating it, please email me
318offset = N * getpagesize(); 324offset = N * getpagesize();
319</programlisting> 325</programlisting>
320 326
327<para>
328 Sometimes there is hardware with memory-like regions that can not be
329 mapped with the technique described here, but there are still ways to
330 access them from userspace. The most common example are x86 ioports.
331 On x86 systems, userspace can access these ioports using
332 <function>ioperm()</function>, <function>iopl()</function>,
333 <function>inb()</function>, <function>outb()</function>, and similar
334 functions.
335</para>
336<para>
337 Since these ioport regions can not be mapped, they will not appear under
338 <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory
339 described above. Without information about the port regions a hardware
340 has to offer, it becomes difficult for the userspace part of the
341 driver to find out which ports belong to which UIO device.
342</para>
343<para>
344 To address this situation, the new directory
345 <filename>/sys/class/uio/uioX/portio/</filename> was added. It only
346 exists if the driver wants to pass information about one or more port
347 regions to userspace. If that is the case, subdirectories named
348 <filename>port0</filename>, <filename>port1</filename>, and so on,
349 will appear underneath
350 <filename>/sys/class/uio/uioX/portio/</filename>.
351</para>
352<para>
353 Each <filename>portX/</filename> directory contains three read-only
354 files that show start, size, and type of the port region:
355</para>
356<itemizedlist>
357<listitem>
358 <para>
359 <filename>start</filename>: The first port of this region.
360 </para>
361</listitem>
362<listitem>
363 <para>
364 <filename>size</filename>: The number of ports in this region.
365 </para>
366</listitem>
367<listitem>
368 <para>
369 <filename>porttype</filename>: A string describing the type of port.
370 </para>
371</listitem>
372</itemizedlist>
373
374
321</sect1> 375</sect1>
322</chapter> 376</chapter>
323 377
@@ -356,6 +410,13 @@ See the description below for details.
356</para></listitem> 410</para></listitem>
357 411
358<listitem><para> 412<listitem><para>
413<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required
414if you want to pass information about ioports to userspace. For each port
415region you need to fill one of the <varname>uio_port</varname> structures.
416See the description below for details.
417</para></listitem>
418
419<listitem><para>
359<varname>long irq</varname>: Required. If your hardware generates an 420<varname>long irq</varname>: Required. If your hardware generates an
360interrupt, it's your modules task to determine the irq number during 421interrupt, it's your modules task to determine the irq number during
361initialization. If you don't have a hardware generated interrupt but 422initialization. If you don't have a hardware generated interrupt but
@@ -448,6 +509,42 @@ Please do not touch the <varname>kobj</varname> element of
448<varname>struct uio_mem</varname>! It is used by the UIO framework 509<varname>struct uio_mem</varname>! It is used by the UIO framework
449to set up sysfs files for this mapping. Simply leave it alone. 510to set up sysfs files for this mapping. Simply leave it alone.
450</para> 511</para>
512
513<para>
514Sometimes, your device can have one or more port regions which can not be
515mapped to userspace. But if there are other possibilities for userspace to
516access these ports, it makes sense to make information about the ports
517available in sysfs. For each region, you have to set up a
518<varname>struct uio_port</varname> in the <varname>port[]</varname> array.
519Here's a description of the fields of <varname>struct uio_port</varname>:
520</para>
521
522<itemizedlist>
523<listitem><para>
524<varname>char *porttype</varname>: Required. Set this to one of the predefined
525constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86
526architectures.
527</para></listitem>
528
529<listitem><para>
530<varname>unsigned long start</varname>: Required if the port region is used.
531Fill in the number of the first port of this region.
532</para></listitem>
533
534<listitem><para>
535<varname>unsigned long size</varname>: Fill in the number of ports in this
536region. If <varname>size</varname> is zero, the region is considered unused.
537Note that you <emphasis>must</emphasis> initialize <varname>size</varname>
538with zero for all unused regions.
539</para></listitem>
540</itemizedlist>
541
542<para>
543Please do not touch the <varname>portio</varname> element of
544<varname>struct uio_port</varname>! It is used internally by the UIO
545framework to set up sysfs files for this region. Simply leave it alone.
546</para>
547
451</sect1> 548</sect1>
452 549
453<sect1 id="adding_irq_handler"> 550<sect1 id="adding_irq_handler">