| Current File : //proc/thread-self/root/kunden/usr/share/doc/alsa-lib-devel/doxygen/html/control.html |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://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"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>ALSA project - the C library reference: Control interface</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">ALSA project - the C library reference
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Index, Preamble and License</a></li> </ul>
</div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Control interface </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Control interface is designed to access primitive controls. There is also an interface for notifying about control and structure changes.</p>
<h1><a class="anchor" id="control_general_overview"></a>
General overview</h1>
<p>In Alsa, there are physical sound cards, such as USB headsets, and virtual sound cards, such as "pulse", which represents the PulseAudio Sound system. Each sound card offers a control interface, making its settings (e.g. volume knobs) available. The complete list of available control interfaces can be obtained using <a class="el" href="group___hint.html#gadf4ce9117fcfa454c523ed6e6bd8b353" title="Get a set of device name hints.">snd_device_name_hint()</a>, giving -1 as card index and "ctl" as interface type. Each returned NAME hint identifies a control interface.</p>
<p>Sound cards have an ID (a string), an index (an int, sometimes called the "card number"), a name, a longname, a mixername and a "components" property. The file /proc/asound/cards lists most of these properties for physical sound cards. Virtual sound cards are not listed in that file. The format is:</p>
<pre class="fragment">index [ID ] Driver - name
longname
</pre><p>Note that the mixername and components are not listed.</p>
<h2><a class="anchor" id="control_cards_id"></a>
Identifying and Opening Control Interfaces</h2>
<p>To work with a control interface, is must be opened first, using <a class="el" href="group___control.html#ga58537f5b74c9c1f51699f9908a0d7f56" title="Opens a sound card.">snd_ctl_open()</a>. This function takes the interface name.</p>
<p>For physical sound cards, the control interface can be identified using the string "hw:<index>" (e.g. <code>hw:2</code>). The NAME hint - which is "hw:CARD=<ID>" - can also be used. Further, its device file (something like <code>/dev/snd/controlC0</code>) is also acceptable. Either of them can be given to <a class="el" href="group___control.html#ga58537f5b74c9c1f51699f9908a0d7f56" title="Opens a sound card.">snd_ctl_open()</a>.</p>
<p>For virtual sound cards, the NAME hint is given to <a class="el" href="group___control.html#ga58537f5b74c9c1f51699f9908a0d7f56" title="Opens a sound card.">snd_ctl_open()</a>.</p>
<p>The functions <a class="el" href="group___control.html#ga1881c5c04a532f5b9397745731ce7730" title="Convert a card string to the card index.">snd_card_get_index()</a>, <a class="el" href="group___control.html#gad48d44da8e3bfe150e928267008b8ff5" title="Obtain the card name.">snd_card_get_name()</a> and <a class="el" href="group___control.html#ga547dcead4a72f24db4a0f9f530f75228" title="Obtain the card long name.">snd_card_get_longname()</a> can be used to find an identifying property when another one is already known.</p>
<h1><a class="anchor" id="control_elements"></a>
Elements</h1>
<p>In ALSA control feature, each sound card can have control elements. The elements are managed according to below model.</p>
<ul>
<li>Element set<ul>
<li>A set of elements with the same attribute (i.e. name, get/put operations). Some element sets can be added to a sound card by drivers in kernel and userspace applications.</li>
</ul>
</li>
<li>Element<ul>
<li>A control element might be a master volume control, for example, or a read-only indicator, such as a sync status. An element has a type (e.g. SNDRV_CTL_ELEM_TYPE_INTEGER or SNDRV_CTL_ELEM_TYPE_BOOLEAN) and - depending on the type - min/max values, a step size, a set of possible values (for enums), etc.</li>
</ul>
</li>
<li>Member<ul>
<li>An element usually includes one or more member(s) to have a value. For example, a stereo volume control element has two members (for left/right), while a mono volume has only one member. The member count can be obtained using <a class="el" href="group___control.html#gaa75a20d4190d324bcda5fd6659a4b377" title="Get number of value entries from a CTL element id/info.">snd_ctl_elem_info_get_count()</a>. Elements of type "SNDRV_CTL_ELEM_TYPE_BYTES" or "SNDRV_CTL_ELEM_TYPE_IEC958" have no members at all (and thus no member count), they have just a single value. The members share the same properties (e.g. both volume control members have the same min/max values). The value of each member can be changed by both of userspace applications and drivers in kernel.</li>
</ul>
</li>
</ul>
<h2><a class="anchor" id="identifying_elements"></a>
Identifying Elements</h2>
<p>Each element has the following identifying properties:</p>
<ul>
<li>The numid (a numeric identifier, assigned when the sound card is detected, constant while the sound card is kept connected)</li>
<li>The interface type (e.g. MIXER, CARD or PCM)</li>
<li>The device</li>
<li>The subdevice</li>
<li>Its name</li>
<li>Its index</li>
</ul>
<p>An element can be identified either by its short numid or by the full set of fields (interface type, device, subdevice, name, index). This set of fields is always the same (driver updates can change it, but in practice this is rare). The numid can change on each boot. In case of an USB sound card, the numid can also change when it is reconnected. The short numid is used to reduce the lookup time.</p>
<h2><a class="anchor" id="element_lists"></a>
Element Lists</h2>
<p>An element list can be used to obtain a list of all elements of the sound card. The list contains generic information (e.g. how many elements the card has), and the identifying properties of the elements (numid, card, name, ...). See <a class="el" href="group___control.html#ga952c52ef86124847f9bf12ee3dbfa5a3">snd_ctl_elem_list_t</a> to learn more about element lists.</p>
<h2><a class="anchor" id="working_with_elements"></a>
Working with Elements</h2>
<p>It is possible to obtain information about an element using the snd_ctl_elem_info_*() functions. For enums, the allowed values can be obtained, for integers, the min/max values can be obtained, and so on. In addition, these functions can report the identifying properties. E.g. when the element is addressed using its numid, the functions complements the name, index, etc.</p>
<p>To access the members (i.e. values) of a control, use the snd_ctl_elem_value*() functions. These allow to get and set the actual values or settings. It is also possible to get and set the ID values (such as the numid or the name).</p>
<h2><a class="anchor" id="element_sets"></a>
Element Sets</h2>
<p>The type of element set is one of integer, integer64, boolean, enumerators, bytes and IEC958 structure. This indicates the type of value for each member in elements included in the element set.</p>
<h1><a class="anchor" id="events"></a>
Events</h1>
<p>When the value of a member is changed, corresponding events are transferred to userspace applications. The applications should subscribe any events in advance.</p>
<h1><a class="anchor" id="tlv_blob"></a>
Supplemental data for elements in an element set</h1>
<p>TLV feature is designed to transfer data in a shape of Type/Length/Value, between a driver and any userspace applications. The main purpose is to attach supplement information for elements to an element set; e.g. dB range.</p>
<p>At first, this feature was implemented to add pre-defined data readable to userspace applications. Soon, it was extended to handle several operations; read, write and command. The original implementation remains as the read operation. The command operation allows drivers to have own implementations against requests from userspace applications.</p>
<p>This feature was introduced to ALSA control feature in 2006, at commit c7a0708a2362, corresponding to a series of work for Linux kernel (42750b04c5ba and 8aa9b586e420).</p>
<p>There's no limitation about maximum size of the data, therefore it can be used to deliver quite large arbitrary data from userspace to in-kernel drivers via ALSA control character device. Focusing on this nature, as of 2016, some in-kernel implementations utilize this feature for I/O operations. This is against the original design. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>