summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/uio-howto.tmpl
diff options
context:
space:
mode:
authorHans J. Koch <hjk@linutronix.de>2008-05-23 15:50:14 +0400
committerGreg Kroah-Hartman <gregkh@suse.de>2008-07-22 08:54:55 +0400
commit328a14e70e7f46997cb50d4258dd93d5377f98c6 (patch)
tree7cc64b122fc45af454d4dde9f561b329d9f2b0c4 /Documentation/DocBook/uio-howto.tmpl
parent934da4766e5f72797118f7c014efaef567a812fc (diff)
downloadlinux-328a14e70e7f46997cb50d4258dd93d5377f98c6.tar.xz
UIO: Add write function to allow irq masking
Sometimes it is necessary to enable/disable the interrupt of a UIO device from the userspace part of the driver. With this patch, the UIO kernel driver can implement an "irqcontrol()" function that does this. Userspace can write an s32 value to /dev/uioX (usually 0 or 1 to turn the irq off or on). The UIO core will then call the driver's irqcontrol function. Signed-off-by: Hans J. Koch <hjk@linutronix.de> Acked-by: Uwe Kleine-König <Uwe.Kleine-Koenig@digi.com> Acked-by: Magnus Damm <damm@igel.co.jp> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Diffstat (limited to 'Documentation/DocBook/uio-howto.tmpl')
-rw-r--r--Documentation/DocBook/uio-howto.tmpl40
1 files changed, 39 insertions, 1 deletions
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl
index fdd7f4f887b7..c4d187313963 100644
--- a/Documentation/DocBook/uio-howto.tmpl
+++ b/Documentation/DocBook/uio-howto.tmpl
@@ -30,6 +30,12 @@
<revhistory>
<revision>
+ <revnumber>0.5</revnumber>
+ <date>2008-05-22</date>
+ <authorinitials>hjk</authorinitials>
+ <revremark>Added description of write() function.</revremark>
+ </revision>
+ <revision>
<revnumber>0.4</revnumber>
<date>2007-11-26</date>
<authorinitials>hjk</authorinitials>
@@ -64,7 +70,7 @@
<?dbhtml filename="copyright.html"?>
<title>Copyright and License</title>
<para>
- Copyright (c) 2006 by Hans-Jürgen Koch.</para>
+ Copyright (c) 2006-2008 by Hans-Jürgen Koch.</para>
<para>
This documentation is Free Software licensed under the terms of the
GPL version 2.
@@ -189,6 +195,30 @@ interested in translating it, please email me
represents the total interrupt count. You can use this number
to figure out if you missed some interrupts.
</para>
+ <para>
+ For some hardware that has more than one interrupt source internally,
+ but not separate IRQ mask and status registers, there might be
+ situations where userspace cannot determine what the interrupt source
+ was if the kernel handler disables them by writing to the chip's IRQ
+ register. In such a case, the kernel has to disable the IRQ completely
+ to leave the chip's register untouched. Now the userspace part can
+ determine the cause of the interrupt, but it cannot re-enable
+ interrupts. Another cornercase is chips where re-enabling interrupts
+ is a read-modify-write operation to a combined IRQ status/acknowledge
+ register. This would be racy if a new interrupt occurred
+ simultaneously.
+ </para>
+ <para>
+ To address these problems, UIO also implements a write() function. It
+ is normally not used and can be ignored for hardware that has only a
+ single interrupt source or has separate IRQ mask and status registers.
+ If you need it, however, a write to <filename>/dev/uioX</filename>
+ will call the <function>irqcontrol()</function> function implemented
+ by the driver. You have to write a 32-bit value that is usually either
+ 0 or 1 to disable or enable interrupts. If a driver does not implement
+ <function>irqcontrol()</function>, <function>write()</function> will
+ return with <varname>-ENOSYS</varname>.
+ </para>
<para>
To handle interrupts properly, your custom kernel module can
@@ -362,6 +392,14 @@ device is actually used.
<function>open()</function>, you will probably also want a custom
<function>release()</function> function.
</para></listitem>
+
+<listitem><para>
+<varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on)
+</varname>: Optional. If you need to be able to enable or disable
+interrupts from userspace by writing to <filename>/dev/uioX</filename>,
+you can implement this function. The parameter <varname>irq_on</varname>
+will be 0 to disable interrupts and 1 to enable them.
+</para></listitem>
</itemizedlist>
<para>