版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_hal/

一、概述

xt_hal_i2c 是 XTINY HAL I2C Master 驱动模块，提供 I2C 总线的初始化、阻塞式读写和半双工传输能力。所有传输函数均为阻塞式，内置互斥保护，多线程安全。

设计原则 ：

仅 Master 模式 ：只提供主机端操作，不包含从机模式
7 位地址 ：所有传输使用标准 7 位 I2C 从机地址
互斥保护 ：内部通过锁保证同一 I2C 总线上多线程调用的安全性
阻塞 API ：所有传输函数均为同步阻塞，调用线程等待传输完成

1.1 依赖

依赖	用途
xt_hal_internal.h	错误码类型 xt_err_t 及平台内部定义

二、核心概念

2.1 I2C 索引（i2c_id）

每个 I2C 外设实例通过 i2c_id 索引标识。使用前需先调用 xt_hal_i2cm_setup 初始化，使用完后调用 xt_hal_i2cm_close 释放资源。索引数量由平台定义。

2.2 传输模式对比

函数	方向	停止信号时机	典型场景
xt_hal_i2cm_tx_block	仅发送	发送完发送	写寄存器配置
xt_hal_i2cm_rx_block	仅接收	接收完发送	读连续数据
xt_hal_i2cm_tx_rx_block	先发后收	接收完发送	写寄存器地址 + 读数据

tx_rx_block 是先写后读的组合操作，在写和读之间 不发送停止信号 （repeated START），适合"写寄存器地址后立即读取寄存器值"的场景。

2.3 速率支持

速度参数 speed 单位为 Hz。常用值为 100000（标准模式）、400000（快速模式）、1000000（快速增强模式）、3400000（高速模式）。实际支持的速率取决于平台硬件。

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_i2c（I2C 驱动）。

3.1 生命周期

函数签名	说明
xt_err_t xt_hal_i2cm_setup(uint8_t i2c_id, uint32_t speed, uint8_t scl_pin, uint8_t sda_pin)	初始化 I2C Master，配置速率与引脚
xt_err_t xt_hal_i2cm_close(uint8_t i2c_id)	关闭 I2C Master，释放资源

3.2 阻塞传输

函数签名	说明
int32_t xt_hal_i2cm_tx_block(uint8_t i2c_id, uint16_t slave_addr, const void *tx_buffer, size_t size)	阻塞发送数据
int32_t xt_hal_i2cm_rx_block(uint8_t i2c_id, uint16_t slave_addr, void *rx_buffer, size_t size)	阻塞接收数据
int32_t xt_hal_i2cm_tx_rx_block(uint8_t i2c_id, uint16_t slave_addr, const void tx_buffer, size_t tx_size, void rx_buffer, size_t rx_size)	阻塞半双工传输（先写后读）

3.3 类型

类型签名	说明
xt_hal_i2c_cb_t	回调函数类型： void (*)(uint8_t i2c_id, uint32_t event_id)
enum xt_hal_i2c_event_id	事件 ID 枚举（ XT_HAL_I2C_EVENT_DONE ）
XT_HAL_I2C_INVALID_ID	无效 I2C ID 宏： (0xFF)

四、编译配置

无编译配置项。

五、常见模式

5.1 读写温度传感器寄存器

#include "xt_hal_i2c.h"
 
#define TEMP_SENSOR_ADDR  0x48
#define REG_TEMP          0x00
 
int32_t read_temp(uint8_t i2c_id) {
    uint8_t reg = REG_TEMP;
    uint8_t data[2] = {0};
 
    int32_t ret = xt_hal_i2cm_tx_rx_block(i2c_id, TEMP_SENSOR_ADDR,
                                           &reg, sizeof(reg),
                                           data, sizeof(data));
    if (ret < 0) {
        return ret;
    }
    int16_t temp_raw = (int16_t)((data[0] << 8) | data[1]);
    return temp_raw;
}
 
void app_init(void) {
    xt_hal_i2cm_setup(0, 400000, 10, 11);
}
 
void app_read(void) {
    int32_t temp = read_temp(0);
    if (temp >= 0) {
        /* 使用温度值 */
    }
}

5.2 仅写配置

#include "xt_hal_i2c.h"
 
void write_config(uint8_t i2c_id, uint8_t config_val) {
    uint8_t buf[2] = {0x01, config_val};
    xt_hal_i2cm_tx_block(i2c_id, 0x68, buf, sizeof(buf));
}

六、已知行为与限制

行为	说明
重复初始化返回繁忙	同一 i2c_id 已初始化时，再次调用 setup 返回 XT_EBUSY
无效 ID 返回参数错误	i2c_id 超出平台可用范围时返回 XT_EINVAL
缓冲区为空或大小为 0 返回参数错误	传输前校验，不产生总线操作
仅 Master 模式	不支持 I2C Slave 模式
7 位地址	从机地址为 7 位，不包含读写位
线程安全	内部使用互斥锁保护，支持多线程并发调用同一 I2C 总线
速度不支持时降级	传入不支持的速率值时，平台自动降级为标准模式（100kHz）