MT2523 API Reference  LinkIt SDK v4
I2C_MASTER

Overview

Terms and acronyms

Terms Details
DMA Direct Memory Access. For an introduction to DMA, please refer to DMA in Wikipedia.
GPIO General Purpose Inputs-Outputs. For more details, please refer to the GPIO module in HAL.
I2C Inter-Integrated Circuit. I2C is typically used to attach low-speed peripheral ICs to processors and microcontrollers. For an introduction to I2C, please refer to I2C in Wikipedia.
NVIC Nested Vectored Interrupt Controller. NVIC is the interrupt controller of ARM Cortex-M4. For more details, please refer to NVIC introduction in ARM Cortex-M4 Processor Technical Reference Manual.

Supported features

Software architecture of the I2C

How to use this driver

Transaction Length And transaction packet of APIs

The Transaction packet is the transaction packet sent by the I2C master using SCL and SDA. Different APIs have different transaction packets, as shown below.

Functions

hal_i2c_status_t hal_i2c_master_init (hal_i2c_port_t i2c_port, hal_i2c_config_t *i2c_config)
 This function initializes the I2C master before starting a transaction. More...
 
hal_i2c_status_t hal_i2c_master_deinit (hal_i2c_port_t i2c_port)
 This function releases the I2C master after the transaction is over. More...
 
hal_i2c_status_t hal_i2c_master_set_frequency (hal_i2c_port_t i2c_port, hal_i2c_frequency_t frequency)
 This function sets the transaction speed. More...
 
hal_i2c_status_t hal_i2c_master_register_callback (hal_i2c_port_t i2c_port, hal_i2c_callback_t i2c_callback, void *user_data)
 This function registers a callback function while using DMA mode. More...
 
hal_i2c_status_t hal_i2c_master_send_polling (hal_i2c_port_t i2c_port, uint8_t slave_address, const uint8_t *data, uint32_t size)
 This function sends data to I2C slave in polling mode. More...
 
hal_i2c_status_t hal_i2c_master_send_dma (hal_i2c_port_t i2c_port, uint8_t slave_address, const uint8_t *data, uint32_t size)
 This function sends data to I2C slave in DMA mode. More...
 
hal_i2c_status_t hal_i2c_master_receive_polling (hal_i2c_port_t i2c_port, uint8_t slave_address, uint8_t *buffer, uint32_t size)
 This function receives data from I2C slave in a polling mode. More...
 
hal_i2c_status_t hal_i2c_master_receive_dma (hal_i2c_port_t i2c_port, uint8_t slave_address, uint8_t *buffer, uint32_t size)
 This function receives data from I2C slave in a DMA mode. More...
 
hal_i2c_status_t hal_i2c_master_send_to_receive_polling (hal_i2c_port_t i2c_port, hal_i2c_send_to_receive_config_t *i2c_send_to_receive_config)
 This function sends data to and then receives data from I2C slave in a polling mode. More...
 
hal_i2c_status_t hal_i2c_master_send_to_receive_dma (hal_i2c_port_t i2c_port, hal_i2c_send_to_receive_config_t *i2c_send_to_receive_config)
 This function sends data to and then receives data from I2C slave in a DMA mode. More...
 
hal_i2c_status_t hal_i2c_master_send_dma_ex (hal_i2c_port_t i2c_port, hal_i2c_send_config_t *i2c_send_config)
 This function sends data to I2C slave in DMA mode. More...
 
hal_i2c_status_t hal_i2c_master_receive_dma_ex (hal_i2c_port_t i2c_port, hal_i2c_receive_config_t *i2c_receive_config)
 This function receives data from I2C slave in a extended DMA mode. More...
 
hal_i2c_status_t hal_i2c_master_send_to_receive_dma_ex (hal_i2c_port_t i2c_port, hal_i2c_send_to_receive_config_ex_t *i2c_send_to_receive_config_ex)
 This function sends data to and then receives data from I2C slave in a extended DMA mode. More...
 
hal_i2c_status_t hal_i2c_master_get_running_status (hal_i2c_port_t i2c_port, hal_i2c_running_status_t *running_status)
 This function gets running status of the I2C master. More...
 

Modules

 Define
 
 Enum
 
 Struct
 
 Typedef
 

Function Documentation

hal_i2c_status_t hal_i2c_master_deinit ( hal_i2c_port_t  i2c_port)

This function releases the I2C master after the transaction is over.

Call this function, if the I2C is no longer in use.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_OK, the operation completed successfully.
Note
This function must be called when the I2C is no longer in use, release the I2C resource for the other users to use this I2C master.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_init()
hal_i2c_status_t hal_i2c_master_get_running_status ( hal_i2c_port_t  i2c_port,
hal_i2c_running_status_t running_status 
)

This function gets running status of the I2C master.

Call this function to check if the I2C is idle or not before transferring data. If it's not idle, then the resource is currently in use, delay the operation until the I2C is idle.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[out]running_statusHAL_I2C_STATUS_BUS_BUSY, the I2C master is in busy status;
HAL_I2C_STATUS_IDLE, the I2C master is in idle status; User can use it to transmit data immediately.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_OK, the operation completed successfully.
Example
Sample code, please refer to How to use this driver
hal_i2c_status_t hal_i2c_master_init ( hal_i2c_port_t  i2c_port,
hal_i2c_config_t i2c_config 
)

This function initializes the I2C master before starting a transaction.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in]i2c_configIs the configuration parameter to initialize the I2C. Details are described at hal_i2c_config_t.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, an invalid transfer_frequency is given;
HAL_I2C_STATUS_OK, the operation completed successfully. HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Note
hal_i2c_master_deinit() must be called when the I2C is no longer in use, release the I2C resource for the other users to use this I2C master.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_deinit()
hal_i2c_status_t hal_i2c_master_receive_dma ( hal_i2c_port_t  i2c_port,
uint8_t  slave_address,
uint8_t *  buffer,
uint32_t  size 
)

This function receives data from I2C slave in a DMA mode.

This function will return a value immediately after configuring the hardware registers. For more details of DMA mode, see DMA mode in Supported features chapter. For details about transaction length and transaction waveform pattern, see Transaction Length And transaction packet of APIs chapter. Note, not all masters support DMA mode. For more details about DMA mode, see hal_i2c_port_t.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in]slave_addressis the I2C slave address.
[out]bufferis the data buffer to receive.
[in]sizeis the data size to receive. The maximum value is HAL_I2C_MAXIMUM_DMA_TRANSACTION_SIZE.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, a NULL buffer pointer is given by user;
HAL_I2C_STATUS_OK, the operation completed successfully;
HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_receive_polling()
hal_i2c_status_t hal_i2c_master_receive_dma_ex ( hal_i2c_port_t  i2c_port,
hal_i2c_receive_config_t i2c_receive_config 
)

This function receives data from I2C slave in a extended DMA mode.

This function returns immediately after configuring the hardware registers. For more details of extended DMA mode, see extended DMA mode in Supported features chapter. For details about transaction length and transaction waveform pattern, see Transaction Length And transaction packet of APIs chapter. Note, not all I2C masters support DMA mode. For more details about DMA mode, see hal_i2c_port_t.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in,out]i2c_receive_configis the configuration parameter of this API for receive.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, an NULL buffer pointer is given by user or either the send_packet_length or send_bytes_in_one_packet is invalid;
HAL_I2C_STATUS_OK, the operation completed successfully;
HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_receive_dma(),hal_i2c_master_receive_polling().
hal_i2c_status_t hal_i2c_master_receive_polling ( hal_i2c_port_t  i2c_port,
uint8_t  slave_address,
uint8_t *  buffer,
uint32_t  size 
)

This function receives data from I2C slave in a polling mode.

This function will not return a value until the transaction is finished. For more details about polling mode, see polling mode in Supported features chapter. For details about transaction length and transaction waveform pattern, see Transaction Length And transaction packet of APIs chapter.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in]slave_addressis the I2C slave address.
[out]bufferis the data buffer to receive.
[in]sizeis the data size to receive. The maximum value is HAL_I2C_MAXIMUM_POLLING_TRANSACTION_SIZE.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, a NULL buffer pointer is given by user;
HAL_I2C_STATUS_OK, the operation completed successfully;
HAL_I2C_STATUS_ERROR, a hardware error occurred during the transaction.
HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_receive_dma()
hal_i2c_status_t hal_i2c_master_register_callback ( hal_i2c_port_t  i2c_port,
hal_i2c_callback_t  i2c_callback,
void *  user_data 
)

This function registers a callback function while using DMA mode.

The callback function will be called at I2C ISR routine after the I2C triggers an interrupt. Always call this function to register a callback function while using DMA mode. Refer to Software architecture of the I2C for DMA architecture.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in]i2c_callbackis the user-defined callback function called at I2C ISR routine.
[in]user_datais a user-defined input data returned during the callback function's call. See the last parameter of hal_i2c_callback_t.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, a NULL function pointer is given by user;
HAL_I2C_STATUS_OK,the operation completed successfully.
Example
Sample code, please refer to How to use this driver
hal_i2c_status_t hal_i2c_master_send_dma ( hal_i2c_port_t  i2c_port,
uint8_t  slave_address,
const uint8_t *  data,
uint32_t  size 
)

This function sends data to I2C slave in DMA mode.

This function returns a value immediately after configuring the hardware registers. For more details about DMA mode, see DMA mode in Supported features chapter. For details about transaction length and transaction waveform pattern, see Transaction Length And transaction packet of APIs chapter. Note, not all I2C masters support DMA mode. For more details about DMA mode,see hal_i2c_port_t.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in]slave_addressis the I2C slave address.
[in]datais the data buffer to send.
[in]sizeis the data size to send. The maximum value is HAL_I2C_MAXIMUM_DMA_TRANSACTION_SIZE.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, an NULL buffer pointer is given by user;
HAL_I2C_STATUS_OK, the operation completed successfully;
HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_send_polling()
hal_i2c_status_t hal_i2c_master_send_dma_ex ( hal_i2c_port_t  i2c_port,
hal_i2c_send_config_t i2c_send_config 
)

This function sends data to I2C slave in DMA mode.

This function returns immediately after configuring the hardware registers. For more details about extended DMA mode, see extended DMA mode in Supported features chapter. For details about transaction length and transaction waveform pattern, see Transaction Length And transaction packet of APIs chapter. Note, not all I2C masters support DMA mode. For more details about DMA mode, see hal_i2c_port_t.

Parameters
[in]i2c_portis the I2C master port number.
[in]i2c_send_configis the configuration parameter of this API for send.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, an NULL buffer pointer is given by user or either the send_packet_length or send_bytes_in_one_packet is invalid;
HAL_I2C_STATUS_OK, the operation completed successfully;
HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_send_dma(), hal_i2c_master_send_polling().
hal_i2c_status_t hal_i2c_master_send_polling ( hal_i2c_port_t  i2c_port,
uint8_t  slave_address,
const uint8_t *  data,
uint32_t  size 
)

This function sends data to I2C slave in polling mode.

This function will not return until the transaction is complete. For more details about polling mode, see polling mode in Supported features chapter. For details about transaction length and transaction waveform pattern, see Transaction Length And transaction packet of APIs chapter.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in]slave_addressis the I2C slave address.
[in]datais the data buffer to send.
[in]sizeis the data size to send. The maximum value is HAL_I2C_MAXIMUM_POLLING_TRANSACTION_SIZE.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, a NULL buffer pointer is given by user;
HAL_I2C_STATUS_OK, the operation completed successfully;
HAL_I2C_STATUS_ERROR, a hardware error occurred during the transaction.
HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_send_dma()
hal_i2c_status_t hal_i2c_master_send_to_receive_dma ( hal_i2c_port_t  i2c_port,
hal_i2c_send_to_receive_config_t i2c_send_to_receive_config 
)

This function sends data to and then receives data from I2C slave in a DMA mode.

This function returns immediately after configuring the hardware registers. For more details of DMA mode, see DMA mode in Supported features chapter. For details about transaction length and transaction waveform pattern, see Transaction Length And transaction packet of APIs chapter. Note, not all masters support DMA mode. For more details about DMA mode, see DMA mode of hal_i2c_port_t.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in,out]i2c_send_to_receive_configis the configuration parameter for this API for both send and receive.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, a NULL buffer pointer is given by user;
HAL_I2C_STATUS_OK, the operation completed successfully;
HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_send_to_receive_polling()
hal_i2c_status_t hal_i2c_master_send_to_receive_dma_ex ( hal_i2c_port_t  i2c_port,
hal_i2c_send_to_receive_config_ex_t i2c_send_to_receive_config_ex 
)

This function sends data to and then receives data from I2C slave in a extended DMA mode.

This function returns immediately after configuring the hardware registers. For more details of extended DMA mode, see extended DMA mode in Supported features chapter. For details about transaction length and transaction waveform pattern, see Transaction Length And transaction packet of APIs chapter. Note, not all I2C masters support DMA mode. For more details about DMA mode, see hal_i2c_port_t.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in,out]i2c_send_to_receive_config_exis the configuration parameter of this API for both send and receive.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, an NULL buffer pointer is given by user or either the send_packet_length or send_bytes_in_one_packet is invalid;
HAL_I2C_STATUS_OK, the operation completed successfully;
HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_send_to_receive_dma(), hal_i2c_master_send_to_receive_polling().
hal_i2c_status_t hal_i2c_master_send_to_receive_polling ( hal_i2c_port_t  i2c_port,
hal_i2c_send_to_receive_config_t i2c_send_to_receive_config 
)

This function sends data to and then receives data from I2C slave in a polling mode.

This function does not return until the transaction is finished. For more details about polling mode, see polling mode in Supported features chapter. For details about transaction length and transaction waveform pattern, see Transaction Length And transaction packet of APIs chapter.

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in,out]i2c_send_to_receive_configis the configuration parameter for this API for both send and receive.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, a NULL buffer pointer is given by user;
HAL_I2C_STATUS_OK, the operation completed successfully;
HAL_I2C_STATUS_ERROR, a hardware error occurred during the transaction.
HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
Sample code, please refer to How to use this driver
See also
hal_i2c_master_send_to_receive_dma()
hal_i2c_status_t hal_i2c_master_set_frequency ( hal_i2c_port_t  i2c_port,
hal_i2c_frequency_t  frequency 
)

This function sets the transaction speed.

Apply this function to change the transaction speed without using hal_i2c_master_init().

Parameters
[in]i2c_portis the I2C master port number. The value is defined in hal_i2c_port_t.
[in]frequencyis an enum value defined in hal_i2c_frequency_t. Only value of type hal_i2c_frequency_t is accepted.
Returns
HAL_I2C_STATUS_INVALID_PORT_NUMBER, an invalid port number is given;
HAL_I2C_STATUS_INVALID_PARAMETER, an invalid speed is given;
HAL_I2C_STATUS_OK, the operation completed successfully. HAL_I2C_STATUS_ERROR_BUSY, the I2C bus is in use.
Example
1 ret = hal_i2c_master_config_speed(HAL_I2C_MASTER_1,HAL_I2C_SPEED_400K);
See also
hal_i2c_master_init()