diff options
author | Hans J. Koch <hjk@linutronix.de> | 2008-12-05 20:25:13 -0500 |
---|---|---|
committer | Greg Kroah-Hartman <gregkh@suse.de> | 2009-01-06 13:44:44 -0500 |
commit | a2ab3d30005cdce45c2c7e31ad6743ad7975609a (patch) | |
tree | 6f82b66bd7145401b187ab9cff7a078b894d639b /Documentation/DocBook/uio-howto.tmpl | |
parent | e70c412ee45332db2636a8f5a35a0685efb0e4aa (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.tmpl | 97 |
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 | |||
318 | offset = N * getpagesize(); | 324 | offset = 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 | ||
414 | if you want to pass information about ioports to userspace. For each port | ||
415 | region you need to fill one of the <varname>uio_port</varname> structures. | ||
416 | See 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 |
360 | interrupt, it's your modules task to determine the irq number during | 421 | interrupt, it's your modules task to determine the irq number during |
361 | initialization. If you don't have a hardware generated interrupt but | 422 | 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 | |||
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 |
449 | to set up sysfs files for this mapping. Simply leave it alone. | 510 | to set up sysfs files for this mapping. Simply leave it alone. |
450 | </para> | 511 | </para> |
512 | |||
513 | <para> | ||
514 | Sometimes, your device can have one or more port regions which can not be | ||
515 | mapped to userspace. But if there are other possibilities for userspace to | ||
516 | access these ports, it makes sense to make information about the ports | ||
517 | available in sysfs. For each region, you have to set up a | ||
518 | <varname>struct uio_port</varname> in the <varname>port[]</varname> array. | ||
519 | Here'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 | ||
525 | constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86 | ||
526 | architectures. | ||
527 | </para></listitem> | ||
528 | |||
529 | <listitem><para> | ||
530 | <varname>unsigned long start</varname>: Required if the port region is used. | ||
531 | Fill 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 | ||
536 | region. If <varname>size</varname> is zero, the region is considered unused. | ||
537 | Note that you <emphasis>must</emphasis> initialize <varname>size</varname> | ||
538 | with zero for all unused regions. | ||
539 | </para></listitem> | ||
540 | </itemizedlist> | ||
541 | |||
542 | <para> | ||
543 | Please do not touch the <varname>portio</varname> element of | ||
544 | <varname>struct uio_port</varname>! It is used internally by the UIO | ||
545 | framework 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"> |