Edit online

接口设计

2 Dec 2024
Read time: 6 minute(s)

Driver 层接口设计

表 1. aic_hw_i2c_register
函数原型 static int aic_hw_i2c_register()
功能说明 注册和初始化 I2C 设备
参数定义 NULL
返回值
0：注册成功
<0：注册失败
注意事项 -
表 2. aic_i2c_bus_control
函数原型 static rt_err_t aic_i2c_bus_control(struct rt_i2c_bus_device *bus, rt_uint32_t cmd, rt_uint32_t value)
功能说明 对 I2C 总线参数进行设置，目前支持更改总线速率
参数定义
bus：I2C 接口对应的总线指针
cmd：命令参数
value：命令值
返回值
RT_EOK：函数执行成功
-RT_EIO：非法操作
注意事项 -
表 3. aic_i2c_slave_control
函数原型 static rt_err_t aic_i2c_slave_control(struct rt_i2c_bus_device *bus, rt_uint32_t cmd, void *arg)
功能说明 对 I2C 从机回调函数进行配置
参数定义
bus：I2C 接口对应的总线指针
cmd：命令参数
arg：回调函数参数
返回值
RT_EOK：函数执行成功
注意事项 -
表 4. aic_i2c_master_xfer
函数原型 static rt_size_t aic_i2c_master_xfer(struct rt_i2c_bus_device *bus, struct rt_i2c_msg msgs[], rt_uint32_t num)
功能说明 I2C 数据传输函数
参数定义
bus：I2C 接口对应的总线指针
msgs： 发送的消息数组
num： 发送的消息数量
返回值 返回已发出的消息数量
注意事项 -
表 5. aic_i2c_xfer_msg
函数原型 static int aic_i2c_xfer_msg(struct aic_i2c_ctrl *i2c_dev, struct aic_i2c_msg *msg, bool is_first, bool is_last)
功能说明 I2C 数据传输函数
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
msg：指向当前将要传输的 msg | is_first：指示当前 msg 是否是第一个 msg | is_last：指示当前 msg 是否是最后一个 msg
返回值
0：执行成功
<0：执行过程中发生错误
注意事项 -
表 6. aic_i2c_xfer_msg_init
函数原型 static void aic_i2c_xfer_msg_init(struct aic_i2c_ctrl *i2c_dev)
功能说明 在传输每个 msg 前进行的初始化，主要是将指示每个 msg 状态的变量设置为初始值，使能中断
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
返回值 无
注意事项 -
表 7. aic_i2c_handle_write
函数原型 static void aic_i2c_handle_write(struct aic_i2c_ctrl *i2c_dev)
功能说明 当触发 TX_EMPTY 中断时，调用该函数。若是读 msg，则调用该函数发送读命令，若是写 msg，则调用该函数发送数据
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
返回值 无
注意事项 -
表 8. aic_i2c_handle_read
函数原型 static void aic_i2c_handle_read(struct aic_i2c_ctrl *i2c_dev)
功能说明 当触发 RX_FULL 中断时，调用该函数读取接收到的数据，若完成当前 msg 的接收，则释放完成量
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
返回值 无
注意事项 -

HAL 层接口设计

表 9. hal_i2c_init
函数原型 int hal_i2c_init(aic_i2c_ctrl *i2c_dev)
功能说明 初始化 I2C 的时钟，主从模式，速率等基础设置
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
返回值
0：执行成功
<0：执行过程中发生错误
注意事项 -
表 10. hal_i2c_clk_init
函数原型 int hal_i2c_clk_init(aic_i2c_ctrl *i2c_dev)
功能说明 初始化 I2C 的时钟
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
返回值
0：执行成功
<0：执行过程中发生错误
注意事项 -
表 11. hal_i2c_set_hold
函数原型 void hal_i2c_set_hold(aic_i2c_ctrl *i2c_dev, u32 val)
功能说明 设置 SDA 的保持时间
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体 | val：设置保持时间的 cycle 数量，保持时间：val*41.66 ns
返回值 无
注意事项 -
表 12. hal_i2c_set_master_slave_mode
函数原型 int hal_i2c_set_master_slave_mode(aic_i2c_ctrl *i2c_dev)
功能说明 设置主从模式
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
返回值
0：执行成功
<0：执行过程中发生错误
注意事项 -
表 13. hal_i2c_master_10bit_addr
函数原型 int hal_i2c_master_10bit_addr(aic_i2c_ctrl *i2c_dev)
功能说明 设置主机模式的寻址模式
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
返回值
0：执行成功
<0：执行过程中发生错误
注意事项 -
表 14. hal_i2c_slave_10bit_addr
函数原型 int hal_i2c_slave_10bit_addr(aic_i2c_ctrl *i2c_dev)
功能说明 设置从机模式的寻址模式
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
返回值
0：执行成功
<0：执行过程中发生错误
注意事项 -
表 15. hal_i2c_scl_cnt
函数原型 static int hal_i2c_scl_cnt(uint32_t clk_freq, uint8_t is_standard_speed, uint16_t *hcnt, uint16_t *lcnt)
功能说明 根据 i2c 模块工作的时钟频率和 i2c 的传输速率，返回需要设置的 hcnt 值和 lcnt 值
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体
返回值
0：执行成功
<0：执行过程中发生错误
注意事项 -
表 16. hal_i2c_speed_mode_select
函数原型 int hal_i2c_speed_mode_select(aic_i2c_ctrl *i2c_dev, uint32_t clk_freq, uint8_t mode)
功能说明 设置 I2C 的传输的工作模式和传输速率
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体 | clk_freq：模块时钟的时钟频率 | mode：工作模式
返回值
0：执行成功
<0：执行过程中发生错误
注意事项 -
表 17. hal_i2c_target_addr
函数原型 void hal_i2c_target_addr(aic_i2c_ctrl *i2c_dev, uint32_t addr)
功能说明 设置 I2C 目标设备的地址
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体 | addr：目标地址
返回值 无
注意事项 -
表 18. hal_i2c_slave_own_addr
函数原型 int hal_i2c_slave_own_addr(aic_i2c_ctrl *i2c_dev, uint32_t addr)
功能说明 设置 SLAVE 模式被寻址的地址
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体 | addr：目标地址
返回值
0：执行成功
<0：执行过程中发生错误
注意事项 -
表 19. hal_i2c_wait_transmit
函数原型 static int32_t hal_i2c_wait_transmit(aic_i2c_ctrl *i2c_dev, uint32_t timeout)
功能说明 I2C 数据发送的超时函数
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体 | timeout：超时时间单位 ms
返回值
0：执行成功
<0：超时
注意事项 -
表 20. hal_i2c_wait_receive
函数原型 static int32_t hal_i2c_wait_receive(aic_i2c_ctrl *i2c_dev, uint32_t wait_data_num, uint32_t timeout)
功能说明 I2C 数据接收的超时函数
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体 | wait_data_num：等待接收数据的数量 | timeout：超时时间单位 ms
返回值
0：执行成功
<0：超时
注意事项 -
表 21. hal_i2c_wait_bus_free
函数原型 int32_t hal_i2c_wait_bus_free(aic_i2c_ctrl *i2c_dev, uint32_t timeout)
功能说明 等待 I2C 总线空闲
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体 | timeout：超时时间单位 ms
返回值
0：执行成功
<0：超时
注意事项 -
表 22. hal_i2c_master_send_msg
函数原型 int32_t hal_i2c_master_send_msg(aic_i2c_ctrl *i2c_dev, struct aic_i2c_msg *msg, uint8_t is_last_message)
功能说明 发送数据
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体 | msg：指向当前将要传输的 msg | is_last_message：指示当前 msg 是否是最后一个 msg
返回值
send_count：发送数据的数量
<0：发送出错
注意事项 -
表 23. hal_i2c_master_receive_msg
函数原型 int32_t hal_i2c_master_receive_msg(aic_i2c_ctrl *i2c_dev, struct aic_i2c_msg *msg, uint8_t is_last_message)
功能说明 发送数据
参数定义
i2c_dev：指向自定义的 aic_i2c_ctrl 结构体 | msg：指向当前将要传输的 msg | is_last_message：指示当前 msg 是否是最后一个 msg
返回值
read_count：接收到数据的数量
<0：接收出错
注意事项 -