channel-mapping-api.rst

  1============================
  2ALSA PCM channel-mapping API
  3============================
  4
  5Takashi Iwai <tiwai@suse.de>
  6
  7General
  8=======
  9
 10The channel mapping API allows user to query the possible channel maps
 11and the current channel map, also optionally to modify the channel map
 12of the current stream.
 13
 14A channel map is an array of position for each PCM channel.
 15Typically, a stereo PCM stream has a channel map of
 16``{ front_left, front_right }``
 17while a 4.0 surround PCM stream has a channel map of
 18``{ front left, front right, rear left, rear right }.``
 19
 20The problem, so far, was that we had no standard channel map
 21explicitly, and applications had no way to know which channel
 22corresponds to which (speaker) position.  Thus, applications applied
 23wrong channels for 5.1 outputs, and you hear suddenly strange sound
 24from rear.  Or, some devices secretly assume that center/LFE is the
 25third/fourth channels while others that C/LFE as 5th/6th channels.
 26
 27Also, some devices such as HDMI are configurable for different speaker
 28positions even with the same number of total channels.  However, there
 29was no way to specify this because of lack of channel map
 30specification.  These are the main motivations for the new channel
 31mapping API.
 32
 33
 34Design
 35======
 36
 37Actually, "the channel mapping API" doesn't introduce anything new in
 38the kernel/user-space ABI perspective.  It uses only the existing
 39control element features.
 40
 41As a ground design, each PCM substream may contain a control element
 42providing the channel mapping information and configuration.  This
 43element is specified by:
 44
 45* iface = SNDRV_CTL_ELEM_IFACE_PCM
 46* name = "Playback Channel Map" or "Capture Channel Map"
 47* device = the same device number for the assigned PCM substream
 48* index = the same index number for the assigned PCM substream
 49
 50Note the name is different depending on the PCM substream direction.
 51
 52Each control element provides at least the TLV read operation and the
 53read operation.  Optionally, the write operation can be provided to
 54allow user to change the channel map dynamically.
 55
 56TLV
 57---
 58
 59The TLV operation gives the list of available channel
 60maps.  A list item of a channel map is usually a TLV of
 61``type data-bytes ch0 ch1 ch2...``
 62where type is the TLV type value, the second argument is the total
 63bytes (not the numbers) of channel values, and the rest are the
 64position value for each channel.
 65
 66As a TLV type, either ``SNDRV_CTL_TLVT_CHMAP_FIXED``,
 67``SNDRV_CTL_TLV_CHMAP_VAR`` or ``SNDRV_CTL_TLVT_CHMAP_PAIRED`` can be used.
 68The ``_FIXED`` type is for a channel map with the fixed channel position
 69while the latter two are for flexible channel positions. ``_VAR`` type is
 70for a channel map where all channels are freely swappable and ``_PAIRED``
 71type is where pair-wise channels are swappable.  For example, when you
 72have {FL/FR/RL/RR} channel map, ``_PAIRED`` type would allow you to swap
 73only {RL/RR/FL/FR} while ``_VAR`` type would allow even swapping FL and
 74RR.
 75
 76These new TLV types are defined in ``sound/tlv.h``.
 77
 78The available channel position values are defined in ``sound/asound.h``,
 79here is a cut:
 80
 81::
 82
 83  /* channel positions */
 84  enum {
 85	SNDRV_CHMAP_UNKNOWN = 0,
 86	SNDRV_CHMAP_NA,		/* N/A, silent */
 87	SNDRV_CHMAP_MONO,	/* mono stream */
 88	/* this follows the alsa-lib mixer channel value + 3 */
 89	SNDRV_CHMAP_FL,		/* front left */
 90	SNDRV_CHMAP_FR,		/* front right */
 91	SNDRV_CHMAP_RL,		/* rear left */
 92	SNDRV_CHMAP_RR,		/* rear right */
 93	SNDRV_CHMAP_FC,		/* front center */
 94	SNDRV_CHMAP_LFE,	/* LFE */
 95	SNDRV_CHMAP_SL,		/* side left */
 96	SNDRV_CHMAP_SR,		/* side right */
 97	SNDRV_CHMAP_RC,		/* rear center */
 98	/* new definitions */
 99	SNDRV_CHMAP_FLC,	/* front left center */
100	SNDRV_CHMAP_FRC,	/* front right center */
101	SNDRV_CHMAP_RLC,	/* rear left center */
102	SNDRV_CHMAP_RRC,	/* rear right center */
103	SNDRV_CHMAP_FLW,	/* front left wide */
104	SNDRV_CHMAP_FRW,	/* front right wide */
105	SNDRV_CHMAP_FLH,	/* front left high */
106	SNDRV_CHMAP_FCH,	/* front center high */
107	SNDRV_CHMAP_FRH,	/* front right high */
108	SNDRV_CHMAP_TC,		/* top center */
109	SNDRV_CHMAP_TFL,	/* top front left */
110	SNDRV_CHMAP_TFR,	/* top front right */
111	SNDRV_CHMAP_TFC,	/* top front center */
112	SNDRV_CHMAP_TRL,	/* top rear left */
113	SNDRV_CHMAP_TRR,	/* top rear right */
114	SNDRV_CHMAP_TRC,	/* top rear center */
115	SNDRV_CHMAP_LAST = SNDRV_CHMAP_TRC,
116  };
117
118When a PCM stream can provide more than one channel map, you can
119provide multiple channel maps in a TLV container type.  The TLV data
120to be returned will contain such as:
121::
122
123	SNDRV_CTL_TLVT_CONTAINER 96
124	    SNDRV_CTL_TLVT_CHMAP_FIXED 4 SNDRV_CHMAP_FC
125	    SNDRV_CTL_TLVT_CHMAP_FIXED 8 SNDRV_CHMAP_FL SNDRV_CHMAP_FR
126	    SNDRV_CTL_TLVT_CHMAP_FIXED 16 NDRV_CHMAP_FL SNDRV_CHMAP_FR \
127		SNDRV_CHMAP_RL SNDRV_CHMAP_RR
128
129The channel position is provided in LSB 16bits.  The upper bits are
130used for bit flags.
131::
132
133	#define SNDRV_CHMAP_POSITION_MASK	0xffff
134	#define SNDRV_CHMAP_PHASE_INVERSE	(0x01 << 16)
135	#define SNDRV_CHMAP_DRIVER_SPEC		(0x02 << 16)
136
137``SNDRV_CHMAP_PHASE_INVERSE`` indicates the channel is phase inverted,
138(thus summing left and right channels would result in almost silence).
139Some digital mic devices have this.
140
141When ``SNDRV_CHMAP_DRIVER_SPEC`` is set, all the channel position values
142don't follow the standard definition above but driver-specific.
143
144Read Operation
145--------------
146
147The control read operation is for providing the current channel map of
148the given stream.  The control element returns an integer array
149containing the position of each channel.
150
151When this is performed before the number of the channel is specified
152(i.e. hw_params is set), it should return all channels set to
153``UNKNOWN``.
154
155Write Operation
156---------------
157
158The control write operation is optional, and only for devices that can
159change the channel configuration on the fly, such as HDMI.  User needs
160to pass an integer value containing the valid channel positions for
161all channels of the assigned PCM substream.
162
163This operation is allowed only at PCM PREPARED state.  When called in
164other states, it shall return an error.