Azure Sphere MT3620 M4 API Reference Manual
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Function
I2C

This section provides Fixed APIs(defined as Common Interface) to fully control the MediaTek I2C HW. More...

Overview

This section provides Fixed APIs(defined as Common Interface) to fully control the MediaTek I2C HW.

Functions

int mtk_mhal_i2c_init_hw (struct mtk_i2c_controller *i2c)
 This function is used to initialize I2C and DMA hardware. More...
 
int mtk_mhal_i2c_trigger_transfer (struct mtk_i2c_controller *i2c)
 This function is used to trigger I2C controller transfer. More...
 
int mtk_mhal_i2c_irq_handle (struct mtk_i2c_controller *i2c)
 Get I2C irq status and clear irq status reg. More...
 
int mtk_mhal_i2c_result_handle (struct mtk_i2c_controller *i2c)
 This fuction is used to analyze the type of i2c interrupt. More...
 
int mtk_mhal_i2c_enable_clk (struct mtk_i2c_controller *i2c)
 Enable I2C clock before transfer. More...
 
int mtk_mhal_i2c_disable_clk (struct mtk_i2c_controller *i2c)
 This function is used to disable I2C clock after transfer. More...
 
int mtk_mhal_i2c_dump_register (struct mtk_i2c_controller *i2c)
 This function is used to dump I2C register value for debugging. More...
 
int mtk_mhal_i2c_init_speed (struct mtk_i2c_controller *i2c, enum i2c_speed_kHz)
 This function is used to initialize transfer speed. More...
 
int mtk_mhal_i2c_init_slv_addr (struct mtk_i2c_controller *i2c, u8 slv_addr)
 This function is used to set I2C salve address. More...
 
int mtk_mhal_i2c_dma_done_callback_register (struct mtk_i2c_controller *i2c, i2c_dma_done_callback callback, void *user_data)
 This defines the callback function prototype. More...
 
int mtk_mhal_i2c_request_dma (struct mtk_i2c_controller *i2c)
 This function is used to allocate I2C DMA channel. More...
 
int mtk_mhal_i2c_release_dma (struct mtk_i2c_controller *i2c)
 This function is used to release I2C DMA channel. More...
 

Function Documentation

int mtk_mhal_i2c_init_hw ( struct mtk_i2c_controller *  i2c)

This function is used to initialize I2C and DMA hardware.

Usage : Initialize hardware according to i2c arg. It must be called if i2c transfer fail.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
Returns
Return "0" if configure I2C hardware successfully.
Return -I2C_EPTR if *i2c is NULL.
Return -I2C_EINVAL if *i2c contains illegal parameter.
int mtk_mhal_i2c_trigger_transfer ( struct mtk_i2c_controller *  i2c)

This function is used to trigger I2C controller transfer.

Usage : While the function returns, the transfer may not be completed. So OS-HAL should wait for I2C hardware irq to be finished (maybe use semaphore). If I2C controller is set as master role, It will start transfer when the function returns. If I2C controller is set as slave role, It will wait I2C master to generate start signal.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
Returns
Return "0" if the transfer is in progress.
Return -I2C_EPTR if *i2c is NULL. Return -I2C_EINVAL if *i2c contains illegal parameter. Return -I2C_EBUSY if I2C hardware busy.
int mtk_mhal_i2c_irq_handle ( struct mtk_i2c_controller *  i2c)

Get I2C irq status and clear irq status reg.

Usage : This function will get interrupt status, assign to i2c->irq_stat and clear irq status. It's called by I2C irq function.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
Returns
Return "0" if I2C get and clear interrupt status successfully.
Return "-1" if I2C interrupt abnormal.
Return -I2C_EPTR if *i2c is NULL. Return -I2C_EINVAL if *i2c contains illegal parameter.
int mtk_mhal_i2c_result_handle ( struct mtk_i2c_controller *  i2c)

This fuction is used to analyze the type of i2c interrupt.

And read Rx FIFO register then copy data to i2c->msg->buf if I2C transfers data successfully when using FIFO mode. Usage : OS-HAL driver must call this function after I2C hardware completes data transfer.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
Returns
Return "0" if the transfer is in progress.
Return -I2C_EPTR if *i2c is NULL. Return -I2C_EINVAL if *i2c contains illegal parameter.
int mtk_mhal_i2c_enable_clk ( struct mtk_i2c_controller *  i2c)

Enable I2C clock before transfer.

Usage : This function is used to enable I2C clock before OS-HAL calls any function that sets the I2C module register operation, otherwise the access to I2C register will fail.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
Returns
Return "0" if enable I2C clock successfully.
Return -I2C_EPTR if *i2c is NULL. Return -I2C_EINVAL if *i2c contains illegal parameter.
int mtk_mhal_i2c_disable_clk ( struct mtk_i2c_controller *  i2c)

This function is used to disable I2C clock after transfer.

Usage : It needs to be called after data transfer to disable clock.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
Returns
Return "0" if disable I2C clock successfully.
Return -I2C_EPTR if *i2c is NULL. Return -I2C_EINVAL if *i2c contains illegal parameter.
int mtk_mhal_i2c_dump_register ( struct mtk_i2c_controller *  i2c)

This function is used to dump I2C register value for debugging.

Usage : Used for dump I2C register.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
Returns
Return "0" if dump register value successfully.
Return -I2C_EPTR if *i2c is NULL. Return -I2C_EINVAL if *i2c contains illegal parameter.
int mtk_mhal_i2c_init_speed ( struct mtk_i2c_controller *  i2c,
enum  i2c_speed_kHz 
)

This function is used to initialize transfer speed.

Usage : OS-HAL driver calls this function to set I2C transfer speed and it uses default transfer speed 100 khz by default when I2C controller is set as master role. OS-HAL driver does not call this function if I2C controller is set as slave role.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
[in]i2c_speed_kHz: It can be set to one of the enum i2c_speed_kHz.
Returns
Return "0" if I2C sets speed successfully.
Return -I2C_EPTR if i2c is NULL.
Return -I2C_EINVAL if a parameter is invalid.
int mtk_mhal_i2c_init_slv_addr ( struct mtk_i2c_controller *  i2c,
u8  slv_addr 
)

This function is used to set I2C salve address.

Usage : OS-HAL driver calls this function to set I2C slave address before transfer when I2C hardware controller is set as a slave role, it which means OS-HAL driver does not call this function when hardware is set as an I2C master role.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
[in]slv_addr: Set controller slave address.
Returns
Return "0" if I2C sets slave address successfully.
Return -I2C_EPTR if i2c is NULL.
Rerurn -I2C_EINVAL If a parameter is invalid then I2C slave address uses 0x20 by default.
int mtk_mhal_i2c_dma_done_callback_register ( struct mtk_i2c_controller *  i2c,
i2c_dma_done_callback  callback,
void *  user_data 
)

This defines the callback function prototype.

It's used for DMA mode transaction.
Users should register a callback function when using I2C DMA mode.
In DMA mode, once I2C and DMA hardware completes transsaction, a DMA interrupt is triggered and a related user callback is called in the DMA interrupt service routine.
This typedef is used to describe the callback function that the user wants to call.

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
[in]callback: The callback function given by OS-HAL which will be called in I2C module DMA interrupt service routine.
[in]user_data: A parameter given by OS-HAL and will be passed to users when the callback function is called.
Returns
Return "0" if callback registers successfully.
Return -I2C_EPTR if i2c or user_data is NULL.
int mtk_mhal_i2c_request_dma ( struct mtk_i2c_controller *  i2c)

This function is used to allocate I2C DMA channel.

Usage: User should call it to allocate DMA channel

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
Returns
Return 0 if users allocate DMA channel successfully.
Return -I2C_EPTR if i2c is NULL.
Return -I2C_EBUSY if dma chan is busy.
int mtk_mhal_i2c_release_dma ( struct mtk_i2c_controller *  i2c)

This function is used to release I2C DMA channel.

Usage: user should call it to release DMA channel

Parameters
[in]i2c: mtk_i2c_controller pointer, it contains register base address, data transmission information and i2c hardware information.
Returns
Return 0 if users release DMA channel successfully.
Return -I2C_EPTR if i2c is NULL.