1 ============================
2 ALSA PCM channel-mapping API
3 ============================
4
5 Takashi Iwai <tiwai@suse.de>
6
7 General
8 =======
9
10 The channel mapping API allows user to query t
11 and the current channel map, also optionally t
12 of the current stream.
13
14 A channel map is an array of position for each
15 Typically, a stereo PCM stream has a channel m
16 ``{ front_left, front_right }``
17 while a 4.0 surround PCM stream has a channel
18 ``{ front left, front right, rear left, rear r
19
20 The problem, so far, was that we had no standa
21 explicitly, and applications had no way to kno
22 corresponds to which (speaker) position. Thus
23 wrong channels for 5.1 outputs, and you hear s
24 from rear. Or, some devices secretly assume t
25 third/fourth channels while others that C/LFE
26
27 Also, some devices such as HDMI are configurab
28 positions even with the same number of total c
29 was no way to specify this because of lack of
30 specification. These are the main motivations
31 mapping API.
32
33
34 Design
35 ======
36
37 Actually, "the channel mapping API" doesn't in
38 the kernel/user-space ABI perspective. It use
39 control element features.
40
41 As a ground design, each PCM substream may con
42 providing the channel mapping information and
43 element is specified by:
44
45 * iface = SNDRV_CTL_ELEM_IFACE_PCM
46 * name = "Playback Channel Map" or "Capture Ch
47 * device = the same device number for the assi
48 * index = the same index number for the assign
49
50 Note the name is different depending on the PC
51
52 Each control element provides at least the TLV
53 read operation. Optionally, the write operati
54 allow user to change the channel map dynamical
55
56 TLV
57 ---
58
59 The TLV operation gives the list of available
60 maps. A list item of a channel map is usually
61 ``type data-bytes ch0 ch1 ch2...``
62 where type is the TLV type value, the second a
63 bytes (not the numbers) of channel values, and
64 position value for each channel.
65
66 As a TLV type, either ``SNDRV_CTL_TLVT_CHMAP_F
67 ``SNDRV_CTL_TLV_CHMAP_VAR`` or ``SNDRV_CTL_TLV
68 The ``_FIXED`` type is for a channel map with
69 while the latter two are for flexible channel
70 for a channel map where all channels are freel
71 type is where pair-wise channels are swappable
72 have {FL/FR/RL/RR} channel map, ``_PAIRED`` ty
73 only {RL/RR/FL/FR} while ``_VAR`` type would a
74 RR.
75
76 These new TLV types are defined in ``sound/tlv
77
78 The available channel position values are defi
79 here 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 cha
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 cente
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
100 SNDRV_CHMAP_FRC, /* front right
101 SNDRV_CHMAP_RLC, /* rear left c
102 SNDRV_CHMAP_RRC, /* rear right
103 SNDRV_CHMAP_FLW, /* front left
104 SNDRV_CHMAP_FRW, /* front right
105 SNDRV_CHMAP_FLH, /* front left
106 SNDRV_CHMAP_FCH, /* front cente
107 SNDRV_CHMAP_FRH, /* front right
108 SNDRV_CHMAP_TC, /* top center
109 SNDRV_CHMAP_TFL, /* top front l
110 SNDRV_CHMAP_TFR, /* top front r
111 SNDRV_CHMAP_TFC, /* top front c
112 SNDRV_CHMAP_TRL, /* top rear le
113 SNDRV_CHMAP_TRR, /* top rear ri
114 SNDRV_CHMAP_TRC, /* top rear ce
115 SNDRV_CHMAP_LAST = SNDRV_CHMAP_TRC,
116 };
117
118 When a PCM stream can provide more than one ch
119 provide multiple channel maps in a TLV contain
120 to be returned will contain such as:
121 ::
122
123 SNDRV_CTL_TLVT_CONTAINER 96
124 SNDRV_CTL_TLVT_CHMAP_FIXED 4 SNDRV
125 SNDRV_CTL_TLVT_CHMAP_FIXED 8 SNDRV
126 SNDRV_CTL_TLVT_CHMAP_FIXED 16 NDRV
127 SNDRV_CHMAP_RL SNDRV_CHMAP_RR
128
129 The channel position is provided in LSB 16bits
130 used for bit flags.
131 ::
132
133 #define SNDRV_CHMAP_POSITION_MASK
134 #define SNDRV_CHMAP_PHASE_INVERSE
135 #define SNDRV_CHMAP_DRIVER_SPEC
136
137 ``SNDRV_CHMAP_PHASE_INVERSE`` indicates the ch
138 (thus summing left and right channels would re
139 Some digital mic devices have this.
140
141 When ``SNDRV_CHMAP_DRIVER_SPEC`` is set, all t
142 don't follow the standard definition above but
143
144 Read Operation
145 --------------
146
147 The control read operation is for providing th
148 the given stream. The control element returns
149 containing the position of each channel.
150
151 When this is performed before the number of th
152 (i.e. hw_params is set), it should return all
153 ``UNKNOWN``.
154
155 Write Operation
156 ---------------
157
158 The control write operation is optional, and o
159 change the channel configuration on the fly, s
160 to pass an integer value containing the valid
161 all channels of the assigned PCM substream.
162
163 This operation is allowed only at PCM PREPARED
164 other states, it shall return an error.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.