From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752970AbYLXDF0 (ORCPT ); Tue, 23 Dec 2008 22:05:26 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1751254AbYLXDFO (ORCPT ); Tue, 23 Dec 2008 22:05:14 -0500 Received: from www.tglx.de ([62.245.132.106]:44547 "EHLO www.tglx.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751233AbYLXDFN (ORCPT ); Tue, 23 Dec 2008 22:05:13 -0500 Date: Wed, 24 Dec 2008 04:04:03 +0100 From: "Hans J. Koch" To: linux-kernel@vger.kernel.org Cc: Greg Kroah-Hartman , Uwe =?utf-8?Q?Kleine-K=C3=B6nig?= , Magnus Damm Subject: [PATCH] UIO: Add missing documentation of features added recently Message-ID: <20081224030400.GB3081@local> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.18 (2008-05-17) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 --- Documentation/DocBook/uio-howto.tmpl | 88 +++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) Index: linux-2.6.28-rc/Documentation/DocBook/uio-howto.tmpl =================================================================== --- linux-2.6.28-rc.orig/Documentation/DocBook/uio-howto.tmpl 2008-12-24 01:15:17.000000000 +0100 +++ linux-2.6.28-rc/Documentation/DocBook/uio-howto.tmpl 2008-12-24 03:29:37.000000000 +0100 @@ -42,6 +42,12 @@ + 0.7 + 2008-12-23 + hjk + Added generic platform drivers and offset attribute. + + 0.6 2008-12-05 hjk @@ -312,6 +318,16 @@ 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 @@ + +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. + + +