1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Operators</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="pcm-interface.html" title="Chapter 5. PCM Interface"><link rel="prev" href="pcm-interface-runtime.html" title="Runtime Pointer - The Chest of PCM Information"><link rel="next" href="pcm-interface-interrupt-handler.html" title="Interrupt Handler"></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">Operators</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="pcm-interface-runtime.html">Prev</a> </td><th width="60%" align="center">Chapter 5. PCM Interface</th><td width="20%" align="right"> <a accesskey="n" href="pcm-interface-interrupt-handler.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pcm-interface-operators"></a>Operators</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-open-callback">open callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-close-callback">close callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-ioctl-callback">ioctl callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-hw-params-callback">hw_params callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-hw-free-callback">hw_free callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-prepare-callback">prepare callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-trigger-callback">trigger callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-pointer-callback">pointer callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-copy-silence">copy and silence callbacks</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-ack">ack callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-page-callback">page callback</a></span></dt></dl></div><p> 2 OK, now let me give details about each pcm callback 3 (<em class="parameter"><code>ops</code></em>). In general, every callback must 4 return 0 if successful, or a negative error number 5 such as <code class="constant">-EINVAL</code>. To choose an appropriate 6 error number, it is advised to check what value other parts of 7 the kernel return when the same kind of request fails. 8 </p><p> 9 The callback function takes at least the argument with 10 <span class="structname">snd_pcm_substream</span> pointer. To retrieve 11 the chip record from the given substream instance, you can use the 12 following macro. 13 14 </p><div class="informalexample"><pre class="programlisting"> 15 16 int xxx() { 17 struct mychip *chip = snd_pcm_substream_chip(substream); 18 .... 19 } 20 21 </pre></div><p> 22 23 The macro reads <code class="constant">substream->private_data</code>, 24 which is a copy of <code class="constant">pcm->private_data</code>. 25 You can override the former if you need to assign different data 26 records per PCM substream. For example, the cmi8330 driver assigns 27 different private_data for playback and capture directions, 28 because it uses two different codecs (SB- and AD-compatible) for 29 different directions. 30 </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-open-callback"></a>open callback</h3></div></div></div><p> 31 </p><div class="informalexample"><pre class="programlisting"> 32 33 static int snd_xxx_open(struct snd_pcm_substream *substream); 34 35 </pre></div><p> 36 37 This is called when a pcm substream is opened. 38 </p><p> 39 At least, here you have to initialize the runtime->hw 40 record. Typically, this is done by like this: 41 42 </p><div class="informalexample"><pre class="programlisting"> 43 44 static int snd_xxx_open(struct snd_pcm_substream *substream) 45 { 46 struct mychip *chip = snd_pcm_substream_chip(substream); 47 struct snd_pcm_runtime *runtime = substream->runtime; 48 49 runtime->hw = snd_mychip_playback_hw; 50 return 0; 51 } 52 53 </pre></div><p> 54 55 where <em class="parameter"><code>snd_mychip_playback_hw</code></em> is the 56 pre-defined hardware description. 57 </p><p> 58 You can allocate a private data in this callback, as described 59 in <a class="link" href="pcm-interface-runtime.html#pcm-interface-runtime-private" title="Private Data"><em class="citetitle"> 60 Private Data</em></a> section. 61 </p><p> 62 If the hardware configuration needs more constraints, set the 63 hardware constraints here, too. 64 See <a class="link" href="pcm-interface-constraints.html" title="Constraints"><em class="citetitle"> 65 Constraints</em></a> for more details. 66 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-close-callback"></a>close callback</h3></div></div></div><p> 67 </p><div class="informalexample"><pre class="programlisting"> 68 69 static int snd_xxx_close(struct snd_pcm_substream *substream); 70 71 </pre></div><p> 72 73 Obviously, this is called when a pcm substream is closed. 74 </p><p> 75 Any private instance for a pcm substream allocated in the 76 open callback will be released here. 77 78 </p><div class="informalexample"><pre class="programlisting"> 79 80 static int snd_xxx_close(struct snd_pcm_substream *substream) 81 { 82 .... 83 kfree(substream->runtime->private_data); 84 .... 85 } 86 87 </pre></div><p> 88 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-ioctl-callback"></a>ioctl callback</h3></div></div></div><p> 89 This is used for any special call to pcm ioctls. But 90 usually you can pass a generic ioctl callback, 91 <code class="function">snd_pcm_lib_ioctl</code>. 92 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-hw-params-callback"></a>hw_params callback</h3></div></div></div><p> 93 </p><div class="informalexample"><pre class="programlisting"> 94 95 static int snd_xxx_hw_params(struct snd_pcm_substream *substream, 96 struct snd_pcm_hw_params *hw_params); 97 98 </pre></div><p> 99 </p><p> 100 This is called when the hardware parameter 101 (<em class="structfield"><code>hw_params</code></em>) is set 102 up by the application, 103 that is, once when the buffer size, the period size, the 104 format, etc. are defined for the pcm substream. 105 </p><p> 106 Many hardware setups should be done in this callback, 107 including the allocation of buffers. 108 </p><p> 109 Parameters to be initialized are retrieved by 110 <code class="function">params_xxx()</code> macros. To allocate 111 buffer, you can call a helper function, 112 113 </p><div class="informalexample"><pre class="programlisting"> 114 115 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); 116 117 </pre></div><p> 118 119 <code class="function">snd_pcm_lib_malloc_pages()</code> is available 120 only when the DMA buffers have been pre-allocated. 121 See the section <a class="link" href="buffer-and-memory.html#buffer-and-memory-buffer-types" title="Buffer Types"><em class="citetitle"> 122 Buffer Types</em></a> for more details. 123 </p><p> 124 Note that this and <em class="structfield"><code>prepare</code></em> callbacks 125 may be called multiple times per initialization. 126 For example, the OSS emulation may 127 call these callbacks at each change via its ioctl. 128 </p><p> 129 Thus, you need to be careful not to allocate the same buffers 130 many times, which will lead to memory leaks! Calling the 131 helper function above many times is OK. It will release the 132 previous buffer automatically when it was already allocated. 133 </p><p> 134 Another note is that this callback is non-atomic 135 (schedulable) as default, i.e. when no 136 <em class="structfield"><code>nonatomic</code></em> flag set. 137 This is important, because the 138 <em class="structfield"><code>trigger</code></em> callback 139 is atomic (non-schedulable). That is, mutexes or any 140 schedule-related functions are not available in 141 <em class="structfield"><code>trigger</code></em> callback. 142 Please see the subsection 143 <a class="link" href="pcm-interface-atomicity.html" title="Atomicity"><em class="citetitle"> 144 Atomicity</em></a> for details. 145 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-hw-free-callback"></a>hw_free callback</h3></div></div></div><p> 146 </p><div class="informalexample"><pre class="programlisting"> 147 148 static int snd_xxx_hw_free(struct snd_pcm_substream *substream); 149 150 </pre></div><p> 151 </p><p> 152 This is called to release the resources allocated via 153 <em class="structfield"><code>hw_params</code></em>. For example, releasing the 154 buffer via 155 <code class="function">snd_pcm_lib_malloc_pages()</code> is done by 156 calling the following: 157 158 </p><div class="informalexample"><pre class="programlisting"> 159 160 snd_pcm_lib_free_pages(substream); 161 162 </pre></div><p> 163 </p><p> 164 This function is always called before the close callback is called. 165 Also, the callback may be called multiple times, too. 166 Keep track whether the resource was already released. 167 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-prepare-callback"></a>prepare callback</h3></div></div></div><p> 168 </p><div class="informalexample"><pre class="programlisting"> 169 170 static int snd_xxx_prepare(struct snd_pcm_substream *substream); 171 172 </pre></div><p> 173 </p><p> 174 This callback is called when the pcm is 175 <span class="quote">“<span class="quote">prepared</span>”</span>. You can set the format type, sample 176 rate, etc. here. The difference from 177 <em class="structfield"><code>hw_params</code></em> is that the 178 <em class="structfield"><code>prepare</code></em> callback will be called each 179 time 180 <code class="function">snd_pcm_prepare()</code> is called, i.e. when 181 recovering after underruns, etc. 182 </p><p> 183 Note that this callback is now non-atomic. 184 You can use schedule-related functions safely in this callback. 185 </p><p> 186 In this and the following callbacks, you can refer to the 187 values via the runtime record, 188 substream->runtime. 189 For example, to get the current 190 rate, format or channels, access to 191 runtime->rate, 192 runtime->format or 193 runtime->channels, respectively. 194 The physical address of the allocated buffer is set to 195 runtime->dma_area. The buffer and period sizes are 196 in runtime->buffer_size and runtime->period_size, 197 respectively. 198 </p><p> 199 Be careful that this callback will be called many times at 200 each setup, too. 201 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-trigger-callback"></a>trigger callback</h3></div></div></div><p> 202 </p><div class="informalexample"><pre class="programlisting"> 203 204 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); 205 206 </pre></div><p> 207 208 This is called when the pcm is started, stopped or paused. 209 </p><p> 210 Which action is specified in the second argument, 211 <code class="constant">SNDRV_PCM_TRIGGER_XXX</code> in 212 <code class="filename"><sound/pcm.h></code>. At least, 213 the <code class="constant">START</code> and <code class="constant">STOP</code> 214 commands must be defined in this callback. 215 216 </p><div class="informalexample"><pre class="programlisting"> 217 218 switch (cmd) { 219 case SNDRV_PCM_TRIGGER_START: 220 /* do something to start the PCM engine */ 221 break; 222 case SNDRV_PCM_TRIGGER_STOP: 223 /* do something to stop the PCM engine */ 224 break; 225 default: 226 return -EINVAL; 227 } 228 229 </pre></div><p> 230 </p><p> 231 When the pcm supports the pause operation (given in the info 232 field of the hardware table), the <code class="constant">PAUSE_PUSH</code> 233 and <code class="constant">PAUSE_RELEASE</code> commands must be 234 handled here, too. The former is the command to pause the pcm, 235 and the latter to restart the pcm again. 236 </p><p> 237 When the pcm supports the suspend/resume operation, 238 regardless of full or partial suspend/resume support, 239 the <code class="constant">SUSPEND</code> and <code class="constant">RESUME</code> 240 commands must be handled, too. 241 These commands are issued when the power-management status is 242 changed. Obviously, the <code class="constant">SUSPEND</code> and 243 <code class="constant">RESUME</code> commands 244 suspend and resume the pcm substream, and usually, they 245 are identical to the <code class="constant">STOP</code> and 246 <code class="constant">START</code> commands, respectively. 247 See the <a class="link" href="power-management.html" title="Chapter 13. Power Management"><em class="citetitle"> 248 Power Management</em></a> section for details. 249 </p><p> 250 As mentioned, this callback is atomic as default unless 251 <em class="structfield"><code>nonatomic</code></em> flag set, and 252 you cannot call functions which may sleep. 253 The trigger callback should be as minimal as possible, 254 just really triggering the DMA. The other stuff should be 255 initialized hw_params and prepare callbacks properly 256 beforehand. 257 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-pointer-callback"></a>pointer callback</h3></div></div></div><p> 258 </p><div class="informalexample"><pre class="programlisting"> 259 260 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) 261 262 </pre></div><p> 263 264 This callback is called when the PCM middle layer inquires 265 the current hardware position on the buffer. The position must 266 be returned in frames, 267 ranging from 0 to buffer_size - 1. 268 </p><p> 269 This is called usually from the buffer-update routine in the 270 pcm middle layer, which is invoked when 271 <code class="function">snd_pcm_period_elapsed()</code> is called in the 272 interrupt routine. Then the pcm middle layer updates the 273 position and calculates the available space, and wakes up the 274 sleeping poll threads, etc. 275 </p><p> 276 This callback is also atomic as default. 277 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-copy-silence"></a>copy and silence callbacks</h3></div></div></div><p> 278 These callbacks are not mandatory, and can be omitted in 279 most cases. These callbacks are used when the hardware buffer 280 cannot be in the normal memory space. Some chips have their 281 own buffer on the hardware which is not mappable. In such a 282 case, you have to transfer the data manually from the memory 283 buffer to the hardware buffer. Or, if the buffer is 284 non-contiguous on both physical and virtual memory spaces, 285 these callbacks must be defined, too. 286 </p><p> 287 If these two callbacks are defined, copy and set-silence 288 operations are done by them. The detailed will be described in 289 the later section <a class="link" href="buffer-and-memory.html" title="Chapter 11. Buffer and Memory Management"><em class="citetitle">Buffer and Memory 290 Management</em></a>. 291 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-ack"></a>ack callback</h3></div></div></div><p> 292 This callback is also not mandatory. This callback is called 293 when the appl_ptr is updated in read or write operations. 294 Some drivers like emu10k1-fx and cs46xx need to track the 295 current appl_ptr for the internal buffer, and this callback 296 is useful only for such a purpose. 297 </p><p> 298 This callback is atomic as default. 299 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-operators-page-callback"></a>page callback</h3></div></div></div><p> 300 This callback is optional too. This callback is used 301 mainly for non-contiguous buffers. The mmap calls this 302 callback to get the page address. Some examples will be 303 explained in the later section <a class="link" href="buffer-and-memory.html" title="Chapter 11. Buffer and Memory Management"><em class="citetitle">Buffer and Memory 304 Management</em></a>, too. 305 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pcm-interface-runtime.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pcm-interface.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pcm-interface-interrupt-handler.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Runtime Pointer - The Chest of PCM Information </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Interrupt Handler</td></tr></table></div></body></html> 306