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