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="control-interface.html" title="Chapter 6. Control Interface"><link rel="prev" href="control-interface-access-flags.html" title="Access Flags"><link rel="next" href="control-interface-constructor.html" title="Constructor"></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="control-interface-access-flags.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Control Interface</th><td width="20%" align="right"> <a accesskey="n" href="control-interface-constructor.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="control-interface-callbacks"></a>Callbacks</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="control-interface-callbacks.html#control-interface-callbacks-info">info callback</a></span></dt><dt><span class="section"><a href="control-interface-callbacks.html#control-interface-callbacks-get">get callback</a></span></dt><dt><span class="section"><a href="control-interface-callbacks.html#control-interface-callbacks-put">put callback</a></span></dt><dt><span class="section"><a href="control-interface-callbacks.html#control-interface-callbacks-all">Callbacks are not atomic</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="control-interface-callbacks-info"></a>info callback</h3></div></div></div><p> 2 The <em class="structfield"><code>info</code></em> callback is used to get 3 detailed information on this control. This must store the 4 values of the given struct <span class="structname">snd_ctl_elem_info</span> 5 object. For example, for a boolean control with a single 6 element: 7 8 </p><div class="example"><a name="idp1094193780"></a><p class="title"><b>Example 6.2. Example of info callback</b></p><div class="example-contents"><pre class="programlisting"> 9 10 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol, 11 struct snd_ctl_elem_info *uinfo) 12 { 13 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN; 14 uinfo->count = 1; 15 uinfo->value.integer.min = 0; 16 uinfo->value.integer.max = 1; 17 return 0; 18 } 19 20 </pre></div></div><p><br class="example-break"> 21 </p><p> 22 The <em class="structfield"><code>type</code></em> field specifies the type 23 of the control. There are <code class="constant">BOOLEAN</code>, 24 <code class="constant">INTEGER</code>, <code class="constant">ENUMERATED</code>, 25 <code class="constant">BYTES</code>, <code class="constant">IEC958</code> and 26 <code class="constant">INTEGER64</code>. The 27 <em class="structfield"><code>count</code></em> field specifies the 28 number of elements in this control. For example, a stereo 29 volume would have count = 2. The 30 <em class="structfield"><code>value</code></em> field is a union, and 31 the values stored are depending on the type. The boolean and 32 integer types are identical. 33 </p><p> 34 The enumerated type is a bit different from others. You'll 35 need to set the string for the currently given item index. 36 37 </p><div class="informalexample"><pre class="programlisting"> 38 39 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, 40 struct snd_ctl_elem_info *uinfo) 41 { 42 static char *texts[4] = { 43 "First", "Second", "Third", "Fourth" 44 }; 45 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED; 46 uinfo->count = 1; 47 uinfo->value.enumerated.items = 4; 48 if (uinfo->value.enumerated.item > 3) 49 uinfo->value.enumerated.item = 3; 50 strcpy(uinfo->value.enumerated.name, 51 texts[uinfo->value.enumerated.item]); 52 return 0; 53 } 54 55 </pre></div><p> 56 </p><p> 57 The above callback can be simplified with a helper function, 58 <code class="function">snd_ctl_enum_info</code>. The final code 59 looks like below. 60 (You can pass ARRAY_SIZE(texts) instead of 4 in the third 61 argument; it's a matter of taste.) 62 63 </p><div class="informalexample"><pre class="programlisting"> 64 65 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, 66 struct snd_ctl_elem_info *uinfo) 67 { 68 static char *texts[4] = { 69 "First", "Second", "Third", "Fourth" 70 }; 71 return snd_ctl_enum_info(uinfo, 1, 4, texts); 72 } 73 74 </pre></div><p> 75 </p><p> 76 Some common info callbacks are available for your convenience: 77 <code class="function">snd_ctl_boolean_mono_info()</code> and 78 <code class="function">snd_ctl_boolean_stereo_info()</code>. 79 Obviously, the former is an info callback for a mono channel 80 boolean item, just like <code class="function">snd_myctl_mono_info</code> 81 above, and the latter is for a stereo channel boolean item. 82 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="control-interface-callbacks-get"></a>get callback</h3></div></div></div><p> 83 This callback is used to read the current value of the 84 control and to return to user-space. 85 </p><p> 86 For example, 87 88 </p><div class="example"><a name="idp1094203812"></a><p class="title"><b>Example 6.3. Example of get callback</b></p><div class="example-contents"><pre class="programlisting"> 89 90 static int snd_myctl_get(struct snd_kcontrol *kcontrol, 91 struct snd_ctl_elem_value *ucontrol) 92 { 93 struct mychip *chip = snd_kcontrol_chip(kcontrol); 94 ucontrol->value.integer.value[0] = get_some_value(chip); 95 return 0; 96 } 97 98 </pre></div></div><p><br class="example-break"> 99 </p><p> 100 The <em class="structfield"><code>value</code></em> field depends on 101 the type of control as well as on the info callback. For example, 102 the sb driver uses this field to store the register offset, 103 the bit-shift and the bit-mask. The 104 <em class="structfield"><code>private_value</code></em> field is set as follows: 105 </p><div class="informalexample"><pre class="programlisting"> 106 107 .private_value = reg | (shift << 16) | (mask << 24) 108 109 </pre></div><p> 110 and is retrieved in callbacks like 111 </p><div class="informalexample"><pre class="programlisting"> 112 113 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol, 114 struct snd_ctl_elem_value *ucontrol) 115 { 116 int reg = kcontrol->private_value & 0xff; 117 int shift = (kcontrol->private_value >> 16) & 0xff; 118 int mask = (kcontrol->private_value >> 24) & 0xff; 119 .... 120 } 121 122 </pre></div><p> 123 </p><p> 124 In the <em class="structfield"><code>get</code></em> callback, 125 you have to fill all the elements if the 126 control has more than one elements, 127 i.e. <em class="structfield"><code>count</code></em> > 1. 128 In the example above, we filled only one element 129 (<em class="structfield"><code>value.integer.value[0]</code></em>) since it's 130 assumed as <em class="structfield"><code>count</code></em> = 1. 131 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="control-interface-callbacks-put"></a>put callback</h3></div></div></div><p> 132 This callback is used to write a value from user-space. 133 </p><p> 134 For example, 135 136 </p><div class="example"><a name="idp1094210188"></a><p class="title"><b>Example 6.4. Example of put callback</b></p><div class="example-contents"><pre class="programlisting"> 137 138 static int snd_myctl_put(struct snd_kcontrol *kcontrol, 139 struct snd_ctl_elem_value *ucontrol) 140 { 141 struct mychip *chip = snd_kcontrol_chip(kcontrol); 142 int changed = 0; 143 if (chip->current_value != 144 ucontrol->value.integer.value[0]) { 145 change_current_value(chip, 146 ucontrol->value.integer.value[0]); 147 changed = 1; 148 } 149 return changed; 150 } 151 152 </pre></div></div><p><br class="example-break"> 153 154 As seen above, you have to return 1 if the value is 155 changed. If the value is not changed, return 0 instead. 156 If any fatal error happens, return a negative error code as 157 usual. 158 </p><p> 159 As in the <em class="structfield"><code>get</code></em> callback, 160 when the control has more than one elements, 161 all elements must be evaluated in this callback, too. 162 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="control-interface-callbacks-all"></a>Callbacks are not atomic</h3></div></div></div><p> 163 All these three callbacks are basically not atomic. 164 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="control-interface-access-flags.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="control-interface.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="control-interface-constructor.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Access Flags </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Constructor</td></tr></table></div></body></html> 165