I2S Interface

Detailed Description

Interface for I2S audio communication.

Summary

The I2S (Inter-IC Sound) interface provides APIs and definitions for I2S audio communication.

Data Structures
struct	i2s_callback_args_t
struct	i2s_status_t
struct	i2s_cfg_t
struct	i2s_api_t
struct	i2s_instance_t

Typedefs
typedef void	i2s_ctrl_t

Enumerations
enum	i2s_pcm_width_t
enum	i2s_word_length_t
enum	i2s_event_t
enum	i2s_mode_t
enum	i2s_mute_t
enum	i2s_ws_continue_t
enum	i2s_state_t

---

Data Structure Documentation

i2s_callback_args_t

struct i2s_callback_args_t

Callback function parameter data

Data Fields
void *	p_context	Placeholder for user data. Set in i2s_api_t::open function in i2s_cfg_t.
i2s_event_t	event	The event can be used to identify what caused the callback (overflow or error).

i2s_status_t

struct i2s_status_t

I2S status.

Data Fields
i2s_state_t	state	Current I2S state.

i2s_cfg_t

struct i2s_cfg_t

User configuration structure, used in open function

Data Fields
uint32_t	channel
i2s_pcm_width_t	pcm_width
	Audio PCM data width.
i2s_word_length_t	word_length
	Audio word length, bits must be >= i2s_cfg_t::pcm_width bits.
i2s_ws_continue_t	ws_continue
	Whether to continue WS transmission during idle state.
i2s_mode_t	operating_mode
	Master or slave mode.
transfer_instance_t const *	p_transfer_tx
transfer_instance_t const *	p_transfer_rx
void(*	p_callback )(i2s_callback_args_t *p_args)
void *	p_context
void const *	p_extend
	Extension parameter for hardware specific settings.
uint8_t	rxi_ipl
	Receive interrupt priority.
uint8_t	txi_ipl
	Transmit interrupt priority.
uint8_t	idle_err_ipl
	Idle/Error interrupt priority.
IRQn_Type	txi_irq
	Transmit IRQ number.
IRQn_Type	rxi_irq
	Receive IRQ number.
IRQn_Type	int_irq
	Idle/Error IRQ number.

Field Documentation

channel

uint32_t i2s_cfg_t::channel

Select a channel corresponding to the channel number of the hardware.

p_transfer_tx

transfer_instance_t const* i2s_cfg_t::p_transfer_tx

To use DMA for transmitting link a Transfer instance here. Set to NULL if unused.

p_transfer_rx

transfer_instance_t const* i2s_cfg_t::p_transfer_rx

To use DMA for receiving link a Transfer instance here. Set to NULL if unused.

p_callback

void(* i2s_cfg_t::p_callback) (i2s_callback_args_t *p_args)

Callback provided when an I2S ISR occurs. Set to NULL for no CPU interrupt.

p_context

void* i2s_cfg_t::p_context

Placeholder for user data. Passed to the user callback in i2s_callback_args_t.

i2s_api_t

struct i2s_api_t

I2S functions implemented at the HAL layer will follow this API.

Data Fields
fsp_err_t(*	open )(i2s_ctrl_t *const p_ctrl, i2s_cfg_t const *const p_cfg)
fsp_err_t(*	stop )(i2s_ctrl_t *const p_ctrl)
fsp_err_t(*	mute )(i2s_ctrl_t *const p_ctrl, i2s_mute_t const mute_enable)
fsp_err_t(*	write )(i2s_ctrl_t *const p_ctrl, void const *const p_src, uint32_t const bytes)
fsp_err_t(*	read )(i2s_ctrl_t *const p_ctrl, void *const p_dest, uint32_t const bytes)
fsp_err_t(*	writeRead )(i2s_ctrl_t *const p_ctrl, void const *const p_src, void *const p_dest, uint32_t const bytes)
fsp_err_t(*	statusGet )(i2s_ctrl_t *const p_ctrl, i2s_status_t *const p_status)
fsp_err_t(*	close )(i2s_ctrl_t *const p_ctrl)
fsp_err_t(*	callbackSet )(i2s_ctrl_t *const p_ctrl, void(*p_callback)(i2s_callback_args_t *), void *const p_context, i2s_callback_args_t *const p_callback_memory)

Field Documentation

open

fsp_err_t(* i2s_api_t::open) (i2s_ctrl_t *const p_ctrl, i2s_cfg_t const *const p_cfg)

Initial configuration.

Precondition

Peripheral clocks and any required output pins should be configured prior to calling this function.

Note

To reconfigure after calling this function, call i2s_api_t::close first.

Parameters

[in]	p_ctrl	Pointer to control block. Must be declared by user. Elements set here.
[in]	p_cfg	Pointer to configuration structure. All elements of this structure must be set by user.

stop

fsp_err_t(* i2s_api_t::stop) (i2s_ctrl_t *const p_ctrl)

Stop communication. Communication is stopped when callback is called with I2S_EVENT_IDLE.

Parameters

[in]

p_ctrl

Control block set in i2s_api_t::open call for this instance.

mute

fsp_err_t(* i2s_api_t::mute) (i2s_ctrl_t *const p_ctrl, i2s_mute_t const mute_enable)

Enable or disable mute.

Parameters

[in]	p_ctrl	Control block set in i2s_api_t::open call for this instance.
[in]	mute_enable	Whether to enable or disable mute.

write

fsp_err_t(* i2s_api_t::write) (i2s_ctrl_t *const p_ctrl, void const *const p_src, uint32_t const bytes)

Write I2S data. All transmit data is queued when callback is called with I2S_EVENT_TX_EMPTY. Transmission is complete when callback is called with I2S_EVENT_IDLE.

Parameters

[in]	p_ctrl	Control block set in i2s_api_t::open call for this instance.
[in]	p_src	Buffer of PCM samples. Must be 4 byte aligned.
[in]	bytes	Number of bytes in the buffer. Recommended requesting a multiple of 8 bytes. If not a multiple of 8, padding 0s will be added to transmission to make it a multiple of 8.

read

fsp_err_t(* i2s_api_t::read) (i2s_ctrl_t *const p_ctrl, void *const p_dest, uint32_t const bytes)

Read I2S data. Reception is complete when callback is called with I2S_EVENT_RX_EMPTY.

Parameters

[in]	p_ctrl	Control block set in i2s_api_t::open call for this instance.
[in]	p_dest	Buffer to store PCM samples. Must be 4 byte aligned.
[in]	bytes	Number of bytes in the buffer. Recommended requesting a multiple of 8 bytes. If not a multiple of 8, receive will stop at the multiple of 8 below requested bytes.

writeRead

fsp_err_t(* i2s_api_t::writeRead) (i2s_ctrl_t *const p_ctrl, void const *const p_src, void *const p_dest, uint32_t const bytes)

Simultaneously write and read I2S data. Transmission and reception are complete when callback is called with I2S_EVENT_IDLE.

Parameters

[in]	p_ctrl	Control block set in i2s_api_t::open call for this instance.
[in]	p_src	Buffer of PCM samples. Must be 4 byte aligned.
[in]	p_dest	Buffer to store PCM samples. Must be 4 byte aligned.
[in]	bytes	Number of bytes in the buffers. Recommended requesting a multiple of 8 bytes. If not a multiple of 8, padding 0s will be added to transmission to make it a multiple of 8, and receive will stop at the multiple of 8 below requested bytes.

statusGet

fsp_err_t(* i2s_api_t::statusGet) (i2s_ctrl_t *const p_ctrl, i2s_status_t *const p_status)

Get current status and store it in provided pointer p_status.

Parameters

[in]	p_ctrl	Control block set in i2s_api_t::open call for this instance.
[out]	p_status	Current status of the driver.

close

fsp_err_t(* i2s_api_t::close) (i2s_ctrl_t *const p_ctrl)

Allows driver to be reconfigured and may reduce power consumption.

Parameters

[in]

p_ctrl

Control block set in i2s_api_t::open call for this instance.

callbackSet

fsp_err_t(* i2s_api_t::callbackSet) (i2s_ctrl_t *const p_ctrl, void(*p_callback)(i2s_callback_args_t *), void *const p_context, i2s_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Parameters

[in]	p_ctrl	Pointer to the I2S control block.
[in]	p_callback	Callback function
[in]	p_context	Pointer to send to callback function
[in]	p_working_memory	Pointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

i2s_instance_t

struct i2s_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
i2s_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
i2s_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
i2s_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

i2s_ctrl_t

typedef void i2s_ctrl_t

I2S control block. Allocate an instance specific control block to pass into the I2S API calls.

Enumeration Type Documentation

i2s_pcm_width_t

enum i2s_pcm_width_t

Audio PCM width

Enumerator
I2S_PCM_WIDTH_8_BITS	Using 8-bit PCM.
I2S_PCM_WIDTH_16_BITS	Using 16-bit PCM.
I2S_PCM_WIDTH_18_BITS	Using 18-bit PCM.
I2S_PCM_WIDTH_20_BITS	Using 20-bit PCM.
I2S_PCM_WIDTH_22_BITS	Using 22-bit PCM.
I2S_PCM_WIDTH_24_BITS	Using 24-bit PCM.
I2S_PCM_WIDTH_32_BITS	Using 32-bit PCM.

i2s_word_length_t

enum i2s_word_length_t

Audio system word length.

Enumerator
I2S_WORD_LENGTH_8_BITS	Using 8-bit system word length.
I2S_WORD_LENGTH_16_BITS	Using 16-bit system word length.
I2S_WORD_LENGTH_24_BITS	Using 24-bit system word length.
I2S_WORD_LENGTH_32_BITS	Using 32-bit system word length.
I2S_WORD_LENGTH_48_BITS	Using 48-bit system word length.
I2S_WORD_LENGTH_64_BITS	Using 64-bit system word length.
I2S_WORD_LENGTH_128_BITS	Using 128-bit system word length.
I2S_WORD_LENGTH_256_BITS	Using 256-bit system word length.

i2s_event_t

enum i2s_event_t

Events that can trigger a callback function

Enumerator
I2S_EVENT_IDLE	Communication is idle.
I2S_EVENT_TX_EMPTY	Transmit buffer is below FIFO trigger level.
I2S_EVENT_RX_FULL	Receive buffer is above FIFO trigger level.

i2s_mode_t

enum i2s_mode_t

I2S communication mode

Enumerator
I2S_MODE_SLAVE	Slave mode.
I2S_MODE_MASTER	Master mode.

i2s_mute_t

enum i2s_mute_t

Mute audio samples.

Enumerator
I2S_MUTE_OFF	Disable mute.
I2S_MUTE_ON	Enable mute.

i2s_ws_continue_t

enum i2s_ws_continue_t

Whether to continue WS (word select line) transmission during idle state.

Enumerator
I2S_WS_CONTINUE_ON	Enable WS continue mode.
I2S_WS_CONTINUE_OFF	Disable WS continue mode.

i2s_state_t

enum i2s_state_t

Possible status values returned by i2s_api_t::statusGet.

Enumerator
I2S_STATE_IN_USE	I2S is in use.
I2S_STATE_STOPPED	I2S is stopped.