I2S / SAI audio bus driver. More...

Data Structures
struct	ove_i2s_cfg
	I2S bus configuration descriptor. More...

Typedefs
typedef void(*	ove_i2s_cb_t) (ove_i2s_t i2s, void *user_data)
	I2S half-buffer completion callback.

Enumerations
enum	ove_i2s_dir_t { OVE_I2S_DIR_TX = 0x01 , OVE_I2S_DIR_RX = 0x02 , OVE_I2S_DIR_TXRX = 0x03 }
	I2S stream direction. More...

Functions
int	ove_i2s_init (ove_i2s_t i2s, ove_i2s_storage_t storage, void tx_dma_buf, void rx_dma_buf, const struct ove_i2s_cfg *cfg)
	Initialise I2S with caller-provided static storage and DMA buffers.

void	ove_i2s_deinit (ove_i2s_t i2s)
	Release an I2S handle previously created with `ove_i2s_init`.

int	ove_i2s_create (ove_i2s_t i2s, const struct ove_i2s_cfg cfg)
	Heap-mode counterpart of `ove_i2s_init()` — allocates storage and DMA buffers internally.

void	ove_i2s_destroy (ove_i2s_t i2s)
	Destroy an I2S handle previously created with `ove_i2s_create`.

int	ove_i2s_set_rx_callback (ove_i2s_t i2s, ove_i2s_cb_t cb, void *user_data)
	Set the RX half-buffer completion callback.

int	ove_i2s_set_tx_callback (ove_i2s_t i2s, ove_i2s_cb_t cb, void *user_data)
	Set the TX half-buffer completion callback.

int	ove_i2s_start (ove_i2s_t i2s)
	Start I2S DMA streaming.

int	ove_i2s_stop (ove_i2s_t i2s)
	Stop I2S DMA streaming.

int	ove_i2s_pause (ove_i2s_t i2s)
	Pause I2S DMA streaming (can be resumed).

int	ove_i2s_resume (ove_i2s_t i2s)
	Resume I2S DMA streaming after pause.

void *	ove_i2s_rx_buf (ove_i2s_t i2s)
	Get pointer to the most recently completed RX half-buffer.

void *	ove_i2s_tx_buf (ove_i2s_t i2s)
	Get pointer to the TX half-buffer safe to write.

size_t	ove_i2s_half_buf_size (ove_i2s_t i2s)
	Get the size of one half-buffer in bytes.

void	ove_i2s_rx_half_cplt_isr (ove_i2s_t i2s)
	ISR helper — invoke from backend RX half-complete interrupt.

void	ove_i2s_rx_cplt_isr (ove_i2s_t i2s)
	ISR helper — invoke from backend RX full-complete interrupt.

void	ove_i2s_tx_half_cplt_isr (ove_i2s_t i2s)
	ISR helper — invoke from backend TX half-complete interrupt.

void	ove_i2s_tx_cplt_isr (ove_i2s_t i2s)
	ISR helper — invoke from backend TX full-complete interrupt.

Detailed Description

I2S / SAI audio bus driver.

Provides a portable I2S master driver for DMA-based audio streaming with double-buffered (ping-pong) operation. The driver delivers half-buffer completion callbacks from ISR context, enabling real-time audio processing.

The codec connected to the I2S bus is NOT initialised by this driver; codec setup is board-specific and must be done separately (e.g. via I2C register writes in the board BSP).

Note: Requires CONFIG_OVE_I2S.

Typedef Documentation

◆ ove_i2s_cb_t

typedef void(* ove_i2s_cb_t) (ove_i2s_t i2s, void *user_data)

I2S half-buffer completion callback.

Called from ISR context when a DMA half-transfer or full-transfer completes. The callback should be short — typically it unblocks a processing task.

Parameters

[in]	i2s	I2S handle.
[in]	user_data	Opaque pointer supplied at registration time.

Enumeration Type Documentation

◆ ove_i2s_dir_t

enum ove_i2s_dir_t

I2S stream direction.

Enumerator
OVE_I2S_DIR_TX	Transmit only (playback).
OVE_I2S_DIR_RX	Receive only (capture).
OVE_I2S_DIR_TXRX	Full-duplex (simultaneous TX + RX).

Function Documentation

◆ ove_i2s_init()

int ove_i2s_init	(	ove_i2s_t *	i2s,
		ove_i2s_storage_t *	storage,
		void *	tx_dma_buf,
		void *	rx_dma_buf,
		const struct ove_i2s_cfg *	cfg
	)

Initialise I2S with caller-provided static storage and DMA buffers.

Parameters

[out]	i2s	Receives the initialised handle.
[in]	storage	Statically-allocated I2S storage.
[in]	tx_dma_buf	TX DMA buffer (may be NULL if direction is RX-only). Must be in DMA-accessible, cache-coherent memory.
[in]	rx_dma_buf	RX DMA buffer (may be NULL if direction is TX-only).
[in]	cfg	I2S configuration descriptor.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_i2s_create()

int ove_i2s_create	(	ove_i2s_t *	i2s,
		const struct ove_i2s_cfg *	cfg
	)

Heap-mode counterpart of ove_i2s_init() — allocates storage and DMA buffers internally.

Parameters

[out]	i2s	Receives the initialised handle.
[in]	cfg	I2S configuration descriptor.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_i2s_set_rx_callback()

int ove_i2s_set_rx_callback	(	ove_i2s_t	i2s,
		ove_i2s_cb_t	cb,
		void *	user_data
	)

Set the RX half-buffer completion callback.

Called from ISR when a DMA RX half-buffer is ready for processing.

Parameters

[in]	i2s	I2S handle.
[in]	cb	Callback invoked on RX half/full transfer; may be NULL to clear.
[in]	user_data	Opaque pointer forwarded to `cb`.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_i2s_set_tx_callback()

int ove_i2s_set_tx_callback	(	ove_i2s_t	i2s,
		ove_i2s_cb_t	cb,
		void *	user_data
	)

Set the TX half-buffer completion callback.

Called from ISR when a DMA TX half-buffer has been transmitted and is safe to refill.

Parameters

[in]	i2s	I2S handle.
[in]	cb	Callback invoked on TX half/full transfer; may be NULL to clear.
[in]	user_data	Opaque pointer forwarded to `cb`.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_i2s_start()

int ove_i2s_start ( ove_i2s_t i2s )

Start I2S DMA streaming.

Begins circular DMA transfers. TX starts first to generate clocks for a synchronous RX slave.

Parameters

[in] i2s I2S handle.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_i2s_stop()

int ove_i2s_stop ( ove_i2s_t i2s )

Stop I2S DMA streaming.

Parameters

[in] i2s I2S handle.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_i2s_pause()

int ove_i2s_pause ( ove_i2s_t i2s )

Pause I2S DMA streaming (can be resumed).

Parameters

[in] i2s I2S handle.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_i2s_resume()

int ove_i2s_resume ( ove_i2s_t i2s )

Resume I2S DMA streaming after pause.

Parameters

[in] i2s I2S handle.

Returns: OVE_OK on success, negative error code on failure.

◆ ove_i2s_rx_buf()

void * ove_i2s_rx_buf ( ove_i2s_t i2s )

Get pointer to the most recently completed RX half-buffer.

Returns the half of the DMA RX buffer that was just filled and is safe to read. Call this from within the RX callback.

Parameters

[in] i2s I2S handle.

Returns: Pointer to the completed RX half-buffer, or NULL on error.

◆ ove_i2s_tx_buf()

void * ove_i2s_tx_buf ( ove_i2s_t i2s )

Get pointer to the TX half-buffer safe to write.

Returns the half of the DMA TX buffer that DMA is NOT currently transmitting from. Fill this buffer before the next TX callback.

Parameters

[in] i2s I2S handle.

Returns: Pointer to the writable TX half-buffer, or NULL on error.

◆ ove_i2s_half_buf_size()

size_t ove_i2s_half_buf_size ( ove_i2s_t i2s )

Get the size of one half-buffer in bytes.

Parameters

[in] i2s I2S handle.

Returns: Half-buffer size in bytes.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ove_i2s_cb_t

Enumeration Type Documentation

◆ ove_i2s_dir_t

Function Documentation

◆ ove_i2s_init()

◆ ove_i2s_create()

◆ ove_i2s_set_rx_callback()

◆ ove_i2s_set_tx_callback()

◆ ove_i2s_start()

◆ ove_i2s_stop()

◆ ove_i2s_pause()

◆ ove_i2s_resume()

◆ ove_i2s_rx_buf()

◆ ove_i2s_tx_buf()

◆ ove_i2s_half_buf_size()