i2s_config_t Struct Reference

I2S configuration structure. More...

#include <i2s.h>

Data Fields
i2s_data_format_en	data_format
i2s_clock_mode_en	clock_mode
i2s_word_size_en	word_size
uint8_t	channels
uint32_t	sample_rate
i2s_clock_mode_t	clock_config
bool	mclk_present
bool	mclk_required
uint16_t	mclk_ratio
size_t	block_size
uint8_t	num_blocks
bool	enable_dma

Detailed Description

I2S configuration structure.

This structure contains complete configuration parameters for an I2S channel. All fields must be properly initialized before passing to i2s_configure.

Note

Buffer configuration parameters (block_size, num_blocks) usage:

Multi-buffer Queue Mode (Driver-managed):

• block_size: Size of each buffer (e.g., 2048 bytes)
• num_blocks: Number of buffers driver allocates (2-4 typical)
• Driver manages internal buffer pool and rotation
• Example: block_size=2048, num_blocks=3 → driver allocates 3×2KB buffers

Contiguous Buffer Mode (Application-managed):

• block_size: Size of each chunk queued via i2s_read_async/i2s_write_async
• num_blocks: Set to 0 (driver does not allocate buffers)
• Application manages large ring buffer and queues chunks manually
• Example: block_size=2048, num_blocks=0 → app provides 16KB ring buffer, queues 2KB chunks at offsets 0, 2KB, 4KB, etc.

Note

DMA is automatically configured based on sample rate, word size, and channel count. Channels are auto-assigned by the driver.

MCLK configuration:

• Set mclk_present/mclk_required to enable MCLK output when supported.
• Set mclk_ratio to the desired MCLK ratio; a value of 0 leaves hardware default.

Field Documentation

data_format

i2s_data_format_en i2s_config_t::data_format

Data format (I2S, Left/Right Justified, TDM)

clock_mode

i2s_clock_mode_en i2s_config_t::clock_mode

Clock mode (Master or Slave)

word_size

i2s_word_size_en i2s_config_t::word_size

Number of bits per word (sample)

channels

uint8_t i2s_config_t::channels

Number of channels (1=mono, 2=stereo, >2=TDM)

sample_rate

uint32_t i2s_config_t::sample_rate

Sample rate in Hz (e.g., 8000, 16000, 48000)

clock_config

i2s_clock_mode_t i2s_config_t::clock_config

Clock-specific configuration (gating, polarity)

mclk_present

bool i2s_config_t::mclk_present

true if MCLK (master clock) output is available

mclk_required

bool i2s_config_t::mclk_required

true if external device requires MCLK (ignored if not present)

mclk_ratio

uint16_t i2s_config_t::mclk_ratio

MCLK to sample rate ratio (e.g., 256, 384, 512). Set 0 for auto or unused.

block_size

size_t i2s_config_t::block_size

Block/buffer size for DMA transfers (in bytes)

num_blocks

uint8_t i2s_config_t::num_blocks

Number of blocks to allocate (0=app-managed)

enable_dma

bool i2s_config_t::enable_dma

Enable DMA-backed transfers (false=interrupt-driven)