MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
I2S Driver

Files

file  fsl_i2s.h
 

Data Structures

struct  i2s_config_t
 I2S configuration structure. More...
 
struct  i2s_transfer_t
 Buffer to transfer from or receive audio data into. More...
 
struct  i2s_handle_t
 Members not to be accessed / modified outside of the driver. More...
 

Macros

#define I2S_NUM_BUFFERS   (4U)
 Number of buffers . More...
 

Typedefs

typedef void(* i2s_transfer_callback_t )(I2S_Type *base, i2s_handle_t *handle, status_t completionStatus, void *userData)
 Callback function invoked from transactional API on completion of a single buffer transfer. More...
 

Enumerations

enum  {
  kStatus_I2S_BufferComplete,
  kStatus_I2S_Done = MAKE_STATUS(kStatusGroup_I2S, 1),
  kStatus_I2S_Busy
}
 _i2s_status I2S status codes. More...
 
enum  i2s_flags_t {
  kI2S_TxErrorFlag = I2S_FIFOINTENSET_TXERR_MASK,
  kI2S_TxLevelFlag = I2S_FIFOINTENSET_TXLVL_MASK,
  kI2S_RxErrorFlag = I2S_FIFOINTENSET_RXERR_MASK,
  kI2S_RxLevelFlag = I2S_FIFOINTENSET_RXLVL_MASK
}
 I2S flags. More...
 
enum  i2s_master_slave_t {
  kI2S_MasterSlaveNormalSlave = 0x0,
  kI2S_MasterSlaveWsSyncMaster = 0x1,
  kI2S_MasterSlaveExtSckMaster = 0x2,
  kI2S_MasterSlaveNormalMaster = 0x3
}
 Master / slave mode. More...
 
enum  i2s_mode_t {
  kI2S_ModeI2sClassic = 0x0,
  kI2S_ModeDspWs50 = 0x1,
  kI2S_ModeDspWsShort = 0x2,
  kI2S_ModeDspWsLong = 0x3
}
 I2S mode. More...
 
enum  {
  kI2S_SecondaryChannel1 = 0U,
  kI2S_SecondaryChannel2 = 1U,
  kI2S_SecondaryChannel3 = 2U
}
 _i2s_secondary_channel I2S secondary channel. More...
 

Driver version

#define FSL_I2S_DRIVER_VERSION   (MAKE_VERSION(2, 2, 0))
 I2S driver version 2.2.0. More...
 

Initialization and deinitialization

void I2S_TxInit (I2S_Type *base, const i2s_config_t *config)
 Initializes the FLEXCOMM peripheral for I2S transmit functionality. More...
 
void I2S_RxInit (I2S_Type *base, const i2s_config_t *config)
 Initializes the FLEXCOMM peripheral for I2S receive functionality. More...
 
void I2S_TxGetDefaultConfig (i2s_config_t *config)
 Sets the I2S Tx configuration structure to default values. More...
 
void I2S_RxGetDefaultConfig (i2s_config_t *config)
 Sets the I2S Rx configuration structure to default values. More...
 
void I2S_Deinit (I2S_Type *base)
 De-initializes the I2S peripheral. More...
 
void I2S_SetBitClockRate (I2S_Type *base, uint32_t sourceClockHz, uint32_t sampleRate, uint32_t bitWidth, uint32_t channelNumbers)
 Transmitter/Receiver bit clock rate configurations. More...
 

Non-blocking API

void I2S_TxTransferCreateHandle (I2S_Type *base, i2s_handle_t *handle, i2s_transfer_callback_t callback, void *userData)
 Initializes handle for transfer of audio data. More...
 
status_t I2S_TxTransferNonBlocking (I2S_Type *base, i2s_handle_t *handle, i2s_transfer_t transfer)
 Begins or queue sending of the given data. More...
 
void I2S_TxTransferAbort (I2S_Type *base, i2s_handle_t *handle)
 Aborts sending of data. More...
 
void I2S_RxTransferCreateHandle (I2S_Type *base, i2s_handle_t *handle, i2s_transfer_callback_t callback, void *userData)
 Initializes handle for reception of audio data. More...
 
status_t I2S_RxTransferNonBlocking (I2S_Type *base, i2s_handle_t *handle, i2s_transfer_t transfer)
 Begins or queue reception of data into given buffer. More...
 
void I2S_RxTransferAbort (I2S_Type *base, i2s_handle_t *handle)
 Aborts receiving of data. More...
 
status_t I2S_TransferGetCount (I2S_Type *base, i2s_handle_t *handle, size_t *count)
 Returns number of bytes transferred so far. More...
 
status_t I2S_TransferGetErrorCount (I2S_Type *base, i2s_handle_t *handle, size_t *count)
 Returns number of buffer underruns or overruns. More...
 

Enable / disable

static void I2S_Enable (I2S_Type *base)
 Enables I2S operation. More...
 
void I2S_EnableSecondaryChannel (I2S_Type *base, uint32_t channel, bool oneChannel, uint32_t position)
 Enables I2S secondary channel. More...
 
static void I2S_DisableSecondaryChannel (I2S_Type *base, uint32_t channel)
 Disables I2S secondary channel. More...
 
static void I2S_Disable (I2S_Type *base)
 Disables I2S operation. More...
 

Interrupts

static void I2S_EnableInterrupts (I2S_Type *base, uint32_t interruptMask)
 Enables I2S FIFO interrupts. More...
 
static void I2S_DisableInterrupts (I2S_Type *base, uint32_t interruptMask)
 Disables I2S FIFO interrupts. More...
 
static uint32_t I2S_GetEnabledInterrupts (I2S_Type *base)
 Returns the set of currently enabled I2S FIFO interrupts. More...
 
void I2S_TxHandleIRQ (I2S_Type *base, i2s_handle_t *handle)
 Invoked from interrupt handler when transmit FIFO level decreases. More...
 
void I2S_RxHandleIRQ (I2S_Type *base, i2s_handle_t *handle)
 Invoked from interrupt handler when receive FIFO level decreases. More...
 

Detailed Description


Data Structure Documentation

struct i2s_config_t

Data Fields

i2s_master_slave_t masterSlave
 Master / slave configuration.
 
i2s_mode_t mode
 I2S mode.
 
bool rightLow
 Right channel data in low portion of FIFO.
 
bool leftJust
 Left justify data in FIFO.
 
bool pdmData
 Data source is the D-Mic subsystem.
 
bool sckPol
 SCK polarity.
 
bool wsPol
 WS polarity.
 
uint16_t divider
 Flexcomm function clock divider (1 - 4096)
 
bool oneChannel
 true mono, false stereo
 
uint8_t dataLength
 Data length (4 - 32)
 
uint16_t frameLength
 Frame width (4 - 512)
 
uint16_t position
 Data position in the frame.
 
uint8_t watermark
 FIFO trigger level.
 
bool txEmptyZero
 Transmit zero when buffer becomes empty or last item.
 
bool pack48
 Packing format for 48-bit data (false - 24 bit values, true - alternating 32-bit and 16-bit values)
 
struct i2s_transfer_t

Data Fields

uint8_t * data
 Pointer to data buffer. More...
 
size_t dataSize
 Buffer size in bytes. More...
 

Field Documentation

uint8_t* i2s_transfer_t::data
size_t i2s_transfer_t::dataSize
struct _i2s_handle

Transactional state of the intialized transfer or receive I2S operation.

Data Fields

uint32_t state
 State of transfer.
 
i2s_transfer_callback_t completionCallback
 Callback function pointer.
 
void * userData
 Application data passed to callback.
 
bool oneChannel
 true mono, false stereo
 
uint8_t dataLength
 Data length (4 - 32)
 
bool pack48
 Packing format for 48-bit data (false - 24 bit values, true - alternating 32-bit and 16-bit values)
 
uint8_t watermark
 FIFO trigger level.
 
bool useFifo48H
 When dataLength 17-24: true use FIFOWR48H, false use FIFOWR.
 
volatile i2s_transfer_t i2sQueue [I2S_NUM_BUFFERS]
 Transfer queue storing transfer buffers.
 
volatile uint8_t queueUser
 Queue index where user's next transfer will be stored.
 
volatile uint8_t queueDriver
 Queue index of buffer actually used by the driver.
 
volatile uint32_t errorCount
 Number of buffer underruns/overruns.
 
volatile uint32_t transferCount
 Number of bytes transferred.
 

Macro Definition Documentation

#define FSL_I2S_DRIVER_VERSION   (MAKE_VERSION(2, 2, 0))
#define I2S_NUM_BUFFERS   (4U)

Typedef Documentation

typedef void(* i2s_transfer_callback_t)(I2S_Type *base, i2s_handle_t *handle, status_t completionStatus, void *userData)
Parameters
baseI2S base pointer.
handlepointer to I2S transaction.
completionStatusstatus of the transaction.
userDataoptional pointer to user arguments data.

Enumeration Type Documentation

anonymous enum
Enumerator
kStatus_I2S_BufferComplete 

Transfer from/into a single buffer has completed.

kStatus_I2S_Done 

All buffers transfers have completed.

kStatus_I2S_Busy 

Already performing a transfer and cannot queue another buffer.

Note
These enums are meant to be OR'd together to form a bit mask.
Enumerator
kI2S_TxErrorFlag 

TX error interrupt.

kI2S_TxLevelFlag 

TX level interrupt.

kI2S_RxErrorFlag 

RX error interrupt.

kI2S_RxLevelFlag 

RX level interrupt.

Enumerator
kI2S_MasterSlaveNormalSlave 

Normal slave.

kI2S_MasterSlaveWsSyncMaster 

WS synchronized master.

kI2S_MasterSlaveExtSckMaster 

Master using existing SCK.

kI2S_MasterSlaveNormalMaster 

Normal master.

enum i2s_mode_t
Enumerator
kI2S_ModeI2sClassic 

I2S classic mode.

kI2S_ModeDspWs50 

DSP mode, WS having 50% duty cycle.

kI2S_ModeDspWsShort 

DSP mode, WS having one clock long pulse.

kI2S_ModeDspWsLong 

DSP mode, WS having one data slot long pulse.

anonymous enum
Enumerator
kI2S_SecondaryChannel1 

secondary channel 1

kI2S_SecondaryChannel2 

secondary channel 2

kI2S_SecondaryChannel3 

secondary channel 3

Function Documentation

void I2S_TxInit ( I2S_Type *  base,
const i2s_config_t config 
)

Ungates the FLEXCOMM clock and configures the module for I2S transmission using a configuration structure. The configuration structure can be custom filled or set with default values by I2S_TxGetDefaultConfig().

Note
This API should be called at the beginning of the application to use the I2S driver.
Parameters
baseI2S base pointer.
configpointer to I2S configuration structure.
void I2S_RxInit ( I2S_Type *  base,
const i2s_config_t config 
)

Ungates the FLEXCOMM clock and configures the module for I2S receive using a configuration structure. The configuration structure can be custom filled or set with default values by I2S_RxGetDefaultConfig().

Note
This API should be called at the beginning of the application to use the I2S driver.
Parameters
baseI2S base pointer.
configpointer to I2S configuration structure.
void I2S_TxGetDefaultConfig ( i2s_config_t config)

This API initializes the configuration structure for use in I2S_TxInit(). The initialized structure can remain unchanged in I2S_TxInit(), or it can be modified before calling I2S_TxInit(). Example:

Default values:

* config->rightLow = false;
* config->leftJust = false;
* config->pdmData = false;
* config->sckPol = false;
* config->wsPol = false;
* config->divider = 1;
* config->oneChannel = false;
* config->dataLength = 16;
* config->frameLength = 32;
* config->position = 0;
* config->watermark = 4;
* config->txEmptyZero = true;
* config->pack48 = false;
*
Parameters
configpointer to I2S configuration structure.
void I2S_RxGetDefaultConfig ( i2s_config_t config)

This API initializes the configuration structure for use in I2S_RxInit(). The initialized structure can remain unchanged in I2S_RxInit(), or it can be modified before calling I2S_RxInit(). Example:

Default values:

* config->rightLow = false;
* config->leftJust = false;
* config->pdmData = false;
* config->sckPol = false;
* config->wsPol = false;
* config->divider = 1;
* config->oneChannel = false;
* config->dataLength = 16;
* config->frameLength = 32;
* config->position = 0;
* config->watermark = 4;
* config->txEmptyZero = false;
* config->pack48 = false;
*
Parameters
configpointer to I2S configuration structure.
void I2S_Deinit ( I2S_Type *  base)

This API gates the FLEXCOMM clock. The I2S module can't operate unless I2S_TxInit or I2S_RxInit is called to enable the clock.

Parameters
baseI2S base pointer.
void I2S_SetBitClockRate ( I2S_Type *  base,
uint32_t  sourceClockHz,
uint32_t  sampleRate,
uint32_t  bitWidth,
uint32_t  channelNumbers 
)
Parameters
baseSAI base pointer.
sourceClockHz,bitclock source frequency.
sampleRateaudio data sample rate.
bitWidth,audiodata bitWidth.
channelNumbers,audiochannel numbers.
void I2S_TxTransferCreateHandle ( I2S_Type *  base,
i2s_handle_t *  handle,
i2s_transfer_callback_t  callback,
void *  userData 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.
callbackfunction to be called back when transfer is done or fails.
userDatapointer to data passed to callback.
status_t I2S_TxTransferNonBlocking ( I2S_Type *  base,
i2s_handle_t *  handle,
i2s_transfer_t  transfer 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.
transferdata buffer.
Return values
kStatus_Success
kStatus_I2S_Busyif all queue slots are occupied with unsent buffers.
void I2S_TxTransferAbort ( I2S_Type *  base,
i2s_handle_t *  handle 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.
void I2S_RxTransferCreateHandle ( I2S_Type *  base,
i2s_handle_t *  handle,
i2s_transfer_callback_t  callback,
void *  userData 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.
callbackfunction to be called back when transfer is done or fails.
userDatapointer to data passed to callback.
status_t I2S_RxTransferNonBlocking ( I2S_Type *  base,
i2s_handle_t *  handle,
i2s_transfer_t  transfer 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.
transferdata buffer.
Return values
kStatus_Success
kStatus_I2S_Busyif all queue slots are occupied with buffers which are not full.
void I2S_RxTransferAbort ( I2S_Type *  base,
i2s_handle_t *  handle 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.
status_t I2S_TransferGetCount ( I2S_Type *  base,
i2s_handle_t *  handle,
size_t *  count 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.
[out]countnumber of bytes transferred so far by the non-blocking transaction.
Return values
kStatus_Success
kStatus_NoTransferInProgressthere is no non-blocking transaction currently in progress.
status_t I2S_TransferGetErrorCount ( I2S_Type *  base,
i2s_handle_t *  handle,
size_t *  count 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.
[out]countnumber of transmit errors encountered so far by the non-blocking transaction.
Return values
kStatus_Success
kStatus_NoTransferInProgressthere is no non-blocking transaction currently in progress.
static void I2S_Enable ( I2S_Type *  base)
inlinestatic
Parameters
baseI2S base pointer.
void I2S_EnableSecondaryChannel ( I2S_Type *  base,
uint32_t  channel,
bool  oneChannel,
uint32_t  position 
)
Parameters
baseI2S base pointer.
channelseondary channel channel number, reference _i2s_secondary_channel.
oneChanneltrue is treated as single channel, functionality left channel for this pair.
positiondefine the location within the frame of the data, should not bigger than 0x1FFU.
static void I2S_DisableSecondaryChannel ( I2S_Type *  base,
uint32_t  channel 
)
inlinestatic
Parameters
baseI2S base pointer.
channelseondary channel channel number, reference _i2s_secondary_channel.
static void I2S_Disable ( I2S_Type *  base)
inlinestatic
Parameters
baseI2S base pointer.
static void I2S_EnableInterrupts ( I2S_Type *  base,
uint32_t  interruptMask 
)
inlinestatic
Parameters
baseI2S base pointer.
interruptMaskbit mask of interrupts to enable. See i2s_flags_t for the set of constants that should be OR'd together to form the bit mask.
static void I2S_DisableInterrupts ( I2S_Type *  base,
uint32_t  interruptMask 
)
inlinestatic
Parameters
baseI2S base pointer.
interruptMaskbit mask of interrupts to enable. See i2s_flags_t for the set of constants that should be OR'd together to form the bit mask.
static uint32_t I2S_GetEnabledInterrupts ( I2S_Type *  base)
inlinestatic
Parameters
baseI2S base pointer.
Returns
A bitmask composed of i2s_flags_t enumerators OR'd together to indicate the set of enabled interrupts.
void I2S_TxHandleIRQ ( I2S_Type *  base,
i2s_handle_t *  handle 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.
void I2S_RxHandleIRQ ( I2S_Type *  base,
i2s_handle_t *  handle 
)
Parameters
baseI2S base pointer.
handlepointer to handle structure.