diff options
author | Hans J. Koch <hjk@linutronix.de> | 2009-01-06 23:12:37 (GMT) |
---|---|---|
committer | Greg Kroah-Hartman <gregkh@kvm.kroah.org> | 2009-01-28 23:55:48 (GMT) |
commit | 6a1b699678c8c0d45f88a37b32358a9e82bef6bb (patch) | |
tree | a70afdb7c6011e84fcb23957eca3503a3916f0ff /Documentation/DocBook/uio-howto.tmpl | |
parent | 720893fd5fb6de1f752f816a89e630f08ae8b20a (diff) | |
download | linux-6a1b699678c8c0d45f88a37b32358a9e82bef6bb.tar.xz |
UIO: Add missing documentation of features added recently
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 <hjk@linutronix.de>
Acked-by: Uwe Kleine-König <ukleinek@strlen.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 | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index b787e47..52e1b79 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -42,6 +42,12 @@ GPL version 2. <revhistory> <revision> + <revnumber>0.7</revnumber> + <date>2008-12-23</date> + <authorinitials>hjk</authorinitials> + <revremark>Added generic platform drivers and offset attribute.</revremark> + </revision> + <revision> <revnumber>0.6</revnumber> <date>2008-12-05</date> <authorinitials>hjk</authorinitials> @@ -312,6 +318,16 @@ interested in translating it, please email me pointed to by addr. </para> </listitem> +<listitem> + <para> + <filename>offset</filename>: The offset, in bytes, that has to be + added to the pointer returned by <function>mmap()</function> to get + to the actual device memory. This is important if the device's memory + is not page aligned. Remember that pointers returned by + <function>mmap()</function> are always page aligned, so it is good + style to always add this offset. + </para> +</listitem> </itemizedlist> <para> @@ -594,6 +610,78 @@ framework to set up sysfs files for this region. Simply leave it alone. </para> </sect1> +<sect1 id="using_uio_pdrv"> +<title>Using uio_pdrv for platform devices</title> + <para> + In many cases, UIO drivers for platform devices can be handled in a + generic way. In the same place where you define your + <varname>struct platform_device</varname>, you simply also implement + your interrupt handler and fill your + <varname>struct uio_info</varname>. A pointer to this + <varname>struct uio_info</varname> is then used as + <varname>platform_data</varname> for your platform device. + </para> + <para> + You also need to set up an array of <varname>struct resource</varname> + containing addresses and sizes of your memory mappings. This + information is passed to the driver using the + <varname>.resource</varname> and <varname>.num_resources</varname> + elements of <varname>struct platform_device</varname>. + </para> + <para> + You now have to set the <varname>.name</varname> element of + <varname>struct platform_device</varname> to + <varname>"uio_pdrv"</varname> to use the generic UIO platform device + driver. This driver will fill the <varname>mem[]</varname> array + according to the resources given, and register the device. + </para> + <para> + 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. + </para> +</sect1> + +<sect1 id="using_uio_pdrv_genirq"> +<title>Using uio_pdrv_genirq for platform devices</title> + <para> + 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 <varname>uio_pdrv</varname> one step further and use a + generic interrupt handler. That's what + <varname>uio_pdrv_genirq</varname> does. + </para> + <para> + The setup for this driver is the same as described above for + <varname>uio_pdrv</varname>, except that you do not implement an + interrupt handler. The <varname>.handler</varname> element of + <varname>struct uio_info</varname> must remain + <varname>NULL</varname>. The <varname>.irq_flags</varname> element + must not contain <varname>IRQF_SHARED</varname>. + </para> + <para> + You will set the <varname>.name</varname> element of + <varname>struct platform_device</varname> to + <varname>"uio_pdrv_genirq"</varname> to use this driver. + </para> + <para> + The generic interrupt handler of <varname>uio_pdrv_genirq</varname> + will simply disable the interrupt line using + <function>disable_irq_nosync()</function>. After doing its work, + userspace can reenable the interrupt by writing 0x00000001 to the UIO + device file. The driver already implements an + <function>irq_control()</function> to make this possible, you must not + implement your own. + </para> + <para> + Using <varname>uio_pdrv_genirq</varname> 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. + </para> +</sect1> + </chapter> <chapter id="userspace_driver" xreflabel="Writing a driver in user space"> |