<?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>Operators</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="ch05.html" title="Chapter 5. PCM Interface" /><link rel="prev" href="ch05s05.html" title="Runtime Pointer - The Chest of PCM Information" /><link rel="next" href="ch05s07.html" title="Interrupt Handler" /></head><body><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="ch05s05.html">Prev</a> </td><th width="60%" align="center">Chapter 5. PCM Interface</th><td width="20%" align="right"> <a accesskey="n" href="ch05s07.html">Next</a></td></tr></table><hr /></div><div class="section" title="Operators"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="pcm-interface-operators"></a>Operators</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-open-callback">open callback</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-close-callback">close callback</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-ioctl-callback">ioctl callback</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-hw-params-callback">hw_params callback</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-hw-free-callback">hw_free callback</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-prepare-callback">prepare callback</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-trigger-callback">trigger callback</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-pointer-callback">pointer callback</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-copy-silence">copy and silence callbacks</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-ack">ack callback</a></span></dt><dt><span class="section"><a href="ch05s06.html#pcm-interface-operators-page-callback">page callback</a></span></dt></dl></div><p> OK, now let me give details about each pcm callback (<em class="parameter"><code>ops</code></em>). In general, every callback must return 0 if successful, or a negative error number such as <code class="constant">-EINVAL</code>. To choose an appropriate error number, it is advised to check what value other parts of the kernel return when the same kind of request fails. </p><p> The callback function takes at least the argument with <span class="structname">snd_pcm_substream</span> pointer. To retrieve the chip record from the given substream instance, you can use the following macro. </p><div class="informalexample"><pre class="programlisting"> int xxx() { struct mychip *chip = snd_pcm_substream_chip(substream); .... } </pre></div><p> The macro reads <code class="constant">substream->private_data</code>, which is a copy of <code class="constant">pcm->private_data</code>. You can override the former if you need to assign different data records per PCM substream. For example, the cmi8330 driver assigns different private_data for playback and capture directions, because it uses two different codecs (SB- and AD-compatible) for different directions. </p><div class="section" title="open callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-open-callback"></a>open callback</h3></div></div></div><p> </p><div class="informalexample"><pre class="programlisting"> static int snd_xxx_open(struct snd_pcm_substream *substream); </pre></div><p> This is called when a pcm substream is opened. </p><p> At least, here you have to initialize the runtime->hw record. Typically, this is done by like this: </p><div class="informalexample"><pre class="programlisting"> static int snd_xxx_open(struct snd_pcm_substream *substream) { struct mychip *chip = snd_pcm_substream_chip(substream); struct snd_pcm_runtime *runtime = substream->runtime; runtime->hw = snd_mychip_playback_hw; return 0; } </pre></div><p> where <em class="parameter"><code>snd_mychip_playback_hw</code></em> is the pre-defined hardware description. </p><p> You can allocate a private data in this callback, as described in <a class="link" href="ch05s05.html#pcm-interface-runtime-private" title="Private Data"><em class="citetitle"> Private Data</em></a> section. </p><p> If the hardware configuration needs more constraints, set the hardware constraints here, too. See <a class="link" href="ch05s09.html" title="Constraints"><em class="citetitle"> Constraints</em></a> for more details. </p></div><div class="section" title="close callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-close-callback"></a>close callback</h3></div></div></div><p> </p><div class="informalexample"><pre class="programlisting"> static int snd_xxx_close(struct snd_pcm_substream *substream); </pre></div><p> Obviously, this is called when a pcm substream is closed. </p><p> Any private instance for a pcm substream allocated in the open callback will be released here. </p><div class="informalexample"><pre class="programlisting"> static int snd_xxx_close(struct snd_pcm_substream *substream) { .... kfree(substream->runtime->private_data); .... } </pre></div><p> </p></div><div class="section" title="ioctl callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-ioctl-callback"></a>ioctl callback</h3></div></div></div><p> This is used for any special call to pcm ioctls. But usually you can pass a generic ioctl callback, <code class="function">snd_pcm_lib_ioctl</code>. </p></div><div class="section" title="hw_params callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-hw-params-callback"></a>hw_params callback</h3></div></div></div><p> </p><div class="informalexample"><pre class="programlisting"> static int snd_xxx_hw_params(struct snd_pcm_substream *substream, struct snd_pcm_hw_params *hw_params); </pre></div><p> </p><p> This is called when the hardware parameter (<em class="structfield"><code>hw_params</code></em>) is set up by the application, that is, once when the buffer size, the period size, the format, etc. are defined for the pcm substream. </p><p> Many hardware setups should be done in this callback, including the allocation of buffers. </p><p> Parameters to be initialized are retrieved by <code class="function">params_xxx()</code> macros. To allocate buffer, you can call a helper function, </p><div class="informalexample"><pre class="programlisting"> snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); </pre></div><p> <code class="function">snd_pcm_lib_malloc_pages()</code> is available only when the DMA buffers have been pre-allocated. See the section <a class="link" href="ch11.html#buffer-and-memory-buffer-types" title="Buffer Types"><em class="citetitle"> Buffer Types</em></a> for more details. </p><p> Note that this and <em class="structfield"><code>prepare</code></em> callbacks may be called multiple times per initialization. For example, the OSS emulation may call these callbacks at each change via its ioctl. </p><p> Thus, you need to be careful not to allocate the same buffers many times, which will lead to memory leaks! Calling the helper function above many times is OK. It will release the previous buffer automatically when it was already allocated. </p><p> Another note is that this callback is non-atomic (schedulable). This is important, because the <em class="structfield"><code>trigger</code></em> callback is atomic (non-schedulable). That is, mutexes or any schedule-related functions are not available in <em class="structfield"><code>trigger</code></em> callback. Please see the subsection <a class="link" href="ch05s08.html" title="Atomicity"><em class="citetitle"> Atomicity</em></a> for details. </p></div><div class="section" title="hw_free callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-hw-free-callback"></a>hw_free callback</h3></div></div></div><p> </p><div class="informalexample"><pre class="programlisting"> static int snd_xxx_hw_free(struct snd_pcm_substream *substream); </pre></div><p> </p><p> This is called to release the resources allocated via <em class="structfield"><code>hw_params</code></em>. For example, releasing the buffer via <code class="function">snd_pcm_lib_malloc_pages()</code> is done by calling the following: </p><div class="informalexample"><pre class="programlisting"> snd_pcm_lib_free_pages(substream); </pre></div><p> </p><p> This function is always called before the close callback is called. Also, the callback may be called multiple times, too. Keep track whether the resource was already released. </p></div><div class="section" title="prepare callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-prepare-callback"></a>prepare callback</h3></div></div></div><p> </p><div class="informalexample"><pre class="programlisting"> static int snd_xxx_prepare(struct snd_pcm_substream *substream); </pre></div><p> </p><p> This callback is called when the pcm is <span class="quote">“<span class="quote">prepared</span>”</span>. You can set the format type, sample rate, etc. here. The difference from <em class="structfield"><code>hw_params</code></em> is that the <em class="structfield"><code>prepare</code></em> callback will be called each time <code class="function">snd_pcm_prepare()</code> is called, i.e. when recovering after underruns, etc. </p><p> Note that this callback is now non-atomic. You can use schedule-related functions safely in this callback. </p><p> In this and the following callbacks, you can refer to the values via the runtime record, substream->runtime. For example, to get the current rate, format or channels, access to runtime->rate, runtime->format or runtime->channels, respectively. The physical address of the allocated buffer is set to runtime->dma_area. The buffer and period sizes are in runtime->buffer_size and runtime->period_size, respectively. </p><p> Be careful that this callback will be called many times at each setup, too. </p></div><div class="section" title="trigger callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-trigger-callback"></a>trigger callback</h3></div></div></div><p> </p><div class="informalexample"><pre class="programlisting"> static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); </pre></div><p> This is called when the pcm is started, stopped or paused. </p><p> Which action is specified in the second argument, <code class="constant">SNDRV_PCM_TRIGGER_XXX</code> in <code class="filename"><sound/pcm.h></code>. At least, the <code class="constant">START</code> and <code class="constant">STOP</code> commands must be defined in this callback. </p><div class="informalexample"><pre class="programlisting"> switch (cmd) { case SNDRV_PCM_TRIGGER_START: /* do something to start the PCM engine */ break; case SNDRV_PCM_TRIGGER_STOP: /* do something to stop the PCM engine */ break; default: return -EINVAL; } </pre></div><p> </p><p> When the pcm supports the pause operation (given in the info field of the hardware table), the <code class="constant">PAUSE_PUSE</code> and <code class="constant">PAUSE_RELEASE</code> commands must be handled here, too. The former is the command to pause the pcm, and the latter to restart the pcm again. </p><p> When the pcm supports the suspend/resume operation, regardless of full or partial suspend/resume support, the <code class="constant">SUSPEND</code> and <code class="constant">RESUME</code> commands must be handled, too. These commands are issued when the power-management status is changed. Obviously, the <code class="constant">SUSPEND</code> and <code class="constant">RESUME</code> commands suspend and resume the pcm substream, and usually, they are identical to the <code class="constant">STOP</code> and <code class="constant">START</code> commands, respectively. See the <a class="link" href="ch13.html" title="Chapter 13. Power Management"><em class="citetitle"> Power Management</em></a> section for details. </p><p> As mentioned, this callback is atomic. You cannot call functions which may sleep. The trigger callback should be as minimal as possible, just really triggering the DMA. The other stuff should be initialized hw_params and prepare callbacks properly beforehand. </p></div><div class="section" title="pointer callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-pointer-callback"></a>pointer callback</h3></div></div></div><p> </p><div class="informalexample"><pre class="programlisting"> static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) </pre></div><p> This callback is called when the PCM middle layer inquires the current hardware position on the buffer. The position must be returned in frames, ranging from 0 to buffer_size - 1. </p><p> This is called usually from the buffer-update routine in the pcm middle layer, which is invoked when <code class="function">snd_pcm_period_elapsed()</code> is called in the interrupt routine. Then the pcm middle layer updates the position and calculates the available space, and wakes up the sleeping poll threads, etc. </p><p> This callback is also atomic. </p></div><div class="section" title="copy and silence callbacks"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-copy-silence"></a>copy and silence callbacks</h3></div></div></div><p> These callbacks are not mandatory, and can be omitted in most cases. These callbacks are used when the hardware buffer cannot be in the normal memory space. Some chips have their own buffer on the hardware which is not mappable. In such a case, you have to transfer the data manually from the memory buffer to the hardware buffer. Or, if the buffer is non-contiguous on both physical and virtual memory spaces, these callbacks must be defined, too. </p><p> If these two callbacks are defined, copy and set-silence operations are done by them. The detailed will be described in the later section <a class="link" href="ch11.html" title="Chapter 11. Buffer and Memory Management"><em class="citetitle">Buffer and Memory Management</em></a>. </p></div><div class="section" title="ack callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-ack"></a>ack callback</h3></div></div></div><p> This callback is also not mandatory. This callback is called when the appl_ptr is updated in read or write operations. Some drivers like emu10k1-fx and cs46xx need to track the current appl_ptr for the internal buffer, and this callback is useful only for such a purpose. </p><p> This callback is atomic. </p></div><div class="section" title="page callback"><div class="titlepage"><div><div><h3 class="title"><a id="pcm-interface-operators-page-callback"></a>page callback</h3></div></div></div><p> This callback is optional too. This callback is used mainly for non-contiguous buffers. The mmap calls this callback to get the page address. Some examples will be explained in the later section <a class="link" href="ch11.html" title="Chapter 11. Buffer and Memory Management"><em class="citetitle">Buffer and Memory Management</em></a>, too. </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch05s07.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>