summaryrefslogtreecommitdiff
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorClemens Ladisch <clemens@ladisch.de>2011-09-13 13:24:41 +0400
committerTakashi Iwai <tiwai@suse.de>2011-09-14 13:00:51 +0400
commitdba8b46992c55946d3b092934f581a343403118f (patch)
tree7ea5af971bc5cc8ecf4c8af1e0547fa11291ba86 /Documentation/DocBook
parent47124373b59e43fd07cbf7b44d9288f19c1d5a93 (diff)
downloadlinux-dba8b46992c55946d3b092934f581a343403118f.tar.xz
ALSA: mpu401: clean up interrupt specification
The semantics of snd_mpu401_uart_new()'s interrupt parameters are somewhat counterintuitive: To prevent the function from allocating its own interrupt, either the irq number must be invalid, or the irq_flags parameter must be zero. At the same time, the irq parameter being invalid specifies that the mpu401 code has to work without an interrupt allocated by the caller. This implies that, if there is an interrupt and it is allocated by the caller, the irq parameter must be set to a valid-looking number which then isn't actually used. With the removal of IRQF_DISABLED, zero becomes a valid irq_flags value, which forces us to handle the parameters differently. This patch introduces a new flag MPU401_INFO_IRQ_HOOK for when the device interrupt is handled by the caller, and makes the allocation of the interrupt to depend only on the irq parameter. As suggested by Takashi, the irq_flags parameter was dropped because, when used, it had the constant value IRQF_DISABLED. Signed-off-by: Clemens Ladisch <clemens@ladisch.de> Signed-off-by: Takashi Iwai <tiwai@suse.de>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/writing-an-alsa-driver.tmpl36
1 files changed, 21 insertions, 15 deletions
diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl
index 598c22f3b3ac..5de23c007078 100644
--- a/Documentation/DocBook/writing-an-alsa-driver.tmpl
+++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl
@@ -4288,7 +4288,7 @@ struct _snd_pcm_runtime {
<![CDATA[
struct snd_rawmidi *rmidi;
snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
- irq, irq_flags, &rmidi);
+ irq, &rmidi);
]]>
</programlisting>
</informalexample>
@@ -4343,6 +4343,13 @@ struct _snd_pcm_runtime {
by itself to start processing the output stream in the irq handler.
</para>
+ <para>
+ If the MPU-401 interface shares its interrupt with the other logical
+ devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
+ (see <link linkend="midi-interface-interrupt-handler"><citetitle>
+ below</citetitle></link>).
+ </para>
+
<para>
Usually, the port address corresponds to the command port and
port + 1 corresponds to the data port. If not, you may change
@@ -4375,14 +4382,12 @@ struct _snd_pcm_runtime {
</para>
<para>
- The 6th argument specifies the irq number for UART. If the irq
- is already allocated, pass 0 to the 7th argument
- (<parameter>irq_flags</parameter>). Otherwise, pass the flags
- for irq allocation
- (<constant>SA_XXX</constant> bits) to it, and the irq will be
- reserved by the mpu401-uart layer. If the card doesn't generate
- UART interrupts, pass -1 as the irq number. Then a timer
- interrupt will be invoked for polling.
+ The 6th argument specifies the ISA irq number that will be
+ allocated. If no interrupt is to be allocated (because your
+ code is already allocating a shared interrupt, or because the
+ device does not use interrupts), pass -1 instead.
+ For a MPU-401 device without an interrupt, a polling timer
+ will be used instead.
</para>
</section>
@@ -4390,12 +4395,13 @@ struct _snd_pcm_runtime {
<title>Interrupt Handler</title>
<para>
When the interrupt is allocated in
- <function>snd_mpu401_uart_new()</function>, the private
- interrupt handler is used, hence you don't have anything else to do
- than creating the mpu401 stuff. Otherwise, you have to call
- <function>snd_mpu401_uart_interrupt()</function> explicitly when
- a UART interrupt is invoked and checked in your own interrupt
- handler.
+ <function>snd_mpu401_uart_new()</function>, an exclusive ISA
+ interrupt handler is automatically used, hence you don't have
+ anything else to do than creating the mpu401 stuff. Otherwise, you
+ have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
+ <function>snd_mpu401_uart_interrupt()</function> explicitly from your
+ own interrupt handler when it has determined that a UART interrupt
+ has occurred.
</para>
<para>