alsactl_init.xml (26262B)
1 <?xml version='1.0'?> 2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4 5 <article> 6 <section> 7 <title>alsactl init</title> 8 <refentry> 9 <refentryinfo> 10 <title>alsactl init</title> 11 <date>July 2008</date> 12 <productname>alsactl</productname> 13 </refentryinfo> 14 15 <refmeta> 16 <refentrytitle>alsactl_init</refentrytitle> 17 <manvolnum>7</manvolnum> 18 <refmiscinfo class="version"></refmiscinfo> 19 </refmeta> 20 21 <refnamediv> 22 <refname>alsactl init</refname> 23 <refpurpose>alsa control management - initialization</refpurpose> 24 </refnamediv> 25 26 <refsect1><title>DESCRIPTION</title> 27 <para>"alsactl init" provides soundcard specific initialization.</para> 28 </refsect1> 29 30 <refsect1><title>CONFIGURATION</title> 31 <para>All "alsactl init" configuration files are placed in 32 <filename>/usr/share/alsa/init/</filename> directory. The top level 33 configuration file is <filename>/usr/share/alsa/init/00main</filename>. 34 The default top-level file can be also specified using -i or 35 --initfile parameter for the alsactl tool. 36 Every file consists of a set of lines of text. All empty lines or 37 lines beginning with '#' will be ignored.</para> 38 39 <refsect2><title>Rules files</title> 40 <para>The "alsactl init" rules are read from the files located 41 in the <filename>/usr/share/alsa/init/*</filename>. The top 42 level configuration file is <filename>/usr/share/alsa/init/00main</filename>. 43 Every line in the rules file contains at least one key value pair. 44 There are two kind of keys, match and assignment keys. If all match 45 keys are matching against its value, the rule gets applied and the 46 assign keys get the specified value assigned.</para> 47 48 <para>A rule may consists of a list of one or more key value pairs 49 separated by a comma. Each key has a distinct operation, depending 50 on the used operator. Valid operators are:</para> 51 <variablelist> 52 <varlistentry> 53 <term><option>==</option></term> 54 <listitem> 55 <para>Compare for equality.</para> 56 </listitem> 57 </varlistentry> 58 59 <varlistentry> 60 <term><option>!=</option></term> 61 <listitem> 62 <para>Compare for non-equality.</para> 63 </listitem> 64 </varlistentry> 65 66 <varlistentry> 67 <term><option>=</option></term> 68 <listitem> 69 <para>Assign a value to a key. Keys that represent a list, 70 are reset and only this single value is assigned.</para> 71 </listitem> 72 </varlistentry> 73 74 <varlistentry> 75 <term><option>+=</option></term> 76 <listitem> 77 <para>Add the value to a key that holds a list 78 of entries.</para> 79 </listitem> 80 </varlistentry> 81 82 <varlistentry> 83 <term><option>:=</option></term> 84 <listitem> 85 <para>Assign a value to a key finally; disallow any 86 later changes, which may be used to prevent changes by 87 any later rules.</para> 88 </listitem> 89 </varlistentry> 90 </variablelist> 91 92 <para>The following key names can be used to match against device 93 properties:</para> 94 <variablelist> 95 <varlistentry> 96 <term><option>CARDINDEX</option></term> 97 <listitem> 98 <para>Match the card index of the ALSA driver.</para> 99 </listitem> 100 </varlistentry> 101 102 <varlistentry> 103 <term><option>CTL{<replaceable>attribute</replaceable>}</option></term> 104 <listitem> 105 <para>Set or test universal control attribute. Possible 106 attributes:</para> 107 <variablelist> 108 <varlistentry> 109 <term><option>numid</option></term> 110 <listitem> 111 <para>Numeric control identification.</para> 112 </listitem> 113 </varlistentry> 114 <varlistentry> 115 <term><option>iface</option>, <option>interface</option></term> 116 <listitem> 117 <para>Control interface name (CARD, HWEDEP, MIXER, PCM, RAWMIDI, TIMER, SEQUENCER)</para> 118 </listitem> 119 </varlistentry> 120 <varlistentry> 121 <term><option>subdev</option>, <option>subdevice</option></term> 122 <listitem> 123 <para>Subdevice number.</para> 124 </listitem> 125 </varlistentry> 126 <varlistentry> 127 <term><option>name</option></term> 128 <listitem> 129 <para>Control name</para> 130 </listitem> 131 </varlistentry> 132 <varlistentry> 133 <term><option>index</option></term> 134 <listitem> 135 <para>Control index</para> 136 </listitem> 137 </varlistentry> 138 <varlistentry> 139 <term><option>type</option></term> 140 <listitem> 141 <para>Control type (BOOLEAN, INTEGER, INTEGER64, ENUMERATED, BYTES, IEC958)</para> 142 </listitem> 143 </varlistentry> 144 <varlistentry> 145 <term><option>attr</option>, <option>attribute</option></term> 146 <listitem> 147 <para>Attributes (stored in a string - use match characters * and ?):</para> 148 <variablelist> 149 <varlistentry> 150 <term><option>r</option></term> 151 <listitem> 152 <para>control is readable</para> 153 </listitem> 154 </varlistentry> 155 <varlistentry> 156 <term><option>w</option></term> 157 <listitem> 158 <para>control is writable</para> 159 </listitem> 160 </varlistentry> 161 <varlistentry> 162 <term><option>v</option></term> 163 <listitem> 164 <para>control is volatile</para> 165 </listitem> 166 </varlistentry> 167 <varlistentry> 168 <term><option>i</option></term> 169 <listitem> 170 <para>control is inactive</para> 171 </listitem> 172 </varlistentry> 173 <varlistentry> 174 <term><option>l</option></term> 175 <listitem> 176 <para>control is locked</para> 177 </listitem> 178 </varlistentry> 179 <varlistentry> 180 <term><option>R</option></term> 181 <listitem> 182 <para>control is TLV readable</para> 183 </listitem> 184 </varlistentry> 185 <varlistentry> 186 <term><option>W</option></term> 187 <listitem> 188 <para>control is TLV writable</para> 189 </listitem> 190 </varlistentry> 191 <varlistentry> 192 <term><option>C</option></term> 193 <listitem> 194 <para>control is TLV commandable</para> 195 </listitem> 196 </varlistentry> 197 <varlistentry> 198 <term><option>o</option></term> 199 <listitem> 200 <para>process is owner of this control</para> 201 </listitem> 202 </varlistentry> 203 <varlistentry> 204 <term><option>u</option></term> 205 <listitem> 206 <para>control created in user space</para> 207 </listitem> 208 </varlistentry> 209 </variablelist> 210 </listitem> 211 </varlistentry> 212 <varlistentry> 213 <term><option>owner</option></term> 214 <listitem> 215 <para>Control owner process PID number</para> 216 </listitem> 217 </varlistentry> 218 <varlistentry> 219 <term><option>count</option></term> 220 <listitem> 221 <para>Control count of values</para> 222 </listitem> 223 </varlistentry> 224 <varlistentry> 225 <term><option>min</option></term> 226 <listitem> 227 <para>Value range - minimum value</para> 228 </listitem> 229 </varlistentry> 230 <varlistentry> 231 <term><option>max</option></term> 232 <listitem> 233 <para>Value range - maximum value</para> 234 </listitem> 235 </varlistentry> 236 <varlistentry> 237 <term><option>step</option></term> 238 <listitem> 239 <para>Value range - step value</para> 240 </listitem> 241 </varlistentry> 242 <varlistentry> 243 <term><option>dBmin</option></term> 244 <listitem> 245 <para>Value range - minimum dB value</para> 246 </listitem> 247 </varlistentry> 248 <varlistentry> 249 <term><option>dBmax</option></term> 250 <listitem> 251 <para>Value range - maximum dB value</para> 252 </listitem> 253 </varlistentry> 254 <varlistentry> 255 <term><option>items</option></term> 256 <listitem> 257 <para>Enumerated value - number of text items</para> 258 </listitem> 259 </varlistentry> 260 <varlistentry> 261 <term><option>enums</option></term> 262 <listitem> 263 <para>Enumerated value - list of text names stored between '|' character</para> 264 </listitem> 265 </varlistentry> 266 <varlistentry> 267 <term><option>value</option></term> 268 <listitem> 269 <para>Value of control stored to a string delimited by 270 comma (,).</para> 271 </listitem> 272 </varlistentry> 273 <varlistentry> 274 <term><option>do_search</option></term> 275 <listitem> 276 <para>Search for a control. Value "1" is returned 277 if a control was found. The CTL{name} key might 278 contain match characters * and ?. An control index 279 might be specified as first argument starting from 280 zero (e.g. CTL{do_search 2}="1").</para> 281 </listitem> 282 </varlistentry> 283 <varlistentry> 284 <term><option>do_count</option></term> 285 <listitem> 286 <para>Search for a controls and return total count 287 of matched ones. The CTL{name} key might contain match 288 characters * and ?.</para> 289 </listitem> 290 </varlistentry> 291 </variablelist> 292 </listitem> 293 </varlistentry> 294 295 <varlistentry> 296 <term><option>CONFIG{sysfs_device}</option></term> 297 <listitem> 298 <para>The relative path to sysfs subsystem specifying 299 the root directory of a soundcard device. Usually, 300 it should be set to "/class/sound/card$cardinfo{card}/device". 301 </para> 302 </listitem> 303 </varlistentry> 304 305 <varlistentry> 306 <term><option>ATTR{<replaceable>filename</replaceable>}</option></term> 307 <listitem> 308 <para>Match sysfs attribute values of the soundcard device. 309 The relative path to sysfs tree must be defined by 310 CONFIG{sysfs_device} key. Trailing whitespace in the attribute 311 values is ignored, if the specified match value does 312 not contain trailing whitespace itself. Depending on 313 the type of operator, this key is also used to set 314 the value of a sysfs attribute. 315 </para> 316 </listitem> 317 </varlistentry> 318 319 <varlistentry> 320 <term><option>ENV{<replaceable>key</replaceable>}</option></term> 321 <listitem> 322 <para>Match against the value of an environment variable. Up 323 to five <option>ENV</option> keys can be specified per rule. 324 Depending on the type of operator, this key is also used 325 to export a variable to the environment.</para> 326 </listitem> 327 </varlistentry> 328 329 <varlistentry> 330 <term><option>PROGRAM</option></term> 331 <listitem> 332 <para>Execute external program. The key is true, if 333 the program returns without exit code zero. The whole event 334 environment is available to the executed program. The 335 program's output printed to stdout is available for 336 the RESULT key.</para> 337 <para>Several buildin commands are available:</para> 338 <variablelist> 339 <varlistentry> 340 <term><option>__ctl_search</option></term> 341 <listitem> 342 <para>Search for a control. The CTL{name} key might 343 contain match characters * and ?. An control index 344 might be specified as first argument starting from 345 zero (e.g. PROGRAM="__ctl_search 2").</para> 346 </listitem> 347 </varlistentry> 348 <varlistentry> 349 <term><option>__ctl_count</option></term> 350 <listitem> 351 <para>Search for a controls and return total count 352 of matched ones. The CTL{name} key might contain match 353 characters * and ?.</para> 354 </listitem> 355 </varlistentry> 356 </variablelist> 357 </listitem> 358 </varlistentry> 359 360 <varlistentry> 361 <term><option>RESULT</option></term> 362 <listitem> 363 <para>Match the returned string of the last PROGRAM call. 364 This key can be used in the same or in any later rule 365 after a PROGRAM call.</para> 366 </listitem> 367 </varlistentry> 368 369 </variablelist> 370 371 <para>Most of the fields support a shell style pattern matching. 372 The following pattern characters are supported:</para> 373 <variablelist> 374 <varlistentry> 375 <term><option>*</option></term> 376 <listitem> 377 <para>Matches zero, or any number of characters.</para> 378 </listitem> 379 </varlistentry> 380 <varlistentry> 381 <term><option>?</option></term> 382 <listitem> 383 <para>Matches any single character.</para> 384 </listitem> 385 </varlistentry> 386 <varlistentry> 387 <term><option>[]</option></term> 388 <listitem> 389 <para>Matches any single character specified within 390 the brackets. For example, the pattern string 'tty[SR]' 391 would match either 'ttyS' or 'ttyR'. Ranges are also 392 supported within this match with the '-' character. 393 For example, to match on the range of all digits, 394 the pattern [0-9] would be used. If the first character 395 following the '[' is a '!', any characters 396 not enclosed are matched.</para> 397 </listitem> 398 </varlistentry> 399 </variablelist> 400 401 <para>The following keys can get values assigned:</para> 402 <variablelist> 403 <varlistentry> 404 <term><option>CTL{numid}</option>, <option>CTL{iface}</option>, 405 <option>CTL{device}</option>, <option>CTL{subdev}</option>, 406 <option>CTL{name}</option>, <option>CTL{index}</option>, 407 </term> 408 <listitem> 409 <para>Select universal control element.</para> 410 </listitem> 411 </varlistentry> 412 <varlistentry> 413 <term><option>CTL{value}</option></term> 414 <listitem> 415 <para>Value is set (written) also to soundcard's control 416 device and RESULT key is set to errno code. The result of 417 set operation is always true (it means continue with 418 next key on line).</para> 419 </listitem> 420 </varlistentry> 421 <varlistentry> 422 <term><option>CTL{values}</option></term> 423 <listitem> 424 <para>Value is set (written) also to soundcard's control 425 device (all control values are set to specified value) and 426 RESULT key is set to errno code. The result of 427 set operation is always true (it means continue with 428 next key on line).</para> 429 </listitem> 430 </varlistentry> 431 <varlistentry> 432 <term><option>CTL{write}</option></term> 433 <listitem> 434 <para>Value is set (written) also to soundcard's control 435 device (all control values are set to specified value). 436 The result of set operation is true when operation 437 succeed (it means continue with next key on line).</para> 438 </listitem> 439 </varlistentry> 440 441 <varlistentry> 442 <term><option>ENV{<replaceable>key</replaceable>}</option></term> 443 <listitem> 444 <para>Export a variable to the environment. Depending on the type of operator, 445 this key is also to match against an environment variable.</para> 446 </listitem> 447 </varlistentry> 448 449 <varlistentry> 450 <term><option>RESULT</option></term> 451 <listitem> 452 <para>Set RESULT variable. Note that PROGRAM also sets 453 this variable, but setting this variable manually 454 might be useful to change code execution order (included 455 files).</para> 456 </listitem> 457 </varlistentry> 458 459 <varlistentry> 460 <term><option>LABEL</option></term> 461 <listitem> 462 <para>Named label where a GOTO can jump to.</para> 463 </listitem> 464 </varlistentry> 465 466 <varlistentry> 467 <term><option>GOTO</option></term> 468 <listitem> 469 <para>Jumps to the next LABEL with a matching name. 470 The goto cannot jump backward.</para> 471 </listitem> 472 </varlistentry> 473 474 <varlistentry> 475 <term><option>INCLUDE</option></term> 476 <listitem> 477 <para>Include the specified filename or files in specified directory. 478 </para> 479 <para> 480 When a directory is specified, only the files with the 481 extension ".conf" are read. 482 Also they are read in the alphabetical order. 483 Thus it's highly recommended to use some number prefix 484 (e.g. "01-something.conf") to assure the order of execucions. 485 </para> 486 </listitem> 487 </varlistentry> 488 489 <varlistentry> 490 <term><option>ACCESS</option></term> 491 <listitem> 492 <para>Check if specified file or directory exists</para> 493 </listitem> 494 </varlistentry> 495 496 <varlistentry> 497 <term><option>CONFIG{sysfs_device}</option></term> 498 <listitem> 499 <para>The relative path to sysfs subsystem specifying 500 the root directory of a soundcard device. Usually, 501 it should be set to "/class/sound/card$cardinfo{card}/device". 502 </para> 503 </listitem> 504 </varlistentry> 505 506 <varlistentry> 507 <term><option>PRINT</option></term> 508 <listitem> 509 <para>PRINT value to stdout.</para> 510 </listitem> 511 </varlistentry> 512 513 <varlistentry> 514 <term><option>ERROR</option></term> 515 <listitem> 516 <para>PRINT value to stderr.</para> 517 </listitem> 518 </varlistentry> 519 520 <varlistentry> 521 <term><option>EXIT</option></term> 522 <listitem> 523 <para>Exit immediately and set program exit code to value 524 (should be integer). If value is "return" string, 525 parser leaves current included file and returns to parent 526 configuration file.</para> 527 </listitem> 528 </varlistentry> 529 530 </variablelist> 531 532 <para>The <option>PROGRAM</option>, <option>RESULT</option>, 533 <option>CTL{value}</option>, 534 <option>PRINT</option>, <option>ERROR</option>, 535 <option>EXIT</option>, <option>CONFIG{}</option> 536 fields support simple printf-like string substitutions. 537 It allows the use of the complete environment set by earlier matching 538 rules. For all other fields, substitutions are applied while the individual rule is 539 being processed. The available substitutions are:</para> 540 <variablelist> 541 <varlistentry> 542 <term><option>$cardinfo{<replaceable>attribute</replaceable>}</option>, <option>%i{<replaceable>attribute</replaceable>}</option></term> 543 <listitem> 544 <para>See CARDINFO{} for more details.</para> 545 </listitem> 546 </varlistentry> 547 548 <varlistentry> 549 <term><option>$ctl{<replaceable>attribute</replaceable>}</option>, <option>%C{<replaceable>attribute</replaceable>}</option></term> 550 <listitem> 551 <para>See CTL{} for more details.</para> 552 </listitem> 553 </varlistentry> 554 555 <varlistentry> 556 <term><option>$attr{<replaceable>file</replaceable>}</option>, <option>%s{<replaceable>file</replaceable>}</option></term> 557 <listitem> 558 <para>The value of a sysfs attribute found at the device, where 559 all keys of the rule have matched. 560 If the attribute is a symlink, the last element of the symlink target is 561 returned as the value.</para> 562 </listitem> 563 </varlistentry> 564 565 <varlistentry> 566 <term><option>$env{<replaceable>key</replaceable>}</option>, <option>%E{<replaceable>key</replaceable>}</option></term> 567 <listitem> 568 <para>The value of an environment variable.</para> 569 </listitem> 570 </varlistentry> 571 572 <varlistentry> 573 <term><option>$result</option>, <option>%c</option></term> 574 <listitem> 575 <para>The string returned by the external program requested with PROGRAM. 576 A single part of the string, separated by a space character may be selected 577 by specifying the part number as an attribute: <option>%c{N}</option>. 578 If the number is followed by the '+' char this part plus all remaining parts 579 of the result string are substituted: <option>%c{N+}</option></para> 580 </listitem> 581 </varlistentry> 582 583 <varlistentry> 584 <term><option>$sysfsroot</option>, <option>%r</option></term> 585 <listitem> 586 <para>Root directory where sysfs file-system is mounted. 587 Ususally, this value is just "/sys".</para> 588 </listitem> 589 </varlistentry> 590 591 <varlistentry> 592 <term><option>$config{<replaceable>key</replaceable>}</option>, <option>%g{<replaceable>key</replaceable>}</option></term> 593 <listitem> 594 <para>The value of a configuration variable. See CONFIG{} for more details.</para> 595 </listitem> 596 </varlistentry> 597 598 <varlistentry> 599 <term><option>%%</option></term> 600 <listitem> 601 <para>The '%' character itself.</para> 602 </listitem> 603 </varlistentry> 604 605 <varlistentry> 606 <term><option>$$</option></term> 607 <listitem> 608 <para>The '$' character itself.</para> 609 </listitem> 610 </varlistentry> 611 </variablelist> 612 <para>The count of characters to be substituted may be limited 613 by specifying the format length value. For example, '%3s{file}' 614 will only insert the first three characters of the sysfs 615 attribute</para> 616 </refsect2> 617 </refsect1> 618 619 <refsect1><title>AUTHOR</title> 620 <para>Written by Jaroslav Kysela <email>perex@perex.cz</email></para> 621 <para>Some portions are written by Greg Kroah-Hartman <email>greg@kroah.com</email> and 622 Kay Sievers <email>kay.sievers@vrfy.org</email>.</para> 623 </refsect1> 624 625 <refsect1> 626 <title>SEE ALSO</title> 627 <para><citerefentry> 628 <refentrytitle>alsactl</refentrytitle><manvolnum>1</manvolnum> 629 </citerefentry></para> 630 </refsect1> 631 </refentry> 632 </section> 633 </article>