From hjk@linutronix.de Tue Feb 20 14:40:27 2007 From: Hans-Jürgen Koch Date: Tue, 13 Feb 2007 15:01:48 +0100 Subject: UIO: update documentation for multiple mappings To: Greg KH Cc: tglx@linutronix.de, Benedikt Spranger Message-ID: <200702131501.49296.hjk@linutronix.de> here's a patch that updates the UIO docs. It adds the description of our new multiple mapping capabilities. Signed-off-by: Greg Kroah-Hartman --- Documentation/DocBook/uio-howto.tmpl | 140 +++++++++++++++++++++++++---------- 1 file changed, 102 insertions(+), 38 deletions(-) --- gregkh-2.6.orig/Documentation/DocBook/uio-howto.tmpl +++ gregkh-2.6/Documentation/DocBook/uio-howto.tmpl @@ -30,6 +30,12 @@ + 0.2 + 2007-02-13 + hjk + Update after multiple mappings were added. + + 0.1 2006-12-11 hjk @@ -76,12 +82,11 @@ interested in translating it, please ema like this are for industrial I/O cards. - To address this situation, and create the userspace I/O system - (UIO) was designed. For typical industrial I/O cards, only a - very small kernel module is needed. The main part of the - driver will run in user space. This simplifies development and - reduces the risk of serious bugs within a kernel - module. + To address this situation, the userspace I/O system (UIO) was + designed. For typical industrial I/O cards, only a very small + kernel module is needed. The main part of the driver will run in + user space. This simplifies development and reduces the risk of + serious bugs within a kernel module. @@ -193,18 +198,6 @@ interested in translating it, please ema - addr: The address of memory that can be - mapped. This file will only appear if the address is not NULL. - - - - - size: The size, in bytes, of the memory - pointed to by addr. This file only appears if size is not 0. - - - - version: A version string defined by your driver. This allows the user space part of your driver to deal with different versions of the kernel module. @@ -218,14 +211,53 @@ interested in translating it, please ema - - + These attributes appear under the /sys/class/uio/uioX directory. Please note that this directory might be a symlink, and not a real directory. Any userspace code that accesses it must be able - to handle this.) + to handle this. + + + Each UIO device can make one or more memory regions available for + memory mapping. This is necessary because some industrial I/O cards + require access to more than one PCI memory region in a driver. + + + Each mapping has its own directory in sysfs, the first mapping + appears as /sys/class/uio/uioX/maps/map0/. + Subsequent mappings create directories map1/, + map2/, and so on. These directories will only + appear if the size of the mapping is not 0. + + + Each mapX/ directory contains two read-only files + that show start address and size of the memory: + + + + + addr: The address of memory that can be mapped. + + + + size: The size, in bytes, of the memory + pointed to by addr. + + + + + + From userspace, the different mappings are distinguished by adjusting + the offset parameter of the + mmap() call. To map the memory of mapping N, you + have to use N times the page size as your offset: + + +offset = N * getpagesize(); + + @@ -309,23 +341,10 @@ it will appear in sysfs. I recommend usi -int memtype: Required if you have memory that can be -mapped with mmap(). Set this to -UIO_MEM_PHYS if you you have physical memory on your -card to be mapped. Use UIO_MEM_LOGICAL for logical -memory (e.g. allocated with kmalloc()). - - - -unsigned long addr: Required if you have memory that -can be mapped with mmap(). Fill in the address of -your memory block. - - - -unsigned long size: Required if you have memory that -can be mapped with mmap(). Fill in the size of the -memory block that addr points to. +struct uio_mem mem[ MAX_UIO_MAPS ]: Required if you +have memory that can be mapped with mmap(). For each +mapping you need to fill one of the uio_mem structures. +See the description below for details. @@ -367,8 +386,53 @@ device is actually used. open(), you will probably also want a custom release() function. + + +Usually, your device will have one or more memory regions that can be mapped +to user space. For each region, you have to set up a +struct uio_mem in the mem[] array. +Here's a description of the fields of struct uio_mem: + + + + +int memtype: Required if the mapping is used. Set this to +UIO_MEM_PHYS if you you have physical memory on your +card to be mapped. Use UIO_MEM_LOGICAL for logical +memory (e.g. allocated with kmalloc()). There's also +UIO_MEM_VIRTUAL for virtual memory. + + + +unsigned long addr: Required if the mapping is used. +Fill in the address of your memory block. This address is the one that +appears in sysfs. + + + +unsigned long size: Fill in the size of the +memory block that addr points to. If size +is zero, the mapping is considered unused. Note that you +must initialize size with zero for +all unused mappings. + + + +void *internal_addr: If you have to access this memory +region from within your kernel module, you will want to map it internally by +using something like ioremap_nocache(). Addresses +returned by this function can not be mapped to user space, so you must not +store it in addr. Use internal_addr +instead to remember such an address. + + + +Please do not touch the kobj element of +struct uio_mem! It is used by the UIO framework +to set up sysfs files for this mapping. Simply leave it alone. +