From hjk@linutronix.de Tue Dec 9 20:34:03 2008 From: "Hans J. Koch" Date: Sat, 6 Dec 2008 02:25:13 +0100 Subject: UIO: Documentation for UIO ioport info handling Cc: gregkh@suse.de, Mike Frysinger , John Ogness , Benedikt Spranger Message-ID: <20081206012513.GC3081@local> Content-Disposition: inline This patch updates UIO documentation with the changes introduced by previous UIO patch. Signed-off-by: Hans J. Koch Signed-off-by: Greg Kroah-Hartman --- Documentation/DocBook/uio-howto.tmpl | 97 +++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -42,6 +42,12 @@ GPL version 2. + 0.6 + 2008-12-05 + hjk + Added description of portio sysfs attributes. + + 0.5 2008-05-22 hjk @@ -318,6 +324,54 @@ interested in translating it, please ema offset = N * getpagesize(); + + 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 + ioperm(), iopl(), + inb(), outb(), and similar + functions. + + + Since these ioport regions can not be mapped, they will not appear under + /sys/class/uio/uioX/maps/ 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 + /sys/class/uio/uioX/portio/ 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 + port0, port1, and so on, + will appear underneath + /sys/class/uio/uioX/portio/. + + + Each portX/ directory contains three read-only + files that show start, size, and type of the port region: + + + + + start: The first port of this region. + + + + + size: The number of ports in this region. + + + + + porttype: A string describing the type of port. + + + + + @@ -356,6 +410,13 @@ See the description below for details. +struct uio_port port[ MAX_UIO_PORTS_REGIONS ]: Required +if you want to pass information about ioports to userspace. For each port +region you need to fill one of the uio_port structures. +See the description below for details. + + + long irq: 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 @@ Please do not touch the kobjstruct uio_mem! 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 +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 +struct uio_port in the port[] array. +Here's a description of the fields of struct uio_port: + + + + +char *porttype: Required. Set this to one of the predefined +constants. Use UIO_PORT_X86 for the ioports found in x86 +architectures. + + + +unsigned long start: Required if the port region is used. +Fill in the number of the first port of this region. + + + +unsigned long size: Fill in the number of ports in this +region. If size is zero, the region is considered unused. +Note that you must initialize size +with zero for all unused regions. + + + + +Please do not touch the portio element of +struct uio_port! It is used internally by the UIO +framework to set up sysfs files for this region. Simply leave it alone. + +