I2S Common API

The following structures and functions are used by an I2S master or slave instance.

enum i2s_mode

I2S mode.

This type is used to describe the I2S mode.

Values:

enumerator I2S_MODE_I2S

The LR clock transitions ahead of the data by one bit clock.

enumerator I2S_MODE_LEFT_JUSTIFIED

The LR clock and data are phase aligned.

enum i2s_slave_bclk_polarity

I2S slave bit clock polarity.

Standard I2S is positive, that is toggle data and LR clock on falling edge of bit clock and sample them on rising edge of bit clock. Some masters have it the other way around.

Values:

enumerator I2S_SLAVE_SAMPLE_ON_BCLK_RISING

Toggle falling, sample rising (default if not set)

enumerator I2S_SLAVE_SAMPLE_ON_BCLK_FALLING

Toggle rising, sample falling

enum i2s_restart

Restart command type.

Restart commands that can be signalled to the I2S or TDM component.

Values:

enumerator I2S_NO_RESTART

Do not restart.

enumerator I2S_RESTART

Restart the bus (causes the I2S/TDM to stop and a new init callback to occur allowing reconfiguration of the BUS).

enumerator I2S_SHUTDOWN

Shutdown. This will cause the I2S/TDM component to exit.

typedef enum i2s_mode i2s_mode_t

I2S mode.

This type is used to describe the I2S mode.

typedef enum i2s_slave_bclk_polarity i2s_slave_bclk_polarity_t

I2S slave bit clock polarity.

Standard I2S is positive, that is toggle data and LR clock on falling edge of bit clock and sample them on rising edge of bit clock. Some masters have it the other way around.

typedef struct i2s_config i2s_config_t

I2S configuration structure.

This structure describes the configuration of an I2S bus.

typedef enum i2s_restart i2s_restart_t

Restart command type.

Restart commands that can be signalled to the I2S or TDM component.

typedef void (*i2s_init_t)(void *app_data, i2s_config_t *i2s_config)

I2S initialization event callback.

The I2S component will call this when it first initializes on first run of after a restart.

Parameters

  • app_data – Points to application specific data supplied by the application. May be used for context data specific to each I2S task instance.

  • i2s_config – This structure is provided if the connected component drives an I2S bus. The members of the structure should be set to the required configuration.

typedef i2s_restart_t (*i2s_restart_check_t)(void *app_data)

I2S restart check callback.

This callback is called once per frame. The application must return the required restart behavior.

Parameters

app_data – Points to application specific data supplied by the application. May be used for context data specific to each I2S task instance.

Returns

The return value should be set to I2S_NO_RESTART, I2S_RESTART or I2S_SHUTDOWN.

typedef void (*i2s_receive_t)(void *app_data, size_t num_in, const int32_t *samples)

Receive an incoming frame of samples.

This callback will be called when a new frame of samples is read in by the I2S task.

Parameters

  • app_data – Points to application specific data supplied by the application. May be used for context data specific to each I2S task instance.

  • num_in – The number of input channels contained within the array.

  • samples – The samples data array as signed 32-bit values. The component may not have 32-bits of accuracy (for example, many I2S codecs are 24-bit), in which case the bottom bits will be arbitrary values.

typedef void (*i2s_send_t)(void *app_data, size_t num_out, int32_t *samples)

Request an outgoing frame of samples.

This callback will be called when the I2S task needs a new frame of samples.

Parameters

  • app_data – Points to application specific data supplied by the application. May be used for context data specific to each I2S task instance.

  • num_out – The number of output channels contained within the array.

  • samples – The samples data array as signed 32-bit values. The component may not have 32-bits of accuracy (for example, many I2S codecs are 24-bit), in which case the bottom bits will be arbitrary values.

I2S_MAX_DATALINES
I2S_CHANS_PER_FRAME
I2S_CALLBACK_ATTR

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

struct i2s_config
#include <i2s.h>

I2S configuration structure.

This structure describes the configuration of an I2S bus.

struct i2s_callback_group_t
#include <i2s.h>

Callback group representing callback events that can occur during the operation of the I2S task. Must be initialized by the application prior to passing it to one of the I2S tasks.