<!-- This comment will put IE 6, 7 and 8 in quirks mode -->
<!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/xhtml;charset=UTF-8"/>
<title>ALSA project - the C library reference: PCM External Plugin SDK</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<!-- Generated by Doxygen 1.6.3 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<img id="MSearchSelect" src="search/search.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</div>
</li>
</ul>
</div>
</div>
<div class="contents">
<h1><a class="anchor" id="pcm_external_plugins">PCM External Plugin SDK </a></h1><h2><a class="anchor" id="pcm_externals">
External Plugins</a></h2>
<p>The external plugins are implemented in a shared object file located at /usr/lib/alsa-lib (the exact location depends on the build option and asoundrc configuration). It has to be the file like libasound_module_pcm_MYPLUGIN.so, where MYPLUGIN corresponds to your own plugin name.</p>
<p>The entry point of the plugin is defined via <a class="el" href="group___plugin___s_d_k.html#ga3fd72ea47a7a921943b26c580b9d6c41">SND_PCM_PLUGIN_DEFINE_FUNC()</a> macro. This macro defines the function with a proper name to be referred from alsa-lib. The function takes the following 6 arguments: </p>
<div class="fragment"><pre class="fragment">int (<a class="code" href="group___p_c_m.html#ga919e634deecd855b6e2e15174e70d3ea">snd_pcm_t</a> **pcmp, <span class="keyword">const</span> <span class="keywordtype">char</span> *name, <a class="code" href="group___config.html#ga1c20905af775ae77d04d1a5696f67985" title="Internal structure for a configuration node object.">snd_config_t</a> *root,
<a class="code" href="group___config.html#ga1c20905af775ae77d04d1a5696f67985" title="Internal structure for a configuration node object.">snd_config_t</a> *conf, <a class="code" href="group___p_c_m.html#gac23b43ff55add78638e503b9cc892c24">snd_pcm_stream_t</a> stream, <span class="keywordtype">int</span> mode)
</pre></div><p> The first argument, pcmp, is the pointer to store the resultant PCM handle. The arguments name, root, stream and mode are the parameters to be passed to the plugin constructor. The conf is the configuration tree for the plugin. The arguments above are defined in the macro itself, so don't use variables with the same names to shadow parameters.</p>
<p>After parsing the configuration parameters in the given conf tree, usually you will call the external plugin API function, <a class="el" href="group___p_c_m___ext_plug.html#gab0b27889f74c83cd033062981320fd62" title="Create an extplug instance.">snd_pcm_extplug_create()</a> or <a class="el" href="group___p_c_m___i_o_plug.html#ga7fb5213a5e776246e2b4dc53ec8d7604" title="Create an ioplug instance.">snd_pcm_ioplug_create()</a>, depending on the plugin type. The PCM handle must be filled *pcmp in return. Then this function must return either a value 0 when succeeded, or a negative value as the error code.</p>
<p>Finally, add <a class="el" href="group___plugin___s_d_k.html#ga73a613cc5b7b3642f53bbd5a1d78004b">SND_PCM_PLUGIN_SYMBOL()</a> with the name of your plugin as the argument at the end. This defines the proper versioned symbol as the reference.</p>
<p>The typical code would look like below: </p>
<div class="fragment"><pre class="fragment"><span class="keyword">struct </span>myplug_info {
snd_pcm_extplug_t ext;
<span class="keywordtype">int</span> my_own_data;
...
};
<a class="code" href="group___plugin___s_d_k.html#ga3fd72ea47a7a921943b26c580b9d6c41">SND_PCM_PLUGIN_DEFINE_FUNC</a>(myplug)
{
<a class="code" href="group___config.html#ga6c621ab8875a222e1fcb56e9feed6ec6" title="Type for a configuration compound iterator.">snd_config_iterator_t</a> i, next;
<a class="code" href="group___config.html#ga1c20905af775ae77d04d1a5696f67985" title="Internal structure for a configuration node object.">snd_config_t</a> *slave = NULL;
<span class="keyword">struct </span>myplug_info *myplug;
<span class="keywordtype">int</span> err;
<a class="code" href="group___config.html#gac3f21333e1f9b602cad9b06cb418fa80" title="Helper macro to iterate over the children of a compound node.">snd_config_for_each</a>(i, next, conf) {
<a class="code" href="group___config.html#ga1c20905af775ae77d04d1a5696f67985" title="Internal structure for a configuration node object.">snd_config_t</a> *n = <a class="code" href="group___config.html#gaa91fe1d926d88041ed516a6a7293f606" title="Returns the configuration node handle pointed to by an iterator.">snd_config_iterator_entry</a>(i);
<span class="keyword">const</span> <span class="keywordtype">char</span> *id;
<span class="keywordflow">if</span> (<a class="code" href="group___config.html#gae366751e8ea98aeb69f9ef876f7b949c" title="Returns the id of a configuration node.">snd_config_get_id</a>(n, &<span class="keywordtype">id</span>) < 0)
<span class="keywordflow">continue</span>;
<span class="keywordflow">if</span> (strcmp(<span class="keywordtype">id</span>, <span class="stringliteral">"comment"</span>) == 0 || strcmp(<span class="keywordtype">id</span>, <span class="stringliteral">"type"</span>) == 0)
<span class="keywordflow">continue</span>;
<span class="keywordflow">if</span> (strcmp(<span class="keywordtype">id</span>, <span class="stringliteral">"slave"</span>) == 0) {
slave = n;
<span class="keywordflow">continue</span>;
}
<span class="keywordflow">if</span> (strcmp(<span class="keywordtype">id</span>, <span class="stringliteral">"my_own_parameter"</span>) == 0) {
....
<span class="keywordflow">continue</span>;
}
<a class="code" href="group___error.html#ga281420eb1344fe9f01d67d20c92457f0">SNDERR</a>(<span class="stringliteral">"Unknown field %s"</span>, <span class="keywordtype">id</span>);
<span class="keywordflow">return</span> -EINVAL;
}
<span class="keywordflow">if</span> (! slave) {
<a class="code" href="group___error.html#ga281420eb1344fe9f01d67d20c92457f0">SNDERR</a>(<span class="stringliteral">"No slave defined for myplug"</span>);
<span class="keywordflow">return</span> -EINVAL;
}
myplug = calloc(1, <span class="keyword">sizeof</span>(*myplug));
<span class="keywordflow">if</span> (myplug == NULL)
<span class="keywordflow">return</span> -ENOMEM;
myplug->ext.version = <a class="code" href="group___p_c_m___ext_plug.html#ga24d0ae71d106f08685d9ba8c6cf5fe78">SND_PCM_EXTPLUG_VERSION</a>;
myplug->ext.name = <span class="stringliteral">"My Own Plugin"</span>;
myplug->ext.callback = &my_own_callback;
myplug->ext.private_data = myplug;
....
err = <a class="code" href="group___p_c_m___ext_plug.html#gab0b27889f74c83cd033062981320fd62" title="Create an extplug instance.">snd_pcm_extplug_create</a>(&myplug->ext, name, root, conf, stream, mode);
<span class="keywordflow">if</span> (err < 0) {
myplug_free(myplug);
<span class="keywordflow">return</span> err;
}
*pcmp = myplug->ext.pcm;
<span class="keywordflow">return</span> 0;
}
<a class="code" href="group___plugin___s_d_k.html#ga73a613cc5b7b3642f53bbd5a1d78004b">SND_PCM_PLUGIN_SYMBOL</a>(myplug);
</pre></div><p>Read the codes in alsa-plugins package for the real examples.</p>
<h2><a class="anchor" id="pcm_extplug">
External Plugin: Filter-Type Plugin</a></h2>
<p>The filter-type plugin is a plugin to convert the PCM signals from the input and feeds to the output. Thus, this plugin always needs a slave PCM as its output.</p>
<p>The plugin can modify the format and the channels of the input/output PCM. It can <em>not</em> modify the sample rate (because of simplicity reason).</p>
<p>The following fields have to be filled in extplug record before calling <a class="el" href="group___p_c_m___ext_plug.html#gab0b27889f74c83cd033062981320fd62" title="Create an extplug instance.">snd_pcm_extplug_create()</a> : version, name, callback. Otherfields are optional and should be initialized with zero.</p>
<p>The constant <a class="el" href="group___p_c_m___ext_plug.html#ga24d0ae71d106f08685d9ba8c6cf5fe78">SND_PCM_EXTPLUG_VERSION</a> must be passed to the version field for the version check in alsa-lib. A non-NULL ASCII string has to be passed to the name field. The callback field contains the table of callback functions for this plugin (defined as snd_pcm_extplug_callback_t).</p>
<p>The driver can set an arbitrary value (pointer) to private_data field to refer its own data in the callbacks.</p>
<p>The rest fields are filled by <a class="el" href="group___p_c_m___ext_plug.html#gab0b27889f74c83cd033062981320fd62" title="Create an extplug instance.">snd_pcm_extplug_create()</a>. The pcm field is the resultant PCM handle. The others are the current status of the PCM.</p>
<p>The callback functions in snd_pcm_extplug_callback_t define the real behavior of the driver. At least, transfer callback must be given. This callback is called at each time certain size of data block is transfered to the slave PCM. Other callbacks are optional.</p>
<p>The close callback is called when the PCM is closed. If the plugin allocates private resources, this is the place to release them again. The hw_params and hw_free callbacks are called at <a class="el" href="group___p_c_m.html#ga1ca0dc120a484965e26cabf966502330" title="Install one PCM hardware configuration chosen from a configuration space and snd_pcm_prepare...">snd_pcm_hw_params()</a> and <a class="el" href="group___p_c_m.html#ga242ad0a269c272830d30666220edbc2a" title="Remove PCM hardware configuration and free associated resources.">snd_pcm_hw_free()</a> API calls, respectively. The last, dump callback, is called for printing the information of the given plugin.</p>
<p>The init callback is called when the PCM is at prepare state or any initialization is issued. Use this callback to reset the PCM instance to a sane initial state.</p>
<p>The hw_params constraints can be defined via either <a class="el" href="group___p_c_m___ext_plug.html#gabef139bbe5db265433fd5310d0faad4d" title="Set master parameter as the min/max values.">snd_pcm_extplug_set_param_minmax()</a> and <a class="el" href="group___p_c_m___ext_plug.html#gadbf27adba1a7cd0195b6ac750bb11bf7" title="Set master parameter as the list.">snd_pcm_extplug_set_param_list()</a> functions after calling <a class="el" href="group___p_c_m___ext_plug.html#gab0b27889f74c83cd033062981320fd62" title="Create an extplug instance.">snd_pcm_extplug_create()</a>. The former defines the minimal and maximal acceptable values for the given hw_params parameter (SND_PCM_EXTPLUG_HW_XXX). This function can't be used for the format parameter. The latter function specifies the available parameter values as the list. As mentioned above, the rate can't be changed. Only changeable parameters are sample format and channels.</p>
<p>To define the constraints of the slave PCM configuration, use either <a class="el" href="group___p_c_m___ext_plug.html#gad3cac0ee15293f349220a75cce69a51e" title="Set slave parameter as the min/max values.">snd_pcm_extplug_set_slave_param_minmax()</a> and <a class="el" href="group___p_c_m___ext_plug.html#gad14f6746e36d556c7a7937633b965ca7" title="Set slave parameter as the list.">snd_pcm_extplug_set_slave_param_list()</a>. The arguments are as same as former functions.</p>
<p>To clear the parameter constraints, call <a class="el" href="group___p_c_m___ext_plug.html#gacef181565eb697397ce41c1aab381777" title="Reset extplug parameters.">snd_pcm_extplug_params_reset()</a> function.</p>
<h2><a class="anchor" id="pcm_ioplug">
External Plugin: I/O Plugin</a></h2>
<p>The I/O-type plugin is a PCM plugin to work as the input or output terminal point, i.e. as a user-space PCM driver.</p>
<p>The new plugin is created via <a class="el" href="group___p_c_m___i_o_plug.html#ga7fb5213a5e776246e2b4dc53ec8d7604" title="Create an ioplug instance.">snd_pcm_ioplug_create()</a> function. The first argument is a pointer of the pluging information. Some of this struct must be initialized in prior to call <a class="el" href="group___p_c_m___i_o_plug.html#ga7fb5213a5e776246e2b4dc53ec8d7604" title="Create an ioplug instance.">snd_pcm_ioplug_create()</a>. Then the function fills other fields in return. The rest arguments, name, stream and mode, are usually identical with the values passed from the ALSA plugin constructor.</p>
<p>The following fields are mandatory: version, name, callback. Otherfields are optional and should be initialized with zero.</p>
<p>The constant <a class="el" href="group___p_c_m___i_o_plug.html#ga81a2273c4df9be29d91e6e2a0860d991">SND_PCM_IOPLUG_VERSION</a> must be passed to the version field for the version check in alsa-lib. A non-NULL ASCII string has to be passed to the name field. The callback field contains the table of callback functions for this plugin (defined as snd_pcm_ioplug_callback_t).</p>
<p>flags field specifies the optional bit-flags. poll_fd and poll_events specify the poll file descriptor and the corresponding poll events (POLLIN, POLLOUT) for the plugin. If the plugin requires multiple poll descriptors or poll descriptor(s) dynamically varying, set poll_descriptors and poll_descriptors_count callbacks to the callback table. Then the poll_fd and poll_events field are ignored.</p>
<p>mmap_rw specifies whether the plugin behaves in the pseudo mmap mode. When this value is set to 1, the plugin creates always a local buffer and performs read/write calls using this buffer as if it's mmapped. The address of local buffer can be obtained via <a class="el" href="group___p_c_m___i_o_plug.html#gac3b666ff286745c9eb24de3e3930970a" title="Get mmap area of ioplug.">snd_pcm_ioplug_mmap_areas()</a> function. When poll_fd, poll_events and mmap_rw fields are changed after <a class="el" href="group___p_c_m___i_o_plug.html#ga7fb5213a5e776246e2b4dc53ec8d7604" title="Create an ioplug instance.">snd_pcm_ioplug_create()</a>, call <a class="el" href="group___p_c_m___i_o_plug.html#gab223893226ecf78f675c89959a8c421a" title="Reinitialize the poll and mmap status.">snd_pcm_ioplug_reinit_status()</a> to reflect the changes.</p>
<p>The driver can set an arbitrary value (pointer) to private_data field to refer its own data in the callbacks.</p>
<p>The rest fields are filled by <a class="el" href="group___p_c_m___i_o_plug.html#ga7fb5213a5e776246e2b4dc53ec8d7604" title="Create an ioplug instance.">snd_pcm_ioplug_create()</a>. The pcm field is the resultant PCM handle. The others are the current status of the PCM.</p>
<p>The callback functions in snd_pcm_ioplug_callback_t define the real behavior of the driver. At least, start, stop and pointer callbacks must be given. Other callbacks are optional. The start and stop callbacks are called when the PCM stream is started and stopped, repsectively. The pointer callback returns the current DMA position, which may be called at any time.</p>
<p>The transfer callback is called when any data transfer happens. It receives the area array, offset and the size to transfer. The area array contains the array of <a class="el" href="structsnd__pcm__channel__area__t.html">snd_pcm_channel_area_t</a> with the elements of number of channels.</p>
<p>When the PCM is closed, close callback is called. If the driver allocates any internal buffers, they should be released in this callback. The hw_params and hw_free callbacks are called when hw_params are set and reset, respectively. Note that they may be called multiple times according to the application. Similarly, sw_params callback is called when sw_params is set or changed.</p>
<p>The prepare, drain, pause and resume callbacks are called when <a class="el" href="group___p_c_m.html#ga788d05de75f2d536f8443cb0306754d0" title="Prepare PCM for use.">snd_pcm_prepare()</a>, <a class="el" href="group___p_c_m.html#ga49afc5b8527f30c33fafa476533c9f86" title="Stop a PCM preserving pending frames.">snd_pcm_drain()</a>, <a class="el" href="group___p_c_m.html#gad711b582c7066bd4fffa1d08a04316b5" title="Pause/resume PCM.">snd_pcm_pause()</a>, and <a class="el" href="group___p_c_m.html#ga13083ce2209aab9ea73831610bc61ab1" title="Resume from suspend, no samples are lost.">snd_pcm_resume()</a> are called. The poll_descriptors_count and poll_descriptors callbacks are used to return the multiple or dynamic poll descriptors as mentioned above. The poll_revents callback is used to modify poll events. If the driver needs to mangle the native poll events to proper poll events for PCM, you can do it in this callback.</p>
<p>Finally, the dump callback is used to print the status of the plugin.</p>
<p>The hw_params constraints can be defined via either <a class="el" href="group___p_c_m___i_o_plug.html#gab62d470b02661214319196394b55fb37" title="Set parameter as the min/max values.">snd_pcm_ioplug_set_param_minmax()</a> and <a class="el" href="group___p_c_m___i_o_plug.html#ga7d713552fb846ccdf4b7ec6a9fc1b562" title="Set parameter as the list.">snd_pcm_ioplug_set_param_list()</a> functions after calling <a class="el" href="group___p_c_m___i_o_plug.html#ga7fb5213a5e776246e2b4dc53ec8d7604" title="Create an ioplug instance.">snd_pcm_ioplug_create()</a>. The former defines the minimal and maximal acceptable values for the given hw_params parameter (SND_PCM_IOPLUG_HW_XXX). This function can't be used for the format parameter. The latter function specifies the available parameter values as the list.</p>
<p>To clear the parameter constraints, call <a class="el" href="group___p_c_m___i_o_plug.html#gad74355dfaa56fae80d49181c83eeecc4" title="Reset ioplug parameters.">snd_pcm_ioplug_params_reset()</a> function. </p>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Defines</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr class="footer"/><address style="text-align: right;"><small>Generated on Sat Nov 20 07:42:24 2010 for ALSA project - the C library reference by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
</body>
</html>
