I2S

This section introduces the Integrated Interchip Sound (I2S) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions. More...

Overview

This section introduces the Integrated Interchip Sound (I2S) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.

Terms and Acronyms

Terms	Details
DMA	Direct Memory Access.
FIFO	First In, First Out.
ISR	Interrupt Service Routine.
I2S	Integrated Interchip Sound.

Supported Features

• Two I2S interfaces share the same XPLL clock source.
  
• Slave mode, only used to communicate with the external codec.
  
• 16MHz master clock provided.
  
• Two modes supported.
  
  • I2S slave mode: Standard I2S protocol.
    
    • Stereo (2-ch)/Mono (1-ch) supported.
      
    • 16-bit word length supported.
      
    • 8/12/16/24/32/48 kHz sample rate supported.
      
  • TDM slave mode: TDM protocol.
    
    • 32/64/128 bit clocks in each FS cycle supported.
      
    • 4/2 channels supported.
      
    • 16-bit word length supported.
      
    • 8/12/16/24/32/48 kHz sample rate supported.
      
    • MSB offset: 0 ~ 127.
      
• For more detail, please refer to the I2S datasheet.
  

How to Use This Driver

• Use I2S transmit/receive (Tx/Rx) data for external codec functionality.
  The users can set the initial type to "MHAL_I2S_TYPE_EXTERNAL_MODE" in mtk_mhal_i2s_cfg_type() function when connecting an external codec component.
  An interrupt will be triggered after the data transfer, using the I2S interface, is completed. A user-defined callback function is called to handle data transfer in the I2S interrupt service routine.
  
  • Step1: Call mtk_mhal_i2s_alloc_vfifo_ch to allocate DMA channel.
    
  • Step2: Call mtk_mhal_i2s_cfg_type() to configure the I2S type.
    
  • Step3: Call mtk_mhal_i2s_set_config() to configure the I2S settings.
    
  • Step4: Call mtk_mhal_i2s_cfg_tx_dma_irq_enable() and mtk_mhal_i2s_cfg_rx_dma_irq_enable() to configure DMA interrupt and register the callback functions.
    
  • Step5: Call mtk_mhal_i2s_start_tx_vfifo() and mtk_mhal_i2s_start_rx_vfifo() to configure and start Tx and Rx Virtual FIFO.
    
  • Step6: Call mtk_mhal_i2s_enable_audio_top(), mtk_mhal_i2s_enable_tx() and mtk_mhal_i2s_enable_rx() functions to start Tx and Rx link data flows.
    
• Event handling for Tx and Rx links data transfer operations.
  
  • The callback functions of Tx and Rx links are always invoked in the DMA Interrupt Service Routine (ISR). It is recommended to send the events of Tx and Rx links to user-defined media task in callback functions and handle the corresponding data operations in the media task to avoid long operations in the ISR.
    
  • Sample code below is shown to explain how to handle events in the user-defined media task.
    

    void _mtk_os_hal_i2s0_tx_callback(void *data)
    {
       mtk_mhal_i2s_move_tx_point(&i2s0_ctlr_cfg.i2s_ctrl,
                      i2s0_ctlr_cfg.tx_period_len);
       if (i2s0_ctlr_cfg.tx_callback_func != NULL)
           i2s0_ctlr_cfg.tx_callback_func(
               i2s0_ctlr_cfg.tx_callback_data);
       // i2s0_ctlr_cfg.tx_callback_func(NULL) is user application.
       // This function triger a event to resume a handle task.
       // The handle task will fill data to next period size buffer.
    }
    void _mtk_os_hal_i2s0_rx_callback(void *data)
    {
       mtk_mhal_i2s_move_rx_point(&i2s0_ctlr_cfg.i2s_ctrl,
                      i2s0_ctlr_cfg.rx_period_len);
       if (i2s0_ctlr_cfg.rx_callback_func != NULL)
           i2s0_ctlr_cfg.rx_callback_func(
               i2s0_ctlr_cfg.rx_callback_data);
       // i2s0_ctlr_cfg.rx_callback_func(NULL) is user application.
       // This function triger a event to resume a handle task.
       // The handle task will get data on this period size buffer.
    }

• The OS-HAL freeRTos driver sample code is as follows:
  freeRTos I2S sample code on github

I2S Function Groups Description

The APIs are grouped by their functionality for easier use. Users can refer to the details of each function by clicking the function name.

• Initialization and configuration
  The mtk_mhal_i2s_cfg_type() function configures the I2S type, which should be set at the beginning of an I2S operation.
  The mtk_mhal_i2s_reset() function, conversely, resets the I2S HW configuration.
  The mtk_mhal_i2s_set_config() function configures the I2S settings providing the respective sample rate and channel number for Tx and Rx links as well as the clock mode for the whole I2S. The users should configure settings before enabling the I2S functions.
  The mtk_mhal_i2s_start_tx_vfifo() function configures DMA Tx VFIFO
  The mtk_mhal_i2s_start_rx_vfifo() function configures DMA Rx VFIFO
  The functions are as follows:
  
  • mtk_mhal_i2s_cfg_type()
  • mtk_mhal_i2s_reset()
  • mtk_mhal_i2s_set_config()
  • mtk_mhal_i2s_start_tx_vfifo()
  • mtk_mhal_i2s_start_rx_vfifo()
• Callback register functions
  Use the following functions to configure interrupt enable and register callback functions for Tx and Rx link data operation.
  These functions include:
  
  • mtk_mhal_i2s_cfg_tx_dma_irq_enable()
  • mtk_mhal_i2s_cfg_tx_dma_irq_enable()
• Enable and disable functions
  Call mtk_mhal_i2s_enable_tx() function to enable the I2S Tx link to transmit the data.
  Call mtk_mhal_i2s_disable_tx() function to disable the I2S Tx data transmission immediately.
  Call mtk_mhal_i2s_enable_rx() function to enable the I2S Rx link to receive data.
  Call mtk_mhal_i2s_disable_rx() function to disable the I2S Rx link immediately.
  Call mtk_mhal_i2s_enable_audio_top() function to enable the I2S audio top immediately.
  Call mtk_mhal_i2s_disable_audio_top() function to disable the I2S audio top immediately.
  Call mtk_mhal_i2s_stop_rx_vfifo() function to disable DMA Rx VFIFO.
  Call mtk_mhal_i2s_stop_tx_vfifo() function to disable DMA Tx VFIFO.
  The functions are as follows:
  
  • mtk_mhal_i2s_enable_tx()
  • mtk_mhal_i2s_disable_tx()
  • mtk_mhal_i2s_enable_rx()
  • mtk_mhal_i2s_disable_rx()
  • mtk_mhal_i2s_enable_audio_top()
  • mtk_mhal_i2s_disable_audio_top()
  • mtk_mhal_i2s_stop_rx_vfifo()
  • mtk_mhal_i2s_stop_tx_vfifo()

Modules
	Define
	This section introduces the Macro definition which is used as I2S M-HAL's API error return type.
	Enum
	This section introduces the enumerations that I2S should configure before performing transfer.
	Function
	This section provides fixed APIs (defined as Common Interface) to fully control the MediaTek I2S HW.
	Struct
	This section introduces the structure used by I2S OS-HAL/M-HAL/HDL.
	Typedef
	This section introduces the typedef that I2S M-HAL used.