Documentation/sound/designs/channel-mapping-api.rst

Source file repositories/reference/linux-study-clean/Documentation/sound/designs/channel-mapping-api.rst

File Facts

System
Linux kernel
Corpus path
Documentation/sound/designs/channel-mapping-api.rst
Extension
.rst
Size
6015 bytes
Lines
165
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

============================
ALSA PCM channel-mapping API
============================

Takashi Iwai <tiwai@suse.de>

General
=======

The channel mapping API allows user to query the possible channel maps
and the current channel map, also optionally to modify the channel map
of the current stream.

A channel map is an array of position for each PCM channel.
Typically, a stereo PCM stream has a channel map of
``{ front_left, front_right }``
while a 4.0 surround PCM stream has a channel map of
``{ front left, front right, rear left, rear right }.``

The problem, so far, was that we had no standard channel map
explicitly, and applications had no way to know which channel
corresponds to which (speaker) position.  Thus, applications applied
wrong channels for 5.1 outputs, and you hear suddenly strange sound
from rear.  Or, some devices secretly assume that center/LFE is the
third/fourth channels while others that C/LFE as 5th/6th channels.

Also, some devices such as HDMI are configurable for different speaker
positions even with the same number of total channels.  However, there
was no way to specify this because of lack of channel map
specification.  These are the main motivations for the new channel
mapping API.


Design
======

Actually, "the channel mapping API" doesn't introduce anything new in
the kernel/user-space ABI perspective.  It uses only the existing
control element features.

As a ground design, each PCM substream may contain a control element
providing the channel mapping information and configuration.  This
element is specified by:

* iface = SNDRV_CTL_ELEM_IFACE_PCM
* name = "Playback Channel Map" or "Capture Channel Map"
* device = the same device number for the assigned PCM substream
* index = the same index number for the assigned PCM substream

Note the name is different depending on the PCM substream direction.

Each control element provides at least the TLV read operation and the
read operation.  Optionally, the write operation can be provided to
allow user to change the channel map dynamically.

TLV
---

The TLV operation gives the list of available channel
maps.  A list item of a channel map is usually a TLV of
``type data-bytes ch0 ch1 ch2...``
where type is the TLV type value, the second argument is the total
bytes (not the numbers) of channel values, and the rest are the
position value for each channel.

As a TLV type, either ``SNDRV_CTL_TLVT_CHMAP_FIXED``,
``SNDRV_CTL_TLV_CHMAP_VAR`` or ``SNDRV_CTL_TLVT_CHMAP_PAIRED`` can be used.
The ``_FIXED`` type is for a channel map with the fixed channel position
while the latter two are for flexible channel positions. ``_VAR`` type is
for a channel map where all channels are freely swappable and ``_PAIRED``

Annotation

Implementation Notes