I²S Common API

I²S Instances

The following structures and functions are used by an I²S 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.

This will contain the TDM context when in TDM mode.

Param app_data:

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

Param 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. This is ignored when used in TDM mode.

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.

Param app_data:

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

Return:

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.

Param app_data:

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

Param num_in:

The number of input channels contained within the array.

Param 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.

Param app_data:

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

Param num_out:

The number of output channels contained within the array.

Param 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.

TDM Instances

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

typedef void (*tdm_post_port_init_t)(void *i2s_tdm_ctx)

TDM post resource initialization event callback.

The TDM component will call this after it first initializes the ports. This gives the app the chance to make adjustments to port timing which are often needed when clocking above 15MHz.

Param i2s_tdm_ctx:

Points to i2s_tdm_ctx_t struct allowing the resources to be modified after they have been enabled and initialised.

I2S_TDM_MAX_POUT_CNT

I2S_TDM_MAX_PIN_CNT

I2S_TDM_MAX_CH_PER_FRAME

TDM_CALLBACK_ATTR

This attribute must be specified on the TDM callback function provided by the application.

struct i2s_tdm_ctx_t

#include <i2s_tdm_slave.h>

Struct to hold an I2S TDM context.

The members in this struct should not be accessed directly.