Audio Formats & Channel Routing API#

The Audio Formats and Channel Routing API provides channel map parsing, multi-channel spatial routing, and integer sample saturation arithmetic across SOF audio processing graphs.

Channel Mapping Infrastructure#

Multi-channel audio streams require precise channel assignments across ALSA PCM devices, DSP processing algorithms, and hardware Digital Audio Interfaces (DAI).

SOF utilizes channel mapping tokens (struct sof_ipc_channel_map) to configure: - Channel slot numbering and spatial assignments (Front Left, Front Right, Center, LFE, Surround). - Dynamic channel routing and demultiplexing. - Helper functions: chmap_get() and chmap_get_size().

PCM Sample Saturation Arithmetic#

DSP filter and gain stages can generate audio sample values that exceed the representable dynamic range of target fixed-point bit depths. Rather than allowing integer overflow wrap-around distortion (which creates severe acoustic clicks), SOF provides inline hardware-optimized saturation primitives:

  • `sat_int32(int64_t x)`: Clamps 64-bit intermediate products to 32-bit signed range ([INT32_MIN, INT32_MAX]).

  • `sat_int24(int32_t x)`: Clamps 32-bit values to 24-bit audio range ([-8388608, 8388607]).

  • `sat_int16(int32_t x)`: Clamps 32-bit values to 16-bit audio range ([-32768, 32767]).

  • `sat_int8(int32_t x)`: Clamps 32-bit values to 8-bit signed range ([-128, 127]).

C API Reference#

group Audio Formats & Channel Routing

Channel map parsing, stream conversion, and audio sample saturation routines.

Functions

static inline uint32_t chmap_get_size(struct sof_ipc_channel_map *chmap)#

Returns the size of an IPC channel map structure in bytes.

Parameters:

  • chmap – [in] Pointer to the channel map structure.

Returns:

Total size in bytes including dynamic channel coefficients.

struct sof_ipc_channel_map *chmap_get(struct sof_ipc_stream_map *smap, int index)#

Returns a channel map for a given channel index in a stream map.

Parameters:

  • smap – [in] Pointer to the stream map structure.

  • index – [in] Channel index.

Returns:

Pointer to matching channel map structure, or NULL if not found.

static inline int32_t sat_int32(int64_t x)#

Saturate a 64-bit integer to signed 32-bit integer range.

Parameters:

  • x – [in] Input 64-bit integer.

Returns:

Saturated 32-bit integer clamped between INT32_MIN and INT32_MAX.

static inline int32_t sat_int24(int32_t x)#

Saturate a 32-bit integer to signed 24-bit integer range.

Parameters:

  • x – [in] Input 32-bit integer.

Returns:

Saturated 24-bit integer clamped between INT24_MINVALUE and INT24_MAXVALUE.

static inline int16_t sat_int16(int32_t x)#

Saturate a 32-bit integer to signed 16-bit integer range.

Parameters:

  • x – [in] Input 32-bit integer.

Returns:

Saturated 16-bit integer clamped between INT16_MIN and INT16_MAX.

static inline int8_t sat_int8(int32_t x)#

Saturate a 32-bit integer to signed 8-bit integer range.

Parameters:

  • x – [in] Input 32-bit integer.

Returns:

Saturated 8-bit integer clamped between INT8_MIN and INT8_MAX.