Functions for the I2S driver. More...

Typedefs
typedef void(*	i2s_event_cb_t) (i2s_instance_en instance, i2s_direction_en direction, i2s_event_en event, void *user_data)
	I2S event callback function type.
typedef void(*	i2s_buffer_cb_t) (i2s_instance_en instance, i2s_direction_en direction, void buffer, size_t size, void user_data)
	I2S buffer completion callback function type.

Functions
INIT_CODE i2s_status_en	i2s_init (i2s_instance_en instance)
i2s_status_en	i2s_get_fifo_depth (i2s_instance_en instance, i2s_direction_en direction, uint32_t *depth)
i2s_status_en	i2s_set_fifo_depth (i2s_instance_en instance, i2s_direction_en direction, uint32_t depth_words)
i2s_status_en	i2s_deinit (i2s_instance_en instance)
i2s_status_en	i2s_intr_enable (i2s_instance_en id, int enable)
i2s_status_en	i2s_get_config (i2s_instance_en instance, i2s_direction_en direction, i2s_config_t *config)
i2s_status_en	i2s_get_capabilities (i2s_instance_en instance, i2s_capabilities_t *caps)
i2s_status_en	i2s_trigger (i2s_instance_en instance, i2s_direction_en direction, i2s_trigger_cmd_en cmd)
i2s_status_en	i2s_register_callback (i2s_instance_en instance, i2s_event_cb_t callback, void *user_data)
i2s_status_en	i2s_register_buffer_callback (i2s_instance_en instance, i2s_buffer_cb_t callback, void *user_data)
i2s_status_en	i2s_configure (i2s_instance_en id, i2s_direction_en direction, const i2s_config_t *cfg)
	Configure I2S (clock + bit clock + mode + format).
i2s_status_en	i2s_write_async (i2s_instance_en instance, const void *buffer, size_t size)
i2s_status_en	i2s_read_async (i2s_instance_en instance, void *buffer, size_t size)
i2s_state_en	i2s_get_state (i2s_instance_en instance, i2s_direction_en direction)
i2s_status_en	i2s_flush (i2s_instance_en instance, i2s_direction_en direction)

Detailed Description

Functions for the I2S driver.

General functions for I2S driver.

Typedef Documentation

◆ i2s_event_cb_t

typedef void(* i2s_event_cb_t) (i2s_instance_en instance, i2s_direction_en direction, i2s_event_en event, void *user_data)

I2S event callback function type.

This callback is invoked when an I2S event occurs (completion, error, etc.).

Parameters

instance	I2S instance that generated the event
direction	Transfer direction (TX or RX)
event	Event type (bitmask of i2s_event_en values)
user_data	User-provided context pointer

◆ i2s_buffer_cb_t

typedef void(* i2s_buffer_cb_t) (i2s_instance_en instance, i2s_direction_en direction, void *buffer, size_t size, void *user_data)

I2S buffer completion callback function type.

This callback is invoked when a buffer transfer completes successfully. It provides direct access to the completed buffer for processing or reuse.

Parameters

instance	I2S instance
direction	Transfer direction (TX or RX)
buffer	Pointer to completed buffer
size	Number of bytes transferred
user_data	User-provided context pointer

Function Documentation

◆ i2s_init()

INIT_CODE i2s_status_en i2s_init ( i2s_instance_en instance )

Initialize I2S instance.

Initializes the specified I2S hardware instance and its associated driver context. This function must be invoked before any configuration or data transfer APIs are called for the given instance.

The function performs basic peripheral reset, context initialization, and prepares the hardware for subsequent configuration via i2s_configure.

Parameters

instance I2S instance identifier.

Returns: i2s_status_en Status code indicating success or failure.

Return values

I2S_OK	Initialization successful.
I2S_ERROR_INVALID_PARAM	Invalid I2S instance.
I2S_ERROR_BUSY	Instance already initialized.
I2S_ERROR_HW_FAULT	Hardware initialization failed.

◆ i2s_get_fifo_depth()

i2s_status_en i2s_get_fifo_depth	(	i2s_instance_en	instance,
		i2s_direction_en	direction,
		uint32_t *	depth )

Query FIFO depth for TX or RX direction.

Retrieves the hardware FIFO depth (in words) for the specified I2S instance and data direction.

Parameters

instance	I2S instance identifier.
direction	Data direction (TX or RX).
depth	Pointer to store the FIFO depth (in words).

Returns: i2s_status_en Status code indicating success or failure.

Return values

I2S_OK	FIFO depth retrieved successfully.
I2S_ERROR_INVALID_PARAM	Invalid instance, direction, or depth pointer.
I2S_ERROR_NOT_READY	Instance not initialized.

◆ i2s_set_fifo_depth()

i2s_status_en i2s_set_fifo_depth	(	i2s_instance_en	instance,
		i2s_direction_en	direction,
		uint32_t	depth_words )

Set FIFO depth used as the maximum submit size.

Configures the maximum number of words that can be submitted to the FIFO per transfer for the specified I2S instance and direction. The configured depth must not exceed the period size configured for the instance.

Parameters

instance	I2S instance identifier.
direction	Data direction (TX or RX).
depth_words	FIFO depth value in words.

Returns: i2s_status_en Status code indicating success or failure.

Return values

I2S_OK	FIFO depth configured successfully.
I2S_ERROR_INVALID_PARAM	Invalid instance, direction, or depth value.
I2S_ERROR_NOT_READY	Instance not initialized.

◆ i2s_deinit()

i2s_status_en i2s_deinit ( i2s_instance_en instance )

Deinitialize I2S instance.

Stops ongoing I2S operations, disables the peripheral, and resets the internal driver context for the specified instance. After this call, the instance must be reinitialized using i2s_init before performing further configuration or data transfer operations.

Parameters

instance I2S instance identifier.

Returns: i2s_status_en Status code indicating success or failure.

Return values

I2S_OK	Deinitialization successful.
I2S_ERROR_PARAMETER	Invalid I2S instance.
I2S_ERROR_NOT_INITIALIZED	Instance not initialized.

◆ i2s_intr_enable()

i2s_status_en i2s_intr_enable	(	i2s_instance_en	id,
		int	enable )

Enable or disable I2S interrupts.

Configures the interrupt generation for the specified I2S instance. This function enables or disables the interrupt at the peripheral level based on the value of the enable parameter.

Parameters

id	I2S instance identifier.
enable	Interrupt control flag. 1 : Enable interrupts. 0 : Disable interrupts.

Returns: i2s_status_en Status code indicating success or failure.

Return values

I2S_OK	Interrupt configuration successful.
I2S_ERROR_INVALID_PARAM	Invalid I2S instance or parameter.
I2S_ERROR_NOT_READY	Instance not initialized.

◆ i2s_get_config()

i2s_status_en i2s_get_config	(	i2s_instance_en	instance,
		i2s_direction_en	direction,
		i2s_config_t *	config )

Get I2S configuration.

Retrieves the current configuration for the specified instance.

Note: Returned configuration reflects the most recent settings applied via i2s_configure. Fields not tracked by hardware will reflect the driver-side cached values.

Parameters

instance	I2S instance identifier.
direction	I2S direction (TX or RX).
config	Pointer to configuration structure to populate.

Returns: i2s_status_en Status code indicating success or failure.

Return values

I2S_OK	Configuration returned successfully (scalar fields only).
I2S_ERROR_INVALID_PARAM	Invalid instance or config pointer.

◆ i2s_get_capabilities()

i2s_status_en i2s_get_capabilities	(	i2s_instance_en	instance,
		i2s_capabilities_t *	caps )

Get I2S capabilities.

Queries the hardware capabilities of the specified I2S instance.

Parameters

instance	I2S instance identifier.
caps	Pointer to capabilities structure to populate.

Returns: i2s_status_en Status code indicating success or failure.

Return values

I2S_OK	Capabilities returned successfully.
I2S_ERROR_INVALID_PARAM	Invalid instance or caps pointer.

◆ i2s_trigger()

i2s_status_en i2s_trigger	(	i2s_instance_en	instance,
		i2s_direction_en	direction,
		i2s_trigger_cmd_en	cmd )

Control I2S stream state.

Issues a trigger command to control the operational state of the specified I2S direction (TX or RX). Supported commands include START, STOP, PAUSE, RESUME, and PREPARE.

State transitions are validated against the current instance state. Invalid transitions are rejected.

Parameters

instance	I2S instance identifier.
direction	I2S direction (TX or RX).
cmd	Trigger command (i2s_trigger_cmd_en).

Returns: i2s_status_en

Return values

I2S_OK	Trigger command executed successfully.
I2S_ERROR_PARAMETER	Invalid instance, direction, or command.
I2S_ERROR_INVALID_STATE	Command not allowed in current state.

◆ i2s_register_callback()

i2s_status_en i2s_register_callback	(	i2s_instance_en	instance,
		i2s_event_cb_t	callback,
		void *	user_data )

Register or unregister I2S event callback.

Registers a single event callback for the specified I2S instance. The callback is invoked on transfer completion, error conditions, or other driver-generated events.

Only one callback may be active per instance. Passing NULL unregisters the currently registered callback.

Parameters

instance	I2S instance identifier.
callback	Event callback function pointer. Set to NULL to unregister.
user_data	User-defined context pointer passed to the callback during invocation.

Returns: i2s_status_en

Return values

I2S_OK	Callback registered or unregistered successfully.
I2S_ERROR_INVALID_PARAM	Invalid instance.
I2S_ERROR_NOT_INITIALIZED	Instance not initialized.

◆ i2s_register_buffer_callback()

i2s_status_en i2s_register_buffer_callback	(	i2s_instance_en	instance,
		i2s_buffer_cb_t	callback,
		void *	user_data )

Register or unregister buffer completion callback.

Registers a callback function that is invoked when a transmit or receive buffer transfer completes. The callback provides direct access to the completed buffer for processing, reuse, or release.

Only one buffer callback may be registered per instance. Passing NULL unregisters the current callback.

Parameters

instance	I2S instance identifier.
callback	Buffer completion callback function pointer. Set to NULL to unregister.
user_data	User-defined context pointer passed to the callback.

Returns: i2s_status_en

Return values

I2S_OK	Callback registered or unregistered successfully.
I2S_ERROR_INVALID_PARAM	Invalid instance.
I2S_ERROR_NOT_INITIALIZED	Instance not initialized.

◆ i2s_configure()

i2s_status_en i2s_configure	(	i2s_instance_en	id,
		i2s_direction_en	direction,
		const i2s_config_t *	cfg )

Configure I2S (clock + bit clock + mode + format).

Configure I2S module parameters.

Applies configuration parameters to the active I2S direction (TX or RX) of the given instance.

Parameters

id	I2S instance identifier.
direction	I2S direction (TX or RX).
cfg	Pointer to I2S configuration structure.

Returns: i2s_status_en

Return values

I2S_OK	Configuration applied successfully.
I2S_ERROR_INVALID_PARAM	Invalid instance, module, or NULL configuration pointer.
I2S_ERROR_INVALID_STATE	Instance not initialized or module in active state.
I2S_ERROR_NOT_SUPPORTED	Unsupported configuration parameter.

Wrapper that applies clock tree, bit clock divider, mode select, and format/config settings in one call.

Parameters

id	I2S instance identifier.
direction	I2S direction (TX or RX).
cfg	I2S configuration structure.

Returns: i2s_status_en

◆ i2s_write_async()

i2s_status_en i2s_write_async	(	i2s_instance_en	instance,
		const void *	buffer,
		size_t	size )

Write data to the I2S transmitter asynchronously (buffered copy).

Copies the provided data into the internal TX buffer. The caller must start streaming separately via i2s_trigger with I2S_TRIGGER_START. During streaming, this API can be called from the TX buffer callback to refill the completed buffer for the next transfer.

Parameters

instance	I2S instance identifier.
buffer	Pointer to the source buffer.
size	Size of the buffer in bytes.

Returns: i2s_status_en

Return values

I2S_OK	Buffer queued successfully for transmission.
I2S_ERROR_INVALID_PARAM	Invalid instance or buffer parameters.
I2S_ERROR_INVALID_STATE	I2S module not in READY or RUNNING state.
I2S_ERROR_NO_MEMORY	No space available in the transmit queue.

◆ i2s_read_async()

i2s_status_en i2s_read_async	(	i2s_instance_en	instance,
		void *	buffer,
		size_t	size )

Queue a receive buffer for asynchronous RX.

Provides a pre-allocated buffer for non-blocking reception. The buffer must remain valid until the registered buffer callback signals completion.

Parameters

instance	I2S instance identifier.
buffer	Pointer to the receive buffer.
size	Size of the buffer in bytes.

Returns: i2s_status_en

Return values

I2S_OK	Buffer queued successfully for reception.
I2S_ERROR_INVALID_PARAM	Invalid instance or buffer parameters.
I2S_ERROR_INVALID_STATE	I2S module not in READY or RUNNING state.
I2S_ERROR_NO_MEMORY	No space available in the receive queue.

◆ i2s_get_state()

i2s_state_en i2s_get_state	(	i2s_instance_en	instance,
		i2s_direction_en	direction )

Get the current state of the I2S driver for a specific direction.

Returns the internal driver state associated with the specified I2S instance and data direction (TX or RX). This can be used by the application to determine whether the driver is idle, running, or in an error condition before initiating new operations.

The returned state reflects the status of the transfer engine maintained by the driver and may be used for synchronization or flow control in higher-level application logic.

Parameters

instance	I2S instance identifier.
direction	Data direction for which the state is requested (TX or RX).

Returns: i2s_state_en

Return values

I2S_STATE_IDLE	No active transfer in the specified direction.
I2S_STATE_READY	I2S direction is configured and ready for transfer.
I2S_STATE_RUNNING	A transfer is currently in progress.
I2S_STATE_ERROR	The driver encountered an error condition.

◆ i2s_flush()

i2s_status_en i2s_flush	(	i2s_instance_en	instance,
		i2s_direction_en	direction )

Flush the I2S FIFO and reset transfer state for a direction.

Clears the hardware FIFO and resets the internal driver transfer state associated with the specified direction (TX or RX). This operation discards any pending or partially transferred data and prepares the direction for a fresh transfer sequence.

This function can be used to recover from underrun/overrun conditions or to ensure that stale data does not remain in the FIFO before starting a new transfer.

Note: Flushing during an active transfer may result in data loss. Applications should ensure that the transfer is stopped or in an appropriate state before invoking this API.

Parameters

instance	I2S instance identifier.
direction	Data direction to flush (TX or RX).

Returns: i2s_status_en

Return values

I2S_OK	FIFO and transfer state successfully flushed.
I2S_ERROR_INVALID_PARAM	Invalid instance or direction parameter.
I2S_ERROR_INVALID_STATE	I2S module not initialized or not in a valid state.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ i2s_event_cb_t

◆ i2s_buffer_cb_t

Function Documentation

◆ i2s_init()

◆ i2s_get_fifo_depth()

◆ i2s_set_fifo_depth()

◆ i2s_deinit()

◆ i2s_intr_enable()

◆ i2s_get_config()

◆ i2s_get_capabilities()

◆ i2s_trigger()

◆ i2s_register_callback()

◆ i2s_register_buffer_callback()

◆ i2s_configure()

◆ i2s_write_async()

◆ i2s_read_async()

◆ i2s_get_state()

◆ i2s_flush()