1<html><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.78.1"><link rel="home" href="index.html" title="Writing an ALSA Driver"><link rel="up" href="rawmidi-interface.html" title="Chapter 9. RawMIDI Interface"><link rel="prev" href="rawmidi-interface-constructor.html" title="Constructor"><link rel="next" href="misc-devices.html" title="Chapter 10. Miscellaneous Devices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><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="rawmidi-interface-constructor.html">Prev</a> </td><th width="60%" align="center">Chapter 9. RawMIDI Interface</th><td width="20%" align="right"> <a accesskey="n" href="misc-devices.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rawmidi-interface-callbacks"></a>Callbacks</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-open"><code class="function">open</code> callback</a></span></dt><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-close"><code class="function">close</code> callback</a></span></dt><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-trigger-out"><code class="function">trigger</code> callback for output 2 substreams</a></span></dt><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-trigger-in"><code class="function">trigger</code> callback for input 3 substreams</a></span></dt><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-drain"><code class="function">drain</code> callback</a></span></dt></dl></div><p> 4 In all the callbacks, the private data that you've set for the 5 rawmidi device can be accessed as 6 substream->rmidi->private_data. 7 8 </p><p> 9 If there is more than one port, your callbacks can determine the 10 port index from the struct snd_rawmidi_substream data passed to each 11 callback: 12 </p><div class="informalexample"><pre class="programlisting"> 13 14 struct snd_rawmidi_substream *substream; 15 int index = substream->number; 16 17 </pre></div><p> 18 </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="rawmidi-interface-op-open"></a><code class="function">open</code> callback</h3></div></div></div><div class="informalexample"><pre class="programlisting"> 19 20 static int snd_xxx_open(struct snd_rawmidi_substream *substream); 21 22 </pre></div><p> 23 This is called when a substream is opened. 24 You can initialize the hardware here, but you shouldn't 25 start transmitting/receiving data yet. 26 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="rawmidi-interface-op-close"></a><code class="function">close</code> callback</h3></div></div></div><div class="informalexample"><pre class="programlisting"> 27 28 static int snd_xxx_close(struct snd_rawmidi_substream *substream); 29 30 </pre></div><p> 31 Guess what. 32 </p><p> 33 The <code class="function">open</code> and <code class="function">close</code> 34 callbacks of a rawmidi device are serialized with a mutex, 35 and can sleep. 36 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="rawmidi-interface-op-trigger-out"></a><code class="function">trigger</code> callback for output 37 substreams</h3></div></div></div><div class="informalexample"><pre class="programlisting"> 38 39 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up); 40 41 </pre></div><p> 42 This is called with a nonzero <em class="parameter"><code>up</code></em> 43 parameter when there is some data in the substream buffer that 44 must be transmitted. 45 </p><p> 46 To read data from the buffer, call 47 <code class="function">snd_rawmidi_transmit_peek</code>. It will 48 return the number of bytes that have been read; this will be 49 less than the number of bytes requested when there are no more 50 data in the buffer. 51 After the data have been transmitted successfully, call 52 <code class="function">snd_rawmidi_transmit_ack</code> to remove the 53 data from the substream buffer: 54 </p><div class="informalexample"><pre class="programlisting"> 55 56 unsigned char data; 57 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) { 58 if (snd_mychip_try_to_transmit(data)) 59 snd_rawmidi_transmit_ack(substream, 1); 60 else 61 break; /* hardware FIFO full */ 62 } 63 64 </pre></div><p> 65 </p><p> 66 If you know beforehand that the hardware will accept data, you 67 can use the <code class="function">snd_rawmidi_transmit</code> function 68 which reads some data and removes them from the buffer at once: 69 </p><div class="informalexample"><pre class="programlisting"> 70 71 while (snd_mychip_transmit_possible()) { 72 unsigned char data; 73 if (snd_rawmidi_transmit(substream, &data, 1) != 1) 74 break; /* no more data */ 75 snd_mychip_transmit(data); 76 } 77 78 </pre></div><p> 79 </p><p> 80 If you know beforehand how many bytes you can accept, you can 81 use a buffer size greater than one with the 82 <code class="function">snd_rawmidi_transmit*</code> functions. 83 </p><p> 84 The <code class="function">trigger</code> callback must not sleep. If 85 the hardware FIFO is full before the substream buffer has been 86 emptied, you have to continue transmitting data later, either 87 in an interrupt handler, or with a timer if the hardware 88 doesn't have a MIDI transmit interrupt. 89 </p><p> 90 The <code class="function">trigger</code> callback is called with a 91 zero <em class="parameter"><code>up</code></em> parameter when the transmission 92 of data should be aborted. 93 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="rawmidi-interface-op-trigger-in"></a><code class="function">trigger</code> callback for input 94 substreams</h3></div></div></div><div class="informalexample"><pre class="programlisting"> 95 96 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up); 97 98 </pre></div><p> 99 This is called with a nonzero <em class="parameter"><code>up</code></em> 100 parameter to enable receiving data, or with a zero 101 <em class="parameter"><code>up</code></em> parameter do disable receiving data. 102 </p><p> 103 The <code class="function">trigger</code> callback must not sleep; the 104 actual reading of data from the device is usually done in an 105 interrupt handler. 106 </p><p> 107 When data reception is enabled, your interrupt handler should 108 call <code class="function">snd_rawmidi_receive</code> for all received 109 data: 110 </p><div class="informalexample"><pre class="programlisting"> 111 112 void snd_mychip_midi_interrupt(...) 113 { 114 while (mychip_midi_available()) { 115 unsigned char data; 116 data = mychip_midi_read(); 117 snd_rawmidi_receive(substream, &data, 1); 118 } 119 } 120 121 </pre></div><p> 122 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="rawmidi-interface-op-drain"></a><code class="function">drain</code> callback</h3></div></div></div><div class="informalexample"><pre class="programlisting"> 123 124 static void snd_xxx_drain(struct snd_rawmidi_substream *substream); 125 126 </pre></div><p> 127 This is only used with output substreams. This function should wait 128 until all data read from the substream buffer have been transmitted. 129 This ensures that the device can be closed and the driver unloaded 130 without losing data. 131 </p><p> 132 This callback is optional. If you do not set 133 <em class="structfield"><code>drain</code></em> in the struct snd_rawmidi_ops 134 structure, ALSA will simply wait for 50 milliseconds 135 instead. 136 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rawmidi-interface-constructor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="rawmidi-interface.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="misc-devices.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> 137