# I2C HAL interface documentation

## Hardware introduction

K230 has a total of 5 i2c channels. The i2c module supports master-slave mode, 7/10-bit addressing, and interrupts. The i2c module transmission rate supports 100k/400k/1M/3.4M.

---

## Data structure description

### `drv_i2c_inst_t`

**Description**: I2C host instance structure, containing I2C configuration and status information.

### `i2c_msg_t`

**Description**: I2C message structure.

- `addr`: device address
- `flags`: Transmission flags (read/write, 10-bit address, etc.)
- `len`: data length
- `buf`: Data buffer pointer

### `drv_i2c_slave_inst_t`

**Description**: I2C slave instance structure.

### I2C transfer flags

- `DRV_I2C_WR`: write operation
- `DRV_I2C_RD`: read operation
- `DRV_I2C_ADDR_10BIT`: 10-bit address mode
- `DRV_I2C_NO_START`: Do not send start signal
- `DRV_I2C_IGNORE_NACK`: Ignore NACK
- `DRV_I2C_NO_READ_ACK`: No ACK is sent when reading
- `DRV_I2C_NO_STOP`: Do not send stop signal

---

## I2C master mode interface

### `int drv_i2c_inst_create(int id, uint32_t freq, uint32_t timeout_ms, uint8_t scl, uint8_t sda, drv_i2c_inst_t** inst);`

**Function**: Create an I2C master instance.

**parameter**:

- `id`: I2C number, 0-4 is hardware I2C, greater than 4 is software I2C
- `freq`: I2C clock frequency (Hz)
- `timeout_ms`: timeout (milliseconds)
- `scl`: SCL pin number (valid in software I2C, must be less than 64)
- `sda`: SDA pin number (valid in software I2C, must be less than 64)
- `inst`: used to store the created I2C instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `void drv_i2c_inst_destroy(drv_i2c_inst_t** inst);`

**Function**: Destroy the I2C host instance and release resources.

**parameter**:

- `inst`: Pointer to I2C instance pointer

---

### `int drv_i2c_set_7b_addr(drv_i2c_inst_t* inst);`

**Function**: Set I2C to 7-bit address mode.

**parameter**:

- `inst`: I2C instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_i2c_set_10b_addr(drv_i2c_inst_t* inst);`

**Function**: Set I2C to 10-bit address mode.

**parameter**:

- `inst`: I2C instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_i2c_set_freq(drv_i2c_inst_t* inst, uint32_t freq);`

**Function**: Set I2C clock frequency.

**parameter**:

- `inst`: I2C instance pointer
- `freq`: clock frequency (Hz)

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_i2c_set_timeout(drv_i2c_inst_t* inst, uint32_t timeout_ms);`

**Function**: Set I2C timeout.

**parameter**:

- `inst`: I2C instance pointer
- `timeout_ms`: timeout (milliseconds)

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_i2c_transfer(drv_i2c_inst_t* inst, i2c_msg_t* msgs, int msg_cnt);`

**Function**: Perform I2C transfer operation.

**parameter**:

- `inst`: I2C instance pointer
- `msgs`: message array
- `msg_cnt`: Number of messages

**Return Value**:

- `0`: Success
- `-1`: failed

---

### I2C host attribute acquisition function

The following functions are used to obtain various properties of the I2C master instance:

- `uint32_t drv_i2c_master_get_type(drv_i2c_inst_t* inst);` - Get I2C type (hardware/software)
- `int drv_i2c_master_get_id(drv_i2c_inst_t* inst);` - Get I2C number
- `int drv_i2c_master_get_fd(drv_i2c_inst_t* inst);` - Get file descriptor
- `uint32_t drv_i2c_master_get_freq(drv_i2c_inst_t* inst);` - Get clock frequency
- `uint32_t drv_i2c_master_get_timeout_ms(drv_i2c_inst_t* inst);` - Get timeout
- `uint8_t drv_i2c_master_get_pin_scl(drv_i2c_inst_t* inst);` - Get SCL pin number
- `uint8_t drv_i2c_master_get_pin_sda(drv_i2c_inst_t* inst);` - Get SDA pin number

---

## I2C slave mode interface

### `int drv_i2c_slave_inst_create(int id, uint32_t buffer_size, uint16_t slave_address, uint8_t scl, uint8_t sda, drv_i2c_slave_inst_t** inst);`

**Function**: Create I2C slave instance.

**parameter**:

- `id`: I2C number
- `buffer_size`: buffer size
- `slave_address`: slave address
- `scl`: SCL pin number
- `sda`: SDA pin number
- `inst`: used to store the created slave instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### I2C slave attribute acquisition function

- `int drv_i2c_slave_get_id(drv_i2c_slave_inst_t* inst);` - Get I2C number
- `int drv_i2c_slave_get_fd(drv_i2c_slave_inst_t* inst);` - Get file descriptor
- `uint8_t drv_i2c_slave_get_pin_scl(drv_i2c_slave_inst_t* inst);` - Get SCL pin number
- `uint8_t drv_i2c_slave_get_pin_sda(drv_i2c_slave_inst_t* inst);` - Get SDA pin number
- `uint32_t drv_i2c_slave_get_buffer_size(drv_i2c_slave_inst_t* inst);` - Get buffer size
- `uint16_t drv_i2c_slave_get_slave_address(drv_i2c_slave_inst_t* inst);` - Get slave address

---

## Usage example

Please refer to `src/rtsmart/libs/testcases/rtsmart_hal/test_i2c_ssd1306.c`

**Note**:

1. Before using hardware I2C, you need to configure the corresponding pin function through FPIOA