<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>Callbacks</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="Writing an ALSA Driver" /><link rel="up" href="ch09.html" title="Chapter 9. RawMIDI Interface" /><link rel="prev" href="ch09s02.html" title="Constructor" /><link rel="next" href="ch10.html" title="Chapter 10. Miscellaneous Devices" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Callbacks</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch09s02.html">Prev</a> </td><th width="60%" align="center">Chapter 9. RawMIDI Interface</th><td width="20%" align="right"> <a accesskey="n" href="ch10.html">Next</a></td></tr></table><hr /></div><div class="section" title="Callbacks"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="rawmidi-interface-callbacks"></a>Callbacks</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ch09s03.html#rawmidi-interface-op-open"><code class="function">open</code> callback</a></span></dt><dt><span class="section"><a href="ch09s03.html#rawmidi-interface-op-close"><code class="function">close</code> callback</a></span></dt><dt><span class="section"><a href="ch09s03.html#rawmidi-interface-op-trigger-out"><code class="function">trigger</code> callback for output
substreams</a></span></dt><dt><span class="section"><a href="ch09s03.html#rawmidi-interface-op-trigger-in"><code class="function">trigger</code> callback for input
substreams</a></span></dt><dt><span class="section"><a href="ch09s03.html#rawmidi-interface-op-drain"><code class="function">drain</code> callback</a></span></dt></dl></div><p>
In all the callbacks, the private data that you've set for the
rawmidi device can be accessed as
substream->rmidi->private_data.
</p><p>
If there is more than one port, your callbacks can determine the
port index from the struct snd_rawmidi_substream data passed to each
callback:
</p><div class="informalexample"><pre class="programlisting">
struct snd_rawmidi_substream *substream;
int index = substream->number;
</pre></div><p>
</p><div class="section" title="open callback"><div class="titlepage"><div><div><h3 class="title"><a id="rawmidi-interface-op-open"></a><code class="function">open</code> callback</h3></div></div></div><div class="informalexample"><pre class="programlisting">
static int snd_xxx_open(struct snd_rawmidi_substream *substream);
</pre></div><p>
This is called when a substream is opened.
You can initialize the hardware here, but you shouldn't
start transmitting/receiving data yet.
</p></div><div class="section" title="close callback"><div class="titlepage"><div><div><h3 class="title"><a id="rawmidi-interface-op-close"></a><code class="function">close</code> callback</h3></div></div></div><div class="informalexample"><pre class="programlisting">
static int snd_xxx_close(struct snd_rawmidi_substream *substream);
</pre></div><p>
Guess what.
</p><p>
The <code class="function">open</code> and <code class="function">close</code>
callbacks of a rawmidi device are serialized with a mutex,
and can sleep.
</p></div><div class="section" title="trigger callback for output substreams"><div class="titlepage"><div><div><h3 class="title"><a id="rawmidi-interface-op-trigger-out"></a><code class="function">trigger</code> callback for output
substreams</h3></div></div></div><div class="informalexample"><pre class="programlisting">
static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
</pre></div><p>
This is called with a nonzero <em class="parameter"><code>up</code></em>
parameter when there is some data in the substream buffer that
must be transmitted.
</p><p>
To read data from the buffer, call
<code class="function">snd_rawmidi_transmit_peek</code>. It will
return the number of bytes that have been read; this will be
less than the number of bytes requested when there are no more
data in the buffer.
After the data have been transmitted successfully, call
<code class="function">snd_rawmidi_transmit_ack</code> to remove the
data from the substream buffer:
</p><div class="informalexample"><pre class="programlisting">
unsigned char data;
while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
if (snd_mychip_try_to_transmit(data))
snd_rawmidi_transmit_ack(substream, 1);
else
break; /* hardware FIFO full */
}
</pre></div><p>
</p><p>
If you know beforehand that the hardware will accept data, you
can use the <code class="function">snd_rawmidi_transmit</code> function
which reads some data and removes them from the buffer at once:
</p><div class="informalexample"><pre class="programlisting">
while (snd_mychip_transmit_possible()) {
unsigned char data;
if (snd_rawmidi_transmit(substream, &data, 1) != 1)
break; /* no more data */
snd_mychip_transmit(data);
}
</pre></div><p>
</p><p>
If you know beforehand how many bytes you can accept, you can
use a buffer size greater than one with the
<code class="function">snd_rawmidi_transmit*</code> functions.
</p><p>
The <code class="function">trigger</code> callback must not sleep. If
the hardware FIFO is full before the substream buffer has been
emptied, you have to continue transmitting data later, either
in an interrupt handler, or with a timer if the hardware
doesn't have a MIDI transmit interrupt.
</p><p>
The <code class="function">trigger</code> callback is called with a
zero <em class="parameter"><code>up</code></em> parameter when the transmission
of data should be aborted.
</p></div><div class="section" title="trigger callback for input substreams"><div class="titlepage"><div><div><h3 class="title"><a id="rawmidi-interface-op-trigger-in"></a><code class="function">trigger</code> callback for input
substreams</h3></div></div></div><div class="informalexample"><pre class="programlisting">
static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
</pre></div><p>
This is called with a nonzero <em class="parameter"><code>up</code></em>
parameter to enable receiving data, or with a zero
<em class="parameter"><code>up</code></em> parameter do disable receiving data.
</p><p>
The <code class="function">trigger</code> callback must not sleep; the
actual reading of data from the device is usually done in an
interrupt handler.
</p><p>
When data reception is enabled, your interrupt handler should
call <code class="function">snd_rawmidi_receive</code> for all received
data:
</p><div class="informalexample"><pre class="programlisting">
void snd_mychip_midi_interrupt(...)
{
while (mychip_midi_available()) {
unsigned char data;
data = mychip_midi_read();
snd_rawmidi_receive(substream, &data, 1);
}
}
</pre></div><p>
</p></div><div class="section" title="drain callback"><div class="titlepage"><div><div><h3 class="title"><a id="rawmidi-interface-op-drain"></a><code class="function">drain</code> callback</h3></div></div></div><div class="informalexample"><pre class="programlisting">
static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
</pre></div><p>
This is only used with output substreams. This function should wait
until all data read from the substream buffer have been transmitted.
This ensures that the device can be closed and the driver unloaded
without losing data.
</p><p>
This callback is optional. If you do not set
<em class="structfield"><code>drain</code></em> in the struct snd_rawmidi_ops
structure, ALSA will simply wait for 50 milliseconds
instead.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch09s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch09.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch10.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Constructor </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. Miscellaneous Devices</td></tr></table></div></body></html>
