From 6a1b699678c8c0d45f88a37b32358a9e82bef6bb Mon Sep 17 00:00:00 2001 From: "Hans J. Koch" Date: Wed, 7 Jan 2009 00:12:37 +0100 Subject: [PATCH] UIO: Add missing documentation of features added recently MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The following features were added to the UIO framework in the near past: * Generic drivers for platform devices (uio_pdrv, uio_pdrv_genirq) * an "offset" sysfs attribute for memory mappings Unfortunately, all this went in without documentation (won't happen again...) This patch updates UIO documentation. Signed-off-by: Hans J. Koch Acked-by: Uwe Kleine-König Signed-off-by: Greg Kroah-Hartman --- Documentation/DocBook/uio-howto.tmpl | 88 ++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index b787e4721c90..52e1b79ce0e6 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -41,6 +41,12 @@ GPL version 2. + + 0.7 + 2008-12-23 + hjk + Added generic platform drivers and offset attribute. + 0.6 2008-12-05 @@ -312,6 +318,16 @@ interested in translating it, please email me pointed to by addr. + + + offset: The offset, in bytes, that has to be + added to the pointer returned by mmap() to get + to the actual device memory. This is important if the device's memory + is not page aligned. Remember that pointers returned by + mmap() are always page aligned, so it is good + style to always add this offset. + + @@ -594,6 +610,78 @@ framework to set up sysfs files for this region. Simply leave it alone. + +Using uio_pdrv for platform devices + + In many cases, UIO drivers for platform devices can be handled in a + generic way. In the same place where you define your + struct platform_device, you simply also implement + your interrupt handler and fill your + struct uio_info. A pointer to this + struct uio_info is then used as + platform_data for your platform device. + + + You also need to set up an array of struct resource + containing addresses and sizes of your memory mappings. This + information is passed to the driver using the + .resource and .num_resources + elements of struct platform_device. + + + You now have to set the .name element of + struct platform_device to + "uio_pdrv" to use the generic UIO platform device + driver. This driver will fill the mem[] array + according to the resources given, and register the device. + + + The advantage of this approach is that you only have to edit a file + you need to edit anyway. You do not have to create an extra driver. + + + + +Using uio_pdrv_genirq for platform devices + + Especially in embedded devices, you frequently find chips where the + irq pin is tied to its own dedicated interrupt line. In such cases, + where you can be really sure the interrupt is not shared, we can take + the concept of uio_pdrv one step further and use a + generic interrupt handler. That's what + uio_pdrv_genirq does. + + + The setup for this driver is the same as described above for + uio_pdrv, except that you do not implement an + interrupt handler. The .handler element of + struct uio_info must remain + NULL. The .irq_flags element + must not contain IRQF_SHARED. + + + You will set the .name element of + struct platform_device to + "uio_pdrv_genirq" to use this driver. + + + The generic interrupt handler of uio_pdrv_genirq + will simply disable the interrupt line using + disable_irq_nosync(). After doing its work, + userspace can reenable the interrupt by writing 0x00000001 to the UIO + device file. The driver already implements an + irq_control() to make this possible, you must not + implement your own. + + + Using uio_pdrv_genirq not only saves a few lines of + interrupt handler code. You also do not need to know anything about + the chip's internal registers to create the kernel part of the driver. + All you need to know is the irq number of the pin the chip is + connected to. + + +