rtos_i2s_driver

Modules
	rtos_i2s_driver_core
	rtos_i2s_master_driver
	rtos_i2s_slave_driver
	rtos_i2s_driver_rpc

Classes
struct	rtos_i2s_struct

Macros
#define	RTOS_I2S_APP_SEND_FILTER_CALLBACK_ATTR   __attribute__((fptrgroup("rtos_i2s_send_filter_cb_fptr_grp")))
#define	RTOS_I2S_APP_RECEIVE_FILTER_CALLBACK_ATTR   __attribute__((fptrgroup("rtos_i2s_receive_filter_cb_fptr_grp")))

Typedefs
typedef struct rtos_i2s_struct	rtos_i2s_t
typedef size_t(*	rtos_i2s_send_filter_cb_t) (rtos_i2s_t *ctx, void *app_data, int32_t *i2s_frame, size_t i2s_frame_size, int32_t *send_buf, size_t samples_available)
typedef size_t(*	rtos_i2s_receive_filter_cb_t) (rtos_i2s_t *ctx, void *app_data, int32_t *i2s_frame, size_t i2s_frame_size, int32_t *receive_buf, size_t sample_spaces_free)

Functions
int	rtos_i2s_mclk_bclk_ratio (const unsigned audio_clock_frequency, const unsigned sample_rate)
void	rtos_i2s_send_filter_cb_set (rtos_i2s_t *ctx, rtos_i2s_send_filter_cb_t send_filter_cb, void *send_filter_app_data)
void	rtos_i2s_receive_filter_cb_set (rtos_i2s_t *ctx, rtos_i2s_receive_filter_cb_t receive_filter_cb, void *receive_filter_app_data)
void	rtos_i2s_start (rtos_i2s_t *i2s_ctx, unsigned mclk_bclk_ratio, i2s_mode_t mode, size_t recv_buffer_size, size_t send_buffer_size, unsigned interrupt_core_id)

Detailed Description

The public API for using the RTOS I2S driver.

Macro Definition Documentation

RTOS_I2S_APP_RECEIVE_FILTER_CALLBACK_ATTR

#define RTOS_I2S_APP_RECEIVE_FILTER_CALLBACK_ATTR   __attribute__((fptrgroup("rtos_i2s_receive_filter_cb_fptr_grp")))

This attribute must be specified on all RTOS I2S receive filter callback functions provided by the application.

RTOS_I2S_APP_SEND_FILTER_CALLBACK_ATTR

#define RTOS_I2S_APP_SEND_FILTER_CALLBACK_ATTR   __attribute__((fptrgroup("rtos_i2s_send_filter_cb_fptr_grp")))

This attribute must be specified on all RTOS I2S send filter callback functions provided by the application.

Typedef Documentation

rtos_i2s_receive_filter_cb_t

typedef size_t(* rtos_i2s_receive_filter_cb_t) (rtos_i2s_t *ctx, void *app_data, int32_t *i2s_frame, size_t i2s_frame_size, int32_t *receive_buf, size_t sample_spaces_free)

Function pointer type for application provided RTOS I2S receive filter callback functions.

These callback functions are called when an I2S driver instance has received the next audio frame from its interface. By default, audio frames received from the driver's interface are put directly into its receive buffer. However, this gives the application an opportunity to override this and provide filtering.

These functions must not block.

Parameters

ctx	A pointer to the associated I2C slave driver instance.
app_data	A pointer to application specific data provided by the application. Used to share data between this callback function and the application.
i2s_frame	A pointer to the buffer where the callback should read the next received frame from The callback should use this as the input to its filter.
i2s_frame_size	The number of samples that should be read from i2s_frame.
receive_buf	A pointer to the next frame in the driver's send buffer. The callback should use this as the input to its filter.
sample_spaces_free	The number of sample spaces free in receive_buf.

Returns

the number of samples written to receive_buf.

rtos_i2s_send_filter_cb_t

typedef size_t(* rtos_i2s_send_filter_cb_t) (rtos_i2s_t *ctx, void *app_data, int32_t *i2s_frame, size_t i2s_frame_size, int32_t *send_buf, size_t samples_available)

Function pointer type for application provided RTOS I2S send filter callback functions.

These callback functions are called when an I2S driver instance needs output the next audio frame to its interface. By default, audio frames in the driver's send buffer are output directly to its interface. However, this gives the application an opportunity to override this and provide filtering.

These functions must not block.

Parameters

ctx	A pointer to the associated I2C slave driver instance.
app_data	A pointer to application specific data provided by the application. Used to share data between this callback function and the application.
i2s_frame	A pointer to the buffer where the callback should write the next frame to send.
i2s_frame_size	The number of samples that should be written to i2s_frame.
send_buf	A pointer to the next frame in the driver's send buffer. The callback should use this as the input to its filter.
samples_available	The number of samples available in send_buf.

Returns

the number of samples read out of send_buf.

rtos_i2s_t

typedef struct rtos_i2s_struct rtos_i2s_t

Typedef to the RTOS I2S driver instance struct.

Function Documentation

rtos_i2s_mclk_bclk_ratio()

int rtos_i2s_mclk_bclk_ratio ( const unsigned  audio_clock_frequency, const unsigned  sample_rate  )

inline

Helper function to calculate the MCLK/BCLK ratio given the audio clock frequency at the master clock pin and the desired sample rate.

Parameters

audio_clock_frequency	The frequency of the audio clock at the port p_mclk.
sample_rate	The desired sample rate.

Returns

the MCLK/BCLK ratio that should be provided to rtos_i2s_start().

rtos_i2s_start()

void rtos_i2s_start	(	rtos_i2s_t *	i2s_ctx,
		unsigned	mclk_bclk_ratio,
		i2s_mode_t	mode,
		size_t	recv_buffer_size,
		size_t	send_buffer_size,
		unsigned	interrupt_core_id
	)

Starts an RTOS I2S driver instance. This must only be called by the tile that owns the driver instance. It must be called after starting the RTOS from an RTOS thread, and must be called before any of the core I2S driver functions are called with this instance.

One of rtos_i2s_master_init(), rtos_i2s_master_ext_clock_init, or rtos_i2s_slave_init() must be called on this I2S driver instance prior to calling this.

Parameters

i2s_ctx	A pointer to the I2S driver instance to start.
mclk_bclk_ratio	The master clock to bit clock ratio. This may be computed by the helper function rtos_i2s_mclk_bclk_ratio(). This is only used if the I2S instance was initialized with rtos_i2s_master_init(). Otherwise it is ignored.
mode	The mode of the LR clock. See i2s_mode_t.
recv_buffer_size	The size in frames of the input buffer. Each frame is two samples (left and right channels) per input port. For example, a size of two here when num_in is three would create a buffer that holds up to 12 samples.
send_buffer_size	The size in frames of the output buffer. Each frame is two samples (left and right channels) per output port. For example, a size of two here when num_out is three would create a buffer that holds up to 12 samples. Frames transmitted by rtos_i2s_tx() are stored in this buffers before they are sent out to the I2S interface.
interrupt_core_id	The ID of the core on which to enable the I2S interrupt.