I2S RTOS Driver

This driver can be used to instantiate and control an I2S master or slave mode I/O interface on xcore in an RTOS application.

Initialization API

The following structures and functions are used to initialize and start an I2S driver instance.

typedef struct rtos_i2s_struct rtos_i2s_t

Typedef to the RTOS I2S driver instance struct.

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.

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.

inline int rtos_i2s_mclk_bclk_ratio(const unsigned audio_clock_frequency, const unsigned sample_rate)

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().

inline 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)
inline 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)

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.

RTOS_I2S_APP_SEND_FILTER_CALLBACK_ATTR

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

RTOS_I2S_APP_RECEIVE_FILTER_CALLBACK_ATTR

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

struct rtos_i2s_struct
#include <rtos_i2s.h>

Struct representing an RTOS I2S driver instance.

The members in this struct should not be accessed directly.

Core API

The following functions are the core I2S driver functions that are used after it has been initialized and started.

inline size_t rtos_i2s_rx(rtos_i2s_t *ctx, int32_t *i2s_sample_buf, size_t frame_count, unsigned timeout)

Receives sample frames from the I2S interface.

This function will block until new frames are available.

Parameters

  • ctx – A pointer to the I2S driver instance to use.

  • i2s_sample_buf – A buffer to copy the received sample frames into.

  • frame_count – The number of frames to receive from the buffer. This must be less than or equal to the size of the input buffer specified to rtos_i2s_start().

  • timeout – The amount of time to wait before the requested number of frames becomes available.

Returns

The number of frames actually received into i2s_sample_buf.

inline size_t rtos_i2s_tx(rtos_i2s_t *ctx, int32_t *i2s_sample_buf, size_t frame_count, unsigned timeout)

Transmits sample frames out to the I2S interface.

The samples are stored into a buffer and are not necessarily sent out to the I2S interface before this function returns.

Parameters

  • ctx – A pointer to the I2S driver instance to use.

  • i2s_sample_buf – A buffer containing the sample frames to transmit out to the I2S interface.

  • frame_count – The number of frames to transmit out from the buffer. This must be less than or equal to the size of the output buffer specified to rtos_i2s_start().

  • timeout – The amount of time to wait before there is enough space in the send buffer to accept the frames to be transmitted.

Returns

The number of frames actually stored into the buffer.

RPC Initialization API

The following functions may be used to share a I2S driver instance with other xcore tiles. Tiles that the driver instance is shared with may call any of the core functions listed above.

void rtos_i2s_rpc_client_init(rtos_i2s_t *i2s_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *host_intertile_ctx)

Initializes an RTOS I2S driver instance on a client tile. This allows a tile that does not own the actual driver instance to use a driver instance on another tile. This will be called instead of on of the RTOS I2S init functions. The host tile that owns the actual instance must simultaneously call rtos_i2s_rpc_host_init().

Parameters

  • i2s_ctx – A pointer to the I2S driver instance to initialize.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as i2s_ctx.

  • host_intertile_ctx – A pointer to the intertile driver instance to use for performing the communication between the client and host tiles. This must have the same scope as i2s_ctx.

void rtos_i2s_rpc_host_init(rtos_i2s_t *i2s_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *client_intertile_ctx[], size_t remote_client_count)

Performs additional initialization on a I2S driver instance to allow client tiles to use the I2S driver instance. Each client tile that will use this instance must simultaneously call rtos_i2s_rpc_client_init().

Parameters

  • i2s_ctx – A pointer to the I2S driver instance to share with clients.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as i2s_ctx.

  • client_intertile_ctx – An array of pointers to the intertile driver instances to use for performing the communication between the host tile and each client tile. This must have the same scope as i2s_ctx.

  • remote_client_count – The number of client tiles to share this driver instance with.

void rtos_i2s_rpc_config(rtos_i2s_t *i2s_ctx, unsigned intertile_port, unsigned host_task_priority)

Configures the RPC for a I2S driver instance. This must be called by both the host tile and all client tiles.

On the client tiles this must be called after calling rtos_i2s_rpc_client_init(). After calling this, the client tile may immediately begin to call the core I2S functions on this driver instance. It does not need to wait for the host to call rtos_i2s_start().

On the host tile this must be called both after calling rtos_i2s_rpc_host_init() and before calling rtos_i2s_start().

Parameters

  • i2s_ctx – A pointer to the I2S driver instance to configure the RPC for.

  • intertile_port – The port number on the intertile channel to use for transferring the RPC requests and responses for this driver instance. This port must not be shared by any other functions. The port must be the same for the host and all its clients.

  • host_task_priority – The priority to use for the task on the host tile that handles RPC requests from the clients.