跳至主要內容

I2C模块用户手册

大约 15 分钟约 4444 字2025/12/26

I2C模块用户手册

目录

1. 简介

本I2C驱动模块提供了对I2C（Inter-Integrated Circuit）外设的抽象接口，旨在简化微控制器（MCU）作为主机或从机与其他设备进行通信的过程。模块支持同步阻塞和异步非阻塞（中断驱动）两种通信方式。

主要功能包括：

  • 初始化与反初始化:
    • 通过 HLI_I2c_Init 或 HLI_I2c_MasterInitModule/HLI_I2c_SlaveInitModule 对一个或多个I2C模块进行配置。
  • 主机模式操作:
    • 同步读写: 使用 HLI_I2c_MasterSyncWrite、HLI_I2c_MasterSyncRead 和 HLI_I2c_MasterSyncWriteRead (带RESTART) 执行阻塞式读写，适用于简单、低频率的操作。
    • 异步读写: 使用 HLI_I2c_MasterAsyncTransmit、HLI_I2c_MasterAsyncSend 和 HLI_I2c_MasterAsyncReceive 发起非阻塞式读写，通过中断和回调函数通知操作完成，适用于需要高效率和并发处理的场景。
  • 从机模式操作:
    • 异步响应: 通过 HLI_I2c_SlaveAsyncTransmit、HLI_I2C_SlaveSetTxBuffer 和 HLI_I2C_SlaveSetRxBuffer 配置从机的数据缓冲区，以异步方式响应主机的读写请求。
  • 状态获取: 通过 HLI_I2c_GetBusyState 查询总线状态。

1.1 支持的设备

当前软件适用于以下芯片:

  • KF32A158xxxSF

1.2 名词及缩写

缩写解释
MCU微控制器
I2C集成电路总线
ISR中断服务例程

2. 文件结构

文件名称描述
kf32axxx_hli_i2c.c此文件包含I2C驱动程序的通用功能
kf32axxx_hli_i2c.h此头文件输出I2C驱动程序的宏、类型定义和函数原型
__irq_i2c.c此文件包含I2C模块中断服务函数
kf32axxx_hli_i2c_cfg.h此文件包含I2C模块相关配置及宏定义
kf32axxx_hli_i2c_Lcfg.c此文件包含I2C初始化配置信息
kf32axxx_hli_i2c_Lcfg.h此文件包含I2C声明初始化配置信息

3. 数据结构

3.1 数据类型

3.1.1 宏定义

无。

3.1.2 枚举

  1. I2C模块 (HLI_I2c_ModuleType)

    枚举值解释
    HLI_I2C_MODULE_0I2C0模块
    HLI_I2C_MODULE_1I2C1模块
    HLI_I2C_MODULE_2I2C2模块
    HLI_I2C_MAX_INDEXI2C模块最大索引

  2. I2C工作模式 (HLI_I2c_ModeType)

    枚举值解释
    HLI_I2C_MASTER主机模式
    HLI_I2C_SLAVE从机模式

  3. I2C波特率 (HLI_I2c_BaudType)

    枚举值解释
    HLI_I2C_BAUDRATE_100K波特率: 100k
    HLI_I2C_BAUDRATE_150K波特率: 150k
    HLI_I2C_BAUDRATE_400K波特率: 400k

  4. I2C状态 (HLI_I2c_ModuleStateType)

    枚举值解释
    HLI_I2C_UNUSEDI2C当前未使用
    HLI_I2C_INITI2C已初始化

  5. I2C函数执行结果 (HLI_I2c_StatusType)

    枚举值解释
    HLI_I2C_SUCCESS函数执行成功
    HLI_I2C_FAILED函数执行失败
    HLI_I2C_MSGLEN_ERRORI2C消息长度为0
    HLI_I2C_TIME_ERROR等待I2C标志超时
    HLI_I2C_ACK_ERROR等待ACK超时
    HLI_I2C_BUSY_ERRORI2C总线忙

3.1.3 类型定义

  1. 回调函数类型

    类型定义名称解释
    HLI_I2c_RecvDataFcnType数据接收完成回调函数
    HLI_I2c_SendDataFcnType数据发送完成回调函数
    HLI_I2c_BusErrorFcnTypeI2C总线错误回调函数
    HLI_I2c_StopFcnType传输停止回调函数
    HLI_I2c_AddrValidFcnType地址匹配成功回调函数

3.2 配置项说明

  1. 静态配置

    静态配置在 kf32axxx_hli_i2c_cfg.h 文件中通过宏定义完成。

    宏定义解释取值范围
    I2C_DEFAULT_SEND_DATA定义了在某些情况下（如从机模式下，主机读取的数据超出从机准备的数据长度时）发送的默认字节。0 ~ 0xFF

  2. 主机模式配置 (HLI_I2c_MasterConfigType)

    成员解释取值范围
    BaudrateI2C总线波特率。HLI_I2C_BAUDRATE_100K, HLI_I2C_BAUDRATE_150K, HLI_I2C_BAUDRATE_400K
    RecvDataFcn异步接收完成时的回调函数指针。HLI_I2c_RecvDataFcnType 类型的函数指针。
    SendDataFcn异步发送完成时的回调函数指针。HLI_I2c_SendDataFcnType 类型的函数指针。
    BusErrorFcn总线错误事件的回调函数指针。HLI_I2c_BusErrorFcnType 类型的函数指针。
    StopFcn停止信号事件的回调函数指针。HLI_I2c_StopFcnType 类型的函数指针。

  3. 从机模式配置 (HLI_I2c_SlaveConfigType)

    成员解释取值范围
    SlaveAddr7位从机地址。0x00 - 0x7F
    AddrMask从机地址掩码，用于地址范围匹配。0x00 - 0x7F
    MatchAllEnable是否使能地址全匹配（忽略 SlaveAddr 和 AddrMask）。true / false
    RecvDataFcn异步接收完成时的回调函数指针。HLI_I2c_RecvDataFcnType 类型的函数指针。
    SendDataFcn异步发送完成时的回调函数指针。HLI_I2c_SendDataFcnType 类型的函数指针。
    BusErrorFcn总线错误事件的回调函数指针。HLI_I2c_BusErrorFcnType 类型的函数指针。
    StopFcn停止信号事件的回调函数指针。HLI_I2c_StopFcnType 类型的函数指针。
    AddrValidFcn地址匹配成功事件的回调函数指针。HLI_I2c_AddrValidFcnType 类型的函数指针。

  4. 顶层配置 (HLI_I2c_ConfigType)

    成员解释取值范围
    I2cNumConfigPtr指向一个 HLI_I2c_NumConfigType 数组的指针，该数组包含了所有要初始化的I2C模块的配置。
    I2cNum要初始化的I2C模块的数量。

  5. 单个模块配置 (HLI_I2c_ModuleConfigType)

    成员解释取值范围
    I2cModeI2C模式, 主机或者从机。可选范围参考 HLI_I2c_ModeType。
    MasterConfig主机模式配置指针。指向主机模式配置（HLI_I2c_MasterConfigType）的指针。
    SlaveConfig从机模式配置指针。指向从机模式配置（HLI_I2c_SlaveConfigType）的指针。

  6. 单元配置 (HLI_I2c_NumConfigType)

    成员解释取值范围
    ModuleIndexI2C模块索引序号可选范围参考 HLI_I2c_ModuleType。
    ModuleConfig单个模块的配置单个模块配置(HLI_I2c_ModuleConfigType)的结构体。

4. 驱动函数

4.1 函数接口

4.1.1 HLI_I2c_Init

NameDescription
函数名称HLI_I2c_Init
语法:HLI_I2c_StatusType HLI_I2c_Init(const HLI_I2c_ConfigType *configPtr)
同步/异步:同步
重入性 :不可重入
形参(输入):configPtr : I2C配置结构体指针
返回值:HLI_I2C_SUCCESS -- 初始化成功
返回值:HLI_I2C_FAILED -- 模块已被初始化
描述:初始化一个或多个I2C模块。
注意事项:该函数会根据输入的配置结构体，完成所有指定I2C模块的初始化。

4.1.2 HLI_I2c_MasterInitModule

NameDescription
函数名称HLI_I2c_MasterInitModule
语法:HLI_I2c_StatusType HLI_I2c_MasterInitModule(HLI_I2c_ModuleType I2cIndex, const HLI_I2c_MasterConfigType *MasterConfigPtr)
同步/异步:同步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):MasterConfigPtr : I2C模块主机配置结构体指针
返回值:HLI_I2C_SUCCESS -- 初始化成功
返回值:HLI_I2C_FAILED -- 模块已被初始化
描述:初始化单个I2C模块为主机模式。
注意事项:设置I2C模块时钟为SCLK, 并根据入口参数设置波特率寄存器。

4.1.3 HLI_I2c_SlaveInitModule

NameDescription
函数名称HLI_I2c_SlaveInitModule
语法:HLI_I2c_StatusType HLI_I2c_SlaveInitModule(HLI_I2c_ModuleType I2cIndex, const HLI_I2c_SlaveConfigType *SlaveConfigPtr)
同步/异步:同步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):SlaveConfigPtr : I2C模块从机配置结构体指针
返回值:HLI_I2C_SUCCESS -- 初始化成功
返回值:HLI_I2C_FAILED -- 模块已被初始化
描述:初始化单个I2C模块为从机模式。
注意事项:会根据配置设置从机地址。

4.1.4 HLI_I2c_DeInit

NameDescription
函数名称HLI_I2c_DeInit
语法:void HLI_I2c_DeInit(HLI_I2c_ModuleType I2cIndex)
同步/异步:同步
重入性 :可重入
形参(输入):I2cIndex : I2C模块索引号
返回值:无
描述:去初始化指定的I2C模块。
注意事项:无

4.1.5 HLI_I2c_MasterSyncWrite

NameDescription
函数名称HLI_I2c_MasterSyncWrite
语法:HLI_I2c_StatusType HLI_I2c_MasterSyncWrite(HLI_I2c_ModuleType I2cIndex, const HLI_I2c_MessageType *I2c_Msg)
同步/异步:同步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):I2c_Msg : 指向I2C消息结构体的指针
返回值:HLI_I2C_SUCCESS -- 成功
返回值:HLI_I2C_FAILED -- I2C模块未就绪
返回值:HLI_I2C_MSGLEN_ERROR -- 消息长度为0
返回值:HLI_I2C_TIME_ERROR -- 等待标志超时
返回值:HLI_I2C_ACK_ERROR -- 等待ACK超时
返回值:HLI_I2C_BUSY_ERROR -- I2C总线忙
描述:同步（阻塞）方式向I2C从机写入数据。
注意事项:无

4.1.6 HLI_I2c_MasterSyncRead

NameDescription
函数名称HLI_I2c_MasterSyncRead
语法:HLI_I2c_StatusType HLI_I2c_MasterSyncRead(HLI_I2c_ModuleType I2cIndex, const HLI_I2c_MessageType *I2c_Msg)
同步/异步:同步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):I2c_Msg : 指向I2C消息结构体的指针
返回值:HLI_I2C_SUCCESS -- 成功
返回值:HLI_I2C_FAILED -- I2C模块未就绪
返回值:HLI_I2C_MSGLEN_ERROR -- 消息长度为0
返回值:HLI_I2C_TIME_ERROR -- 等待标志超时
返回值:HLI_I2C_ACK_ERROR -- 等待ACK超时
返回值:HLI_I2C_BUSY_ERROR -- I2C总线忙
描述:同步（阻塞）方式从I2C从机读取数据。
注意事项:无

4.1.7 HLI_I2c_MasterSyncWriteRead

NameDescription
函数名称HLI_I2c_MasterSyncWriteRead
语法:HLI_I2c_StatusType HLI_I2c_MasterSyncWriteRead(HLI_I2c_ModuleType I2cIndex, const HLI_I2c_MessageType *WriteMsg, const HLI_I2c_MessageType *ReadMsg)
同步/异步:同步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):WriteMsg : 指向I2C发送消息的指针
形参(输入):ReadMsg : 指向I2C接收消息的指针
返回值:HLI_I2C_SUCCESS -- 成功
返回值:HLI_I2C_FAILED -- I2C模块未就绪
返回值:HLI_I2C_MSGLEN_ERROR -- 消息长度为0
返回值:HLI_I2C_TIME_ERROR -- 等待标志超时
返回值:HLI_I2C_ACK_ERROR -- 等待ACK超时
返回值:HLI_I2C_BUSY_ERROR -- I2C总线忙
描述:使用RESTART时序操作I2C从机，即先向从机发送数据，然后发送RESTART信号，再读取数据。
注意事项:无

4.1.8 HLI_I2c_MasterAsyncTransmit

NameDescription
函数名称HLI_I2c_MasterAsyncTransmit
语法:HLI_I2c_StatusType HLI_I2c_MasterAsyncTransmit(HLI_I2c_ModuleType I2cIndex, uint32_t SlaveAddr, const HLI_I2c_IntrMessageType *MasterMsg)
同步/异步:异步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):SlaveAddr: 从机地址
形参(输入):MasterMsg : 指向I2C中断消息结构体的指针
返回值:HLI_I2C_SUCCESS -- 成功
返回值:HLI_I2C_FAILED -- I2C模块未就绪
返回值:HLI_I2C_MSGLEN_ERROR -- 数据长度错误
返回值:HLI_I2C_BUSY_ERROR -- I2C总线忙
描述:配置I2C主机进行异步传输（读、写或读写）。
注意事项:1. 若MasterMsg->SendBuf为NULL, 但MasterMsg->ReceiveBuf不为NULL, 则为单接收。
2. 若MasterMsg->SendBuf不为NULL, 但MasterMsg->ReceiveBuf为NULL, 则为单发送。
3. 若MasterMsg->SendBuf和MasterMsg->ReceiveBuf均不为NULL, 则使用RESTART信号，先发送再接收。

4.1.9 HLI_I2c_MasterAsyncSend

NameDescription
函数名称HLI_I2c_MasterAsyncSend
语法:HLI_I2c_StatusType HLI_I2c_MasterAsyncSend(HLI_I2c_ModuleType I2cIndex, uint32_t SlaveAddr, const uint8_t *SendBuf, uint32_t SendLength)
同步/异步:异步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):SlaveAddr: 从机地址
形参(输入):SendBuf: 指向发送数据buffer的指针
形参(输入):SendLength: 发送数据长度
返回值:HLI_I2c_StatusType
描述:异步方式向I2C从机写入数据。
注意事项:无

4.1.10 HLI_I2c_MasterAsyncReceive

NameDescription
函数名称HLI_I2c_MasterAsyncReceive
语法:HLI_I2c_StatusType HLI_I2c_MasterAsyncReceive(HLI_I2c_ModuleType I2cIndex, uint32_t SlaveAddr, uint8_t *ReceiveBuf, uint32_t ReceiveLength)
同步/异步:异步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):SlaveAddr: 从机地址
形参(输入):ReceiveBuf: 指向接收数据buffer的指针
形参(输入):ReceiveLength: 接收数据长度
返回值:HLI_I2c_StatusType
描述:异步方式从I2C从机读取数据。
注意事项:无

4.1.11 HLI_I2c_SlaveAsyncTransmit

NameDescription
函数名称HLI_I2c_SlaveAsyncTransmit
语法:HLI_I2c_StatusType HLI_I2c_SlaveAsyncTransmit(HLI_I2c_ModuleType I2cIndex, const HLI_I2c_IntrMessageType *SlaveMsg)
同步/异步:异步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):SlaveMsg : 指向I2C从机中断消息结构体的指针
返回值:HLI_I2C_SUCCESS -- 成功
返回值:HLI_I2C_FAILED -- I2C模块未就绪
描述:配置I2C从机用于异步响应的发送和接收缓冲区。
注意事项:无

4.1.12 HLI_I2C_SlaveSetTxBuffer

NameDescription
函数名称HLI_I2C_SlaveSetTxBuffer
语法:void HLI_I2C_SlaveSetTxBuffer(HLI_I2c_ModuleType I2cIndex, const uint8_t *TxBuffer, uint32_t TxSize)
同步/异步:同步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):TxBuffer : 指向发送buffer的指针
形参(输入):TxSize: 发送数据长度
返回值:无
描述:在从机模式下，设置下一次主机读取时要发送的数据缓冲区和长度。
注意事项:通常在地址匹配回调 (AddrValidFcn) 或发送完成回调 (SendDataFcn) 中调用，用于准备下一次的发送内容。

4.1.13 HLI_I2C_SlaveSetRxBuffer

NameDescription
函数名称HLI_I2C_SlaveSetRxBuffer
语法:void HLI_I2C_SlaveSetRxBuffer(HLI_I2c_ModuleType I2cIndex, uint8_t *RxBuffer, uint32_t RxSize)
同步/异步:同步
重入性 :不可重入
形参(输入):I2cIndex : I2C模块索引号
形参(输入):RxBuffer : 指向接收buffer的指针
形参(输入):RxSize: 接收数据长度
返回值:无
描述:在从机模式下，设置用于接收下一次主机写入数据的缓冲区和长度。
注意事项:通常在地址匹配回调 (AddrValidFcn) 或接收完成回调 (RecvDataFcn) 中调用，为下一次接收做准备。

4.1.14 HLI_I2c_GetBusyState

NameDescription
函数名称HLI_I2c_GetBusyState
语法:bool HLI_I2c_GetBusyState(HLI_I2c_ModuleType I2cIndex)
同步/异步:同步
重入性 :可重入
形参(输入):I2cIndex : I2C模块索引号
返回值:true -- I2C总线忙
返回值:false -- I2C总线空闲
描述:获取I2C总线状态。
注意事项:无

4.2 中断回调

4.2.1 HLI_I2c_RecvDataFcnType

NameDescription
函数指针名称HLI_I2c_RecvDataFcnType
语法void (*HLI_I2c_RecvDataFcnType)(HLI_I2c_ModuleType I2cIndex, uint8_t *RxData)
形参(输入)I2cIndex: I2C模块索引号
形参(输入)RxData: 指向接收Buffer的指针
描述当接收数量等于设置数量时，通知用户已完成一组数据接收。
注意事项建议不在回调函数内进行耗时操作，仅操作数据。当接收完成时, 若不及时将数据取出, 最后一个字节可能存在被覆盖的风险。

4.2.2 HLI_I2c_SendDataFcnType

NameDescription
函数指针名称HLI_I2c_SendDataFcnType
语法void (*HLI_I2c_SendDataFcnType)(HLI_I2c_ModuleType I2cIndex)
形参(输入)I2cIndex : I2C模块索引号
描述当发送数量等于设置数量时，通知用户已完成一组数据发送。
注意事项建议不在回调函数内进行耗时操作，仅操作数据。

4.2.3 HLI_I2c_BusErrorFcnType

NameDescription
函数指针名称HLI_I2c_BusErrorFcnType
语法void (*HLI_I2c_BusErrorFcnType)(HLI_I2c_ModuleType I2cIndex)
形参(输入)I2cIndex : I2C模块索引号
描述当I2C总线出现错误时，通知用户。
注意事项无

4.2.4 HLI_I2c_StopFcnType

NameDescription
函数指针名称HLI_I2c_StopFcnType
语法void (*HLI_I2c_StopFcnType)(HLI_I2c_ModuleType I2cIndex, bool TransmitDir)
形参(输入)I2cIndex : I2C模块索引号
形参(输入)TransmitDir: 传输方向 (true -- 读从机, false -- 写从机)
描述当总线上检测到STOP信号时产生通知。
注意事项在从机模式下，可用于判断一帧通信的结束。

4.2.5 HLI_I2c_AddrValidFcnType

NameDescription
函数指针名称HLI_I2c_AddrValidFcnType
语法void (*HLI_I2c_AddrValidFcnType)(HLI_I2c_ModuleType I2cIndex, bool TransmitDir)
形参(输入)I2cIndex : I2C模块索引号
形参(输入)TransmitDir: 传输方向 (true -- 主机读从机, false -- 主机写从机)
描述当从机接收到匹配的地址时产生通知。
注意事项仅用于从机模式。可以在此回调中准备要发送或接收的数据。

5. 使用示例

注

示例中使用的参数仅用作示例演示，应用时以实际为准。

1. 主机同步读写

此模式下，程序会阻塞等待每次I2C传输完成。

2. 主机异步读写

此模式下，函数调用立即返回，通过中断和回调函数处理传输过程。

3. 从机异步响应

从机完全由中断驱动，响应主机的请求。

6. 限制与假设

  • 波特率: 仅支持100K、150K、400K波特率。
  • 地址模式: 默认使用7位从机地址, 10位从机地址暂不支持。
  • 运行时错误: 当模块未初始化、或正在进行读写时, 再次调用读写数据接口, 驱动会返回错误码。

7. 变更记录

版本时间变更记录
v1.02025-11-20新增初版文档
最近更新
贡献者: 翟宇