mirror of
https://github.com/alsa-project/alsa-utils
synced 2024-11-14 18:05:42 +01:00
a227f00690
To increase configuration readability, add CTL{do_search} and CTL{do_count}
actions. The old PROGRAM=="__ctl_search" notion is also allowed.
Add CTL{write} to XML documentation.
Signed-off-by: Jaroslav Kysela <perex@perex.cz>
625 lines
25 KiB
XML
625 lines
25 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<article>
|
|
<section>
|
|
<title>alsactl init</title>
|
|
<refentry>
|
|
<refentryinfo>
|
|
<title>alsactl init</title>
|
|
<date>July 2008</date>
|
|
<productname>alsactl</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>alsactl_init</refentrytitle>
|
|
<manvolnum>7</manvolnum>
|
|
<refmiscinfo class="version"></refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>alsactl init</refname>
|
|
<refpurpose>alsa control management - initialization</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1><title>DESCRIPTION</title>
|
|
<para>"alsactl init" provides soundcard specific initialization.</para>
|
|
</refsect1>
|
|
|
|
<refsect1><title>CONFIGURATION</title>
|
|
<para>All "alsactl init" configuration files are placed in
|
|
<filename>/usr/share/alsa/init/</filename> directory. The top level
|
|
configuration file is <filename>/usr/share/alsa/init/00main</filename>.
|
|
The default top-level file can be also specified using -i or
|
|
--initfile parameter for the alsactl tool.
|
|
Every file consists of a set of lines of text. All empty lines or
|
|
lines beginning with '#' will be ignored.</para>
|
|
|
|
<refsect2><title>Rules files</title>
|
|
<para>The "alsactl init" rules are read from the files located
|
|
in the <filename>/usr/share/alsa/init/*</filename>. The top
|
|
level configuration file is <filename>/usr/share/alsa/init/00main</filename>.
|
|
Every line in the rules file contains at least one key value pair.
|
|
There are two kind of keys, match and assignment keys. If all match
|
|
keys are matching against its value, the rule gets applied and the
|
|
assign keys get the specified value assigned.</para>
|
|
|
|
<para>A rule may consists of a list of one or more key value pairs
|
|
separated by a comma. Each key has a distinct operation, depending
|
|
on the used operator. Valid operators are:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>==</option></term>
|
|
<listitem>
|
|
<para>Compare for equality.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>!=</option></term>
|
|
<listitem>
|
|
<para>Compare for non-equality.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>=</option></term>
|
|
<listitem>
|
|
<para>Assign a value to a key. Keys that represent a list,
|
|
are reset and only this single value is assigned.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>+=</option></term>
|
|
<listitem>
|
|
<para>Add the value to a key that holds a list
|
|
of entries.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>:=</option></term>
|
|
<listitem>
|
|
<para>Assign a value to a key finally; disallow any
|
|
later changes, which may be used to prevent changes by
|
|
any later rules.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>The following key names can be used to match against device
|
|
properties:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>CARDINDEX</option></term>
|
|
<listitem>
|
|
<para>Match the card index of the ALSA driver.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>CTL{<replaceable>attribute</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>Set or test universal control attribute. Possible
|
|
attributes:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>numid</option></term>
|
|
<listitem>
|
|
<para>Numeric control identification.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>iface</option>, <option>interface</option></term>
|
|
<listitem>
|
|
<para>Control interface name (CARD, HWEDEP, MIXER, PCM, RAWMIDI, TIMER, SEQUENCER)</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>subdev</option>, <option>subdevice</option></term>
|
|
<listitem>
|
|
<para>Subdevice number.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>name</option></term>
|
|
<listitem>
|
|
<para>Control name</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>index</option></term>
|
|
<listitem>
|
|
<para>Control index</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>type</option></term>
|
|
<listitem>
|
|
<para>Control type (BOOLEAN, INTEGER, INTEGER64, ENUMERATED, BYTES, IEC958)</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>attr</option>, <option>attribute</option></term>
|
|
<listitem>
|
|
<para>Attributes (stored in a string - use match characters * and ?):</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>r</option></term>
|
|
<listitem>
|
|
<para>control is readable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>w</option></term>
|
|
<listitem>
|
|
<para>control is writable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>v</option></term>
|
|
<listitem>
|
|
<para>control is volatile</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>i</option></term>
|
|
<listitem>
|
|
<para>control is inactive</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>l</option></term>
|
|
<listitem>
|
|
<para>control is locked</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>R</option></term>
|
|
<listitem>
|
|
<para>control is TLV readable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>W</option></term>
|
|
<listitem>
|
|
<para>control is TLV writable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>C</option></term>
|
|
<listitem>
|
|
<para>control is TLV commandable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>o</option></term>
|
|
<listitem>
|
|
<para>process is owner of this control</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>u</option></term>
|
|
<listitem>
|
|
<para>control created in user space</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>owner</option></term>
|
|
<listitem>
|
|
<para>Control owner process PID number</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>count</option></term>
|
|
<listitem>
|
|
<para>Control count of values</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>min</option></term>
|
|
<listitem>
|
|
<para>Value range - minimum value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>max</option></term>
|
|
<listitem>
|
|
<para>Value range - maximum value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>step</option></term>
|
|
<listitem>
|
|
<para>Value range - step value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dBmin</option></term>
|
|
<listitem>
|
|
<para>Value range - minimum dB value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dBmax</option></term>
|
|
<listitem>
|
|
<para>Value range - maximum dB value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>items</option></term>
|
|
<listitem>
|
|
<para>Enumerated value - number of text items</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>enums</option></term>
|
|
<listitem>
|
|
<para>Enumerated value - list of text names stored between '|' character</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>value</option></term>
|
|
<listitem>
|
|
<para>Value of control stored to a string delimited by
|
|
comma (,).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>do_search</option></term>
|
|
<listitem>
|
|
<para>Search for a control. Value "1" is returned
|
|
if a control was found. The CTL{name} key might
|
|
contain match characters * and ?. An control index
|
|
might be specified as first argument starting from
|
|
zero (e.g. CTL{do_search 2}="1").</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>do_count</option></term>
|
|
<listitem>
|
|
<para>Search for a controls and return total count
|
|
of matched ones. The CTL{name} key might contain match
|
|
characters * and ?.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>CONFIG{sysfs_device}</option></term>
|
|
<listitem>
|
|
<para>The relative path to sysfs subsystem specifying
|
|
the root directory of a soundcard device. Usually,
|
|
it should be set to "/class/sound/card$cardinfo{card}/device".
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ATTR{<replaceable>filename</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>Match sysfs attribute values of the soundcard device.
|
|
The relative path to sysfs tree must be defined by
|
|
CONFIG{sysfs_device} key. Trailing whitespace in the attribute
|
|
values is ignored, if the specified match value does
|
|
not contain trailing whitespace itself. Depending on
|
|
the type of operator, this key is also used to set
|
|
the value of a sysfs attribute.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ENV{<replaceable>key</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>Match against the value of an environment variable. Up
|
|
to five <option>ENV</option> keys can be specified per rule.
|
|
Depending on the type of operator, this key is also used
|
|
to export a variable to the environment.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>PROGRAM</option></term>
|
|
<listitem>
|
|
<para>Execute external program. The key is true, if
|
|
the program returns without exit code zero. The whole event
|
|
environment is available to the executed program. The
|
|
program's output printed to stdout is available for
|
|
the RESULT key.</para>
|
|
<para>Several buildin commands are available:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>__ctl_search</option></term>
|
|
<listitem>
|
|
<para>Search for a control. The CTL{name} key might
|
|
contain match characters * and ?. An control index
|
|
might be specified as first argument starting from
|
|
zero (e.g. PROGRAM="__ctl_search 2").</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>__ctl_count</option></term>
|
|
<listitem>
|
|
<para>Search for a controls and return total count
|
|
of matched ones. The CTL{name} key might contain match
|
|
characters * and ?.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>RESULT</option></term>
|
|
<listitem>
|
|
<para>Match the returned string of the last PROGRAM call.
|
|
This key can be used in the same or in any later rule
|
|
after a PROGRAM call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<para>Most of the fields support a shell style pattern matching.
|
|
The following pattern characters are supported:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>*</option></term>
|
|
<listitem>
|
|
<para>Matches zero, or any number of characters.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>?</option></term>
|
|
<listitem>
|
|
<para>Matches any single character.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>[]</option></term>
|
|
<listitem>
|
|
<para>Matches any single character specified within
|
|
the brackets. For example, the pattern string 'tty[SR]'
|
|
would match either 'ttyS' or 'ttyR'. Ranges are also
|
|
supported within this match with the '-' character.
|
|
For example, to match on the range of all digits,
|
|
the pattern [0-9] would be used. If the first character
|
|
following the '[' is a '!', any characters
|
|
not enclosed are matched.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>The following keys can get values assigned:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>CTL{numid}</option>, <option>CTL{iface}</option>,
|
|
<option>CTL{device}</option>, <option>CTL{subdev}</option>,
|
|
<option>CTL{name}</option>, <option>CTL{index}</option>,
|
|
</term>
|
|
<listitem>
|
|
<para>Select universal control element.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>CTL{value}</option></term>
|
|
<listitem>
|
|
<para>Value is set (written) also to soundcard's control
|
|
device and RESULT key is set to errno code. The result of
|
|
set operation is always true (it means continue with
|
|
next key on line).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>CTL{values}</option></term>
|
|
<listitem>
|
|
<para>Value is set (written) also to soundcard's control
|
|
device (all control values are set to specified value) and
|
|
RESULT key is set to errno code. The result of
|
|
set operation is always true (it means continue with
|
|
next key on line).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>CTL{write}</option></term>
|
|
<listitem>
|
|
<para>Value is set (written) also to soundcard's control
|
|
device (all control values are set to specified value).
|
|
The result of set operation is true when operation
|
|
succeed (it means continue with next key on line).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ENV{<replaceable>key</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>Export a variable to the environment. Depending on the type of operator,
|
|
this key is also to match against an environment variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>RESULT</option></term>
|
|
<listitem>
|
|
<para>Set RESULT variable. Note that PROGRAM also sets
|
|
this variable, but setting this variable manually
|
|
might be useful to change code execution order (included
|
|
files).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>LABEL</option></term>
|
|
<listitem>
|
|
<para>Named label where a GOTO can jump to.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>GOTO</option></term>
|
|
<listitem>
|
|
<para>Jumps to the next LABEL with a matching name.
|
|
The goto cannot jump backward.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>INCLUDE</option></term>
|
|
<listitem>
|
|
<para>Include specified filename or all files in specified directory</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ACCESS</option></term>
|
|
<listitem>
|
|
<para>Check if specified file or directory exists</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>CONFIG{sysfs_device}</option></term>
|
|
<listitem>
|
|
<para>The relative path to sysfs subsystem specifying
|
|
the root directory of a soundcard device. Usually,
|
|
it should be set to "/class/sound/card$cardinfo{card}/device".
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>PRINT</option></term>
|
|
<listitem>
|
|
<para>PRINT value to stdout.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ERROR</option></term>
|
|
<listitem>
|
|
<para>PRINT value to stderr.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>EXIT</option></term>
|
|
<listitem>
|
|
<para>Exit immediately and set program exit code to value
|
|
(should be integer). If value is "return" string,
|
|
parser leaves current included file and returns to parent
|
|
configuration file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<para>The <option>PROGRAM</option>, <option>RESULT</option>,
|
|
<option>CTL{value}</option>,
|
|
<option>PRINT</option>, <option>ERROR</option>,
|
|
<option>EXIT</option>, <option>CONFIG{}</option>
|
|
fields support simple printf-like string substitutions.
|
|
It allows the use of the complete environment set by earlier matching
|
|
rules. For all other fields, substitutions are applied while the individual rule is
|
|
being processed. The available substitutions are:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>$cardinfo{<replaceable>attribute</replaceable>}</option>, <option>%i{<replaceable>attribute</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>See CARDINFO{} for more details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$ctl{<replaceable>attribute</replaceable>}</option>, <option>%C{<replaceable>attribute</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>See CTL{} for more details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$attr{<replaceable>file</replaceable>}</option>, <option>%s{<replaceable>file</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>The value of a sysfs attribute found at the device, where
|
|
all keys of the rule have matched.
|
|
If the attribute is a symlink, the last element of the symlink target is
|
|
returned as the value.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$env{<replaceable>key</replaceable>}</option>, <option>%E{<replaceable>key</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>The value of an environment variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$result</option>, <option>%c</option></term>
|
|
<listitem>
|
|
<para>The string returned by the external program requested with PROGRAM.
|
|
A single part of the string, separated by a space character may be selected
|
|
by specifying the part number as an attribute: <option>%c{N}</option>.
|
|
If the number is followed by the '+' char this part plus all remaining parts
|
|
of the result string are substituted: <option>%c{N+}</option></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$sysfsroot</option>, <option>%r</option></term>
|
|
<listitem>
|
|
<para>Root directory where sysfs file-system is mounted.
|
|
Ususally, this value is just "/sys".</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$config{<replaceable>key</replaceable>}</option>, <option>%g{<replaceable>key</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>The value of a configuration variable. See CONFIG{} for more details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>%%</option></term>
|
|
<listitem>
|
|
<para>The '%' character itself.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$$</option></term>
|
|
<listitem>
|
|
<para>The '$' character itself.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>The count of characters to be substituted may be limited
|
|
by specifying the format length value. For example, '%3s{file}'
|
|
will only insert the first three characters of the sysfs
|
|
attribute</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1><title>AUTHOR</title>
|
|
<para>Written by Jaroslav Kysela <email>perex@perex.cz</email></para>
|
|
<para>Some portions are written by Greg Kroah-Hartman <email>greg@kroah.com</email> and
|
|
Kay Sievers <email>kay.sievers@vrfy.org</email>.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>SEE ALSO</title>
|
|
<para><citerefentry>
|
|
<refentrytitle>alsactl</refentrytitle><manvolnum>1</manvolnum>
|
|
</citerefentry></para>
|
|
</refsect1>
|
|
</refentry>
|
|
</section>
|
|
</article>
|