ALSA: doc: ReSTize Channel-Mapping-API document

============================

ALSA PCM channel-mapping API

============================

Takashi Iwai <tiwai@suse.de>

GENERAL

-------

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

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 }

``{ front_left, front_right }``

while a 4.0 surround PCM stream has a channel map of

  { front left, front right, rear left, rear right }.

``{ 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

mapping API.

DESIGN

------

Design

======

Actually, "the channel mapping API" doesn't introduce anything new in

the kernel/user-space ABI perspective.  It uses only the existing

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

* 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.

read operation.  Optionally, the write operation can be provided to

allow user to change the channel map dynamically.

* TLV

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...

``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

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``

type is where pair-wise channels are swappable.  For example, when you

have {FL/FR/RL/RR} channel map, _PAIRED type would allow you to swap

only {RL/RR/FL/FR} while _VAR type would allow even swapping FL and

have {FL/FR/RL/RR} channel map, ``_PAIRED`` type would allow you to swap

only {RL/RR/FL/FR} while ``_VAR`` type would allow even swapping FL and

RR.

These new TLV types are defined in sound/tlv.h.

These new TLV types are defined in ``sound/tlv.h``.

The available channel position values are defined in sound/asound.h,

The available channel position values are defined in ``sound/asound.h``,

here is a cut:

::

  /* channel positions */

  enum {

	SNDRV_CHMAP_UNKNOWN = 0,

When a PCM stream can provide more than one channel map, you can

provide multiple channel maps in a TLV container type.  The TLV data

to be returned will contain such as:

::

	SNDRV_CTL_TLVT_CONTAINER 96

	    SNDRV_CTL_TLVT_CHMAP_FIXED 4 SNDRV_CHMAP_FC

	    SNDRV_CTL_TLVT_CHMAP_FIXED 8 SNDRV_CHMAP_FL SNDRV_CHMAP_FR

The channel position is provided in LSB 16bits.  The upper bits are

used for bit flags.

::

	#define SNDRV_CHMAP_POSITION_MASK	0xffff

	#define SNDRV_CHMAP_PHASE_INVERSE	(0x01 << 16)

	#define SNDRV_CHMAP_DRIVER_SPEC		(0x02 << 16)

SNDRV_CHMAP_PHASE_INVERSE indicates the channel is phase inverted,

``SNDRV_CHMAP_PHASE_INVERSE`` indicates the channel is phase inverted,

(thus summing left and right channels would result in almost silence).

Some digital mic devices have this.

When SNDRV_CHMAP_DRIVER_SPEC is set, all the channel position values

When ``SNDRV_CHMAP_DRIVER_SPEC`` is set, all the channel position values

don't follow the standard definition above but driver-specific.

* READ OPERATION

Read Operation

--------------

The control read operation is for providing the current channel map of

the given stream.  The control element returns an integer array

When this is performed before the number of the channel is specified

(i.e. hw_params is set), it should return all channels set to

UNKNOWN.

``UNKNOWN``.

* WRITE OPERATION

Write Operation

---------------

The control write operation is optional, and only for devices that can

change the channel configuration on the fly, such as HDMI.  User needs

.. toctree::

   :maxdepth: 2

   channel-mapping-api

   procfile

   powersave