bf0_hal_i2s.h

Header file of I2S HAL module.

Author: Sifli software development team
Attention

Defines

HAL_I2S_ERROR_NONE: No error

HAL_I2S_ERROR_TIMEOUT: Timeout error

HAL_I2S_ERROR_OVR: OVR error

HAL_I2S_ERROR_UDR: UDR error

HAL_I2S_ERROR_DMA: DMA transfer error

HAL_I2S_ERROR_UNKNOW: Unknow Error error

I2S_IT_TXE: Tx empty interrupt

I2S_IT_RXNE: Rx not empty interrupt

I2S_FLAG_TXE: I2S STATUS TX EMPTY

I2S_FLAG_RXNE: I2S STATUS RX NOT EMPTY

I2S_FIFO_TX_FULL: I2S STATUS Tx full

I2S_FIFO_TX_EMPTY: I2S STATUS Tx empty

I2S_FIFO_TX_AMFULL: I2S STATUS Tx almost full

I2S_FIFO_TX_AMEMPTY: I2S STATUS Tx almost empty

I2S_FIFO_RX_FULL: I2S STATUS Rx full

I2S_FIFO_RX_EMPTY: I2S STATUS Rx empty

I2S_FIFO_RX_AMFULL: I2S STATUS Rx almost full

I2S_FIFO_RX_AMEMPTY: I2S STATUS Rx almost empty

I2S_SAMPLERATE_8000: sample rate 8K bps

I2S_SAMPLERATE_16000: sample rate 16K bps

I2S_SAMPLERATE_24000: sample rate 24K bps

I2S_SAMPLERATE_32000: sample rate 32K bps

I2S_SAMPLERATE_48000: sample rate 48K bps

I2S_SAMPLERATE_44100: Isample rate 44.1K bps

I2S_SAMPLERATE_22050: sample rate 22.05K bps

I2S_SAMPLERATE_11025: sample rate 11.025K bps

IS_I2S_SAMPLE_RATE(SR)

CHECK if valid sampel rate number.

参数:

SR – Sample rate.

返回值:

true – if success

__HAL_I2S_RESET_HANDLE_STATE(__HANDLE__)

Reset I2S handle state.

参数:

__HANDLE__ – I2S handle.

返回值:

None –

__HAL_I2S_TX_ENABLE(__HANDLE__)

Enable the specified I2S TX peripheral .

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_TX_DISABLE(__HANDLE__)

Disable the specified I2S TX peripheral .

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_RX_ENABLE(__HANDLE__)

Enable the specified I2S RX peripheral .

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_RX_DISABLE(__HANDLE__)

Disable the specified I2S RX peripheral .

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_TX_INTF_ENABLE(__HANDLE__)

Use the external I2S TX interface.

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_TX_INTF_DISABLE(__HANDLE__)

Use internal APB TX interface.

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_RX_INTF_ENABLE(__HANDLE__)

Use the external I2S RX interface .

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_RX_INTF_DISABLE(__HANDLE__)

Use internal APB RX interface.

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_ENABLE_IT(__HANDLE__, __INTERRUPT__)

Enable the specified I2S interrupts.

参数:

__HANDLE__ – specifies the I2S Handle.
__INTERRUPT__ – specifies the interrupt source to enable or disable. This parameter can be one of the following values:
- I2S_IT_TXE: Tx buffer empty interrupt enable
- I2S_IT_RXNE: RX buffer not empty interrupt enable

返回值:

None –

__HAL_I2S_DISABLE_IT(__HANDLE__, __INTERRUPT__)

Disable the specified I2S interrupts.

参数:

__HANDLE__ – specifies the I2S Handle.
__INTERRUPT__ – specifies the interrupt source to enable or disable. This parameter can be one of the following values:
- I2S_IT_TXE: Tx buffer empty interrupt enable
- I2S_IT_RXNE: RX buffer not empty interrupt enable

返回值:

None –

__HAL_I2S_GET_IT_SOURCE(__HANDLE__, __INTERRUPT__)

Checks if the specified I2S interrupt source is enabled or disabled.

参数:

__HANDLE__ – specifies the I2S Handle. This parameter can be I2S where x: 1, 2, or 3 to select the I2S peripheral.
__INTERRUPT__ – specifies the I2S interrupt source to check. This parameter can be one of the following values:
- I2S_IT_TXE: Tx buffer empty interrupt enable
- I2S_IT_RXNE: RX buffer not empty interrupt enable
- I2S_IT_ERR: Error interrupt enable

返回值:

The – new state of IT (TRUE or FALSE).

__HAL_I2S_GET_FLAG(__HANDLE__, __FLAG__)

Checks whether the specified I2S flag is set or not.

参数:

__HANDLE__ – specifies the I2S Handle.
__FLAG__ – specifies the flag to check. This parameter can be one of the following values:
- I2S_FLAG_RXNE: Receive buffer not empty flag
- I2S_FLAG_TXE: Transmit buffer empty flag
- I2S_FLAG_UDR: Underrun flag
- I2S_FLAG_OVR: Overrun flag
- I2S_FLAG_FRE: Frame error flag
- I2S_FLAG_CHSIDE: Channel Side flag
- I2S_FLAG_BSY: Busy flag

返回值:

The – new state of FLAG (TRUE or FALSE).

__HAL_I2S_CLEAR_OVRFLAG(__HANDLE__)

Clears the I2S OVR pending flag.

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_CLEAR_UDRFLAG(__HANDLE__)

Clears the I2S UDR pending flag.

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_CLK_XTAL(__HANDLE__)

Set the I2S clock from crystal.

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_CLK_PLL(__HANDLE__)

Set the I2S clock from pll.

参数:

__HANDLE__ – specifies the I2S Handle.

返回值:

None –

__HAL_I2S_SET_SPCLK_DIV(__HANDLE__, __DIV__)

Set the I2S SP clock divider.

参数:

__HANDLE__ – specifies the I2S Handle.
__DIV__ – clock divider.

返回值:

None –

Enums

enum HAL_I2S_StateTypeDef

HAL State structures definition.

Values:

enumerator HAL_I2S_STATE_RESET: I2S not yet initialized or disabled

enumerator HAL_I2S_STATE_READY: I2S initialized and ready for use

enumerator HAL_I2S_STATE_BUSY: I2S internal process is ongoing

enumerator HAL_I2S_STATE_BUSY_TX: Data Transmission process is ongoing

enumerator HAL_I2S_STATE_BUSY_RX: Data Reception process is ongoing

enumerator HAL_I2S_STATE_PAUSE: I2S pause state: used in case of DMA

enumerator HAL_I2S_STATE_ERROR: I2S error state

Functions

HAL_StatusTypeDef HAL_I2S_Init(I2S_HandleTypeDef *hi2s)

Initializes the I2S according to the specified parameters in the I2S_InitTypeDef and create the associated handle.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_DeInit(I2S_HandleTypeDef *hi2s)

DeInitializes the I2S peripheral.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

void HAL_I2S_MspInit(I2S_HandleTypeDef *hi2s)

Initializes the I2S pin setting.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

None –

void HAL_I2S_MspDeInit(I2S_HandleTypeDef *hi2s)

deunitializes the I2S pin setting.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

None –

HAL_StatusTypeDef HAL_I2S_Config_Transmit(I2S_HandleTypeDef *hi2s, I2S_CFG_T *cfg)

Set I2S transmit configures.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module
cfg – channel, track, volume and others parameters

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_Config_Receive(I2S_HandleTypeDef *hi2s, I2S_CFG_T *cfg)

Set I2S Receive configures.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module
cfg – channel, track, volume and others parameters

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_Transmit(I2S_HandleTypeDef *hi2s, uint8_t *pData, uint32_t Size, uint32_t Timeout)

Set I2S Transmit data with polling mode.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module
pData – data buffer
Size – data length need to be transmit
Timeout – time out threshold if not finish, in ms

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_Receive(I2S_HandleTypeDef *hi2s, uint8_t *pData, uint32_t Size, uint32_t Timeout)

Set I2S receive data with polling mode.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module
pData – data buffer
Size – data length need to be transmit
Timeout – time out threshold if not finish, in ms

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_Transmit_IT(I2S_HandleTypeDef *hi2s, uint8_t *pData, uint32_t Size)

Transmit an amount of data in non-blocking mode with Interrupt.

备注

When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S configuration phase, the Size parameter means the number of 16-bit data length in the transaction and when a 24-bit data frame or a 32-bit data frame is selected the Size parameter means the number of 16-bit data length.

备注

The I2S is kept enabled at the end of transaction to avoid the clock de-synchronization between Master and Slave(example: audio streaming).

备注

This function can use an Audio Frequency up to 48KHz when I2S Clock Source is 32MHz

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module
pData – a 16-bit pointer to data buffer.
Size – number of data sample to be sent:

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_Receive_IT(I2S_HandleTypeDef *hi2s, uint8_t *pData, uint32_t Size)

Receive an amount of data in non-blocking mode with Interrupt.

备注

The I2S is kept enabled at the end of transaction to avoid the clock de-synchronization between Master and Slave(example: audio streaming).

备注

It is recommended to use DMA for the I2S receiver to avoid de-synchronisation between Master and Slave otherwise the I2S interrupt should be optimized.

备注

This function can use an Audio Frequency up to 48KHz when I2S Clock Source is 32MHz

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module
pData – a 16-bit pointer to the Receive data buffer.
Size – number of data sample to be sent:

返回值:

HAL – status

void HAL_I2S_IRQHandler(I2S_HandleTypeDef *hi2s)

This function handles I2S interrupt request.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

None –

HAL_StatusTypeDef HAL_I2S_Transmit_DMA(I2S_HandleTypeDef *hi2s, uint8_t *pData, uint32_t Size)

Set I2S Transmit data with DMA mode.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module
pData – data buffer
Size – data length need to be transmit

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_Receive_DMA(I2S_HandleTypeDef *hi2s, uint8_t *pData, uint32_t Size)

Set I2S Transmit data with DMA mode.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module
pData – data buffer
Size – data length need to be transmit

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_DMAPause(I2S_HandleTypeDef *hi2s)

Pauses the audio stream playing from the Media.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_DMAResume(I2S_HandleTypeDef *hi2s)

Resumes the audio stream playing from the Media.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_DMAStop(I2S_HandleTypeDef *hi2s)

Stops the audio stream playing from the Media.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_TX_DMAPause(I2S_HandleTypeDef *hi2s)

Pauses the audio stream playing from the Media.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_TX_DMAResume(I2S_HandleTypeDef *hi2s)

Resumes the audio stream playing from the Media.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_TX_DMAStop(I2S_HandleTypeDef *hi2s)

Stops the audio stream playing from the Media.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_RX_DMAPause(I2S_HandleTypeDef *hi2s)

Pauses the audio stream recording.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_RX_DMAResume(I2S_HandleTypeDef *hi2s)

Resumes the audio stream recording.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

HAL_StatusTypeDef HAL_I2S_RX_DMAStop(I2S_HandleTypeDef *hi2s)

Stops the audio stream recording.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – status

void HAL_I2S_TxHalfCpltCallback(I2S_HandleTypeDef *hi2s)

Tx Transfer Half completed callbacks.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

None –

void HAL_I2S_TxCpltCallback(I2S_HandleTypeDef *hi2s)

Tx Transfer completed callbacks.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

None –

void HAL_I2S_RxHalfCpltCallback(I2S_HandleTypeDef *hi2s)

Rx Transfer half completed callbacks.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

None –

void HAL_I2S_RxCpltCallback(I2S_HandleTypeDef *hi2s)

Rx Transfer completed callbacks.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

None –

void HAL_I2S_ErrorCallback(I2S_HandleTypeDef *hi2s)

I2S error callbacks.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

None –

HAL_I2S_StateTypeDef HAL_I2S_GetState(I2S_HandleTypeDef *hi2s)

Return the I2S state.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

HAL – state

uint32_t HAL_I2S_GetError(I2S_HandleTypeDef *hi2s)

Return the I2S error code.

参数:

hi2s – pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

返回值:

I2S – Error Code

struct CLK_DIV_T

#include <bf0_hal_i2s.h>

I2S bclk lrck divder table structure definition.

Public Members

uint32_t samplerate: Sample rate

uint16_t lr_clk_duty_high: LRCK duty cycle high

uint16_t lr_clk_duty_low: RX LRCK duty cycle low

uint16_t blck_duty: bit clock duty cycle

struct I2S_CFG_T

#include <bf0_hal_i2s.h>

I2S bus configure structure definition.

Public Members

uint8_t bus_dw: I2S bus data width 8, 16, 24 32 …

uint8_t data_dw: output data width, only support 8 or 16

uint8_t slave_mode: 0 master mode, 1 slave mode.

uint8_t track: 1 mono, 0s stereo

uint8_t chnl_sel: 0 noral, 5 left/write switch , 0xa left right average

uint8_t lrck_invert: for standard I2S, set lrck_pol to 0,for Left/Right Justified, set lrck_pol to 1

uint32_t sample_rate: Sample rate

uint32_t bclk: I2S BCLK

uint8_t vol: 0 ~ 15, 0=+6db, 4=0db, 14=-15db, 15=mute

uint8_t balance_en: 0 balance disable, 1 right channel adjust, 2 left channel adjust

uint8_t balance_vol: when balance_en=1, 1 ~ 15, 1=-1.5db, 2=-3db … 14=-21db, 15=mute

uint8_t extern_intf: 0 use internal apb memory, 1 use external interface

uint8_t pcm_dw: For I2S rx/tx data width , related with peripheral

uint8_t clk_div_index: clock divder index(for txrx_clk_div), base on sample rate

CLK_DIV_T *clk_div

struct I2S_InitTypeDef

#include <bf0_hal_i2s.h>

I2S Init structure definition.

Public Members

uint32_t src_clk_freq: Source clk for I2S module

uint32_t mclk_div: I2S mclock for I2S module

I2S_CFG_T tx_cfg: Transmit i2s configure

I2S_CFG_T rx_cfg: Receive i2s configure

struct I2S_HandleTypeDef

#include <bf0_hal_i2s.h>

I2S handle Structure definition.

Public Members

I2S_TypeDef *Instance: I2S registers base address

I2S_InitTypeDef Init: I2S communication parameters

uint32_t *pTxBuffPtr: Pointer to I2S Tx transfer buffer

uint32_t TxXferSize: I2S Tx transfer size

uint32_t TxXferCount: I2S Tx transfer Counter

uint32_t *pRxBuffPtr: Pointer to I2S Rx transfer buffer

uint32_t RxXferSize: I2S Rx transfer size

uint32_t RxXferCount: I2S Rx transfer counter (This field is initialized at the same value as transfer size at the beginning of the transfer and decremented when a sample is received. NbSamplesReceived = RxBufferSize-RxBufferCount)

DMA_HandleTypeDef *hdmatx: I2S Tx DMA handle parameters

DMA_HandleTypeDef *hdmarx: I2S Rx DMA handle parameters

HAL_LockTypeDef Lock: I2S locking object

HAL_I2S_StateTypeDef State: I2S communication state

uint32_t ErrorCode: I2S Error code This parameter can be a value of I2S Error