RT-Thread在STM32硬件I2C的踩坑记录
参考文章：
1.将硬件I2C巧妙地将“嫁接”到RTT原生的模拟I2C驱动框架
2.基于STM32F4平台的硬件I2C驱动实现笔记
3.《rt-thread驱动框架分析》- i2c驱动
0.前言
最近打算用RT-Thread做一个小demo玩玩，其中需要用I2C通信驱动一个oled屏幕，但是找了一圈也没找到RTT中对硬件I2C的支持方式以及使用案例，好像大家都心照不宣的用这个好用又不好用的软件I2C。这里还是忍不住吐槽两句，连硬件SPI都已经支持了，甚至支持SPI DMA模式了，硬件I2C这么多年了也没适配。也希望有大佬能贡献一份力量，做出一份能让DIY玩家凑合用的第三方硬件I2C驱动也行。
一、软硬件I2C区别
有关I2C通信协议的原理部分就不多介绍了，这个算是很常见的通信协议了，CSDN论坛一搜一大把，RT Thread文档中心也有较详细的介绍。
软件I2C是使用GPIO的电平翻转模拟出I2C信号，它的好处是方便移植，下至51单片机，上至linux平台，只要有GPIO都能适用(当然linux下也不会有人用这个)。缺点则是速率很低，软件操作GPIO电平翻转不可避免的有时延以及毛刺，为了消除这种现象的影响，模拟的I2C信号之间就需要稍微大点的时间间隔。软件I2C的信号频率一般在30KHz ~ 50KHz，即便优化相当好的情况也差不多在这个量级。用来操作128x64的oled屏幕，帧率基本在2帧左右。
硬件I2C则是通过操作芯片自带的寄存器进行I2C通信，缺点就是不同芯片间驱动不通用，优点则是速度更快，并且可以适配DMA模式，降低CPU负载。笔者使用的STM32RCT6，硬件I2C标准模式信号频率为100KHz，快速模式400KHz，一些性能较好的芯片还有1MHz的极速模式。400kHz情况下操作128x64的oled帧率在25帧左右，可以说是提升巨大了。
二、RT Thread中的I2C驱动
关于RT Thread中的I2C驱动框架的实现方式，可以参考上述的第三篇参考文章，个人觉得写的很详细也好懂。RT Thread为类Linux的实时操作系统，所以I2C框架的实现方式和linux中的也比较相像：I2C驱动提供一些操作相关的ops函数，并注册到内核中，I2C设备则可以通过probe函数挂载到总线上，通过ops操作函数进行I2C通信。
并且在该篇文章中，该作者跳过原本的bit_ops，重新设计了一个硬件I2C的实现方式，将驱动直接挂载到内核core中，也实现了作为master设备的硬件I2C驱动。不过笔者认为这种方式对通用结构的兼容性不太好，所以又找了一些其他方式。
三、尝试适配硬件I2C
参考文章1和2中，通过修改I2C总线的实现函数，“嫁接”一个硬件的I2C驱动实现方式。这里就先放上代码，首先在原drv_soft_i2c.c和drv_soft_i2c.h的同级目录下，分别创建drv_hard_i2c.c和drv_hard_i2c.h：
drv_hard_i2c.h：
/*
* Copyright (c) 2006-2018, RT-Thread Development Team
*
* SPDX-License-Identifier: Apache-2.0
*
* Change Logs:
* Date Author Notes
* 2018-11-08 balanceTWK first version
*/
#ifndef __DRV_I2C__
#define __DRV_I2C__
#include <rtthread.h>
#include <rthw.h>
#include <rtdevice.h>
#ifdef BSP_USING_HARD_I2C
/* stm32 config class */
typedef void (*pI2cConfig)(void);
struct stm32_hard_i2c_config
{
rt_uint8_t scl; /* scl pin */
rt_uint8_t sda; /* sda pin */
const pI2cConfig pFunc; /* i2c init function */
const char* pName; /* i2c bus name */
I2C_HandleTypeDef* pHi2c; /* i2c handle */
struct rt_i2c_bus_device i2c_bus; /* i2c bus device */
};
/* stm32 i2c dirver class */
struct stm32_i2c
{
struct rt_i2c_bit_ops ops;
struct rt_i2c_bus_device i2c2_bus;
};
#define HARD_I2C_CONFIG(x) \
{
.scl = BSP_I2C##x##_SCL_PIN, \
.sda = BSP_I2C##x##_SDA_PIN, \
.pFunc = MX_I2C##x##_Init, \
.pHi2c = &hi2c##x, \
.pName = "i2c"#x, \
.i2c_bus = {
.ops = &i2c_bus_ops,
},
}
int rt_hw_i2c_init(void);
#endif
#endif /* RT_USING_I2C */
其中stm32_hard_i2c_config可以理解为i2c实例对象，属性包括scl和sda引脚、总线名称及初始化函数等。（注：在参考文章2中的总线速度、信号量及互斥锁则不需要，因为使用CubeMx生成的初始化函数中已有总线速度，HAL库中的I2C操作函数内部已有总线锁）
stm32_i2c则封装了设备操作函数及总线，用于与内核对接。
函数宏HARD_I2C_CONFIG(x)则用来后续创建I2C设备对象。
drv_hard_i2c.c：
/*
* Copyright (c) 2006-2018, RT-Thread Development Team
*
* SPDX-License-Identifier: Apache-2.0
*
* Change Logs:
* Date Author Notes
* 2018-11-08 balanceTWK first version
*/
#include <board.h>
#include "drv_hard_i2c.h"
#include "drv_config.h"
#include<rtthread.h>
#include<rtdevice.h>
#ifdef BSP_USING_HARD_I2C
//#define DRV_DEBUG
#define LOG_TAG "drv.i2c"
#include <drv_log.h>
static const struct stm32_hard_i2c_config hard_i2c_config[] =
{
#ifdef BSP_USING_HARD_I2C1
HARD_I2C_CONFIG(1),
#endif
#ifdef BSP_USING_HARD_I2C2
HARD_I2C_CONFIG(2),
#endif
#ifdef BSP_USING_HARD_I2C3
HARD_I2C_CONFIG(3),
#endif
#ifdef BSP_USING_HARD_I2C4
HARD_I2C_CONFIG(4),
#endif
};
static struct stm32_i2c i2c_obj[sizeof(hard_i2c_config) / sizeof(hard_i2c_config[0])];
/**
* This function initializes the i2c pin.
*
* @param Stm32 i2c dirver class.
*/
static void stm32_i2c_gpio_init(struct stm32_i2c *i2c)
{
struct stm32_soft_i2c_config* cfg = (struct stm32_soft_i2c_config*)i2c->ops.data;
rt_pin_mode(cfg->scl, PIN_MODE_OUTPUT_OD);
rt_pin_mode(cfg->sda, PIN_MODE_OUTPUT_OD);
rt_pin_write(cfg->scl, PIN_HIGH);
rt_pin_write(cfg->sda, PIN_HIGH);
}
/**
* The time delay function.
*
* @param microseconds.
*/
static void stm32_udelay(rt_uint32_t us)
{
rt_uint32_t ticks;
rt_uint32_t told, tnow, tcnt = 0;
rt_uint32_t reload = SysTick->LOAD;
ticks = us * reload / (1000000 / RT_TICK_PER_SECOND);
told = SysTick->VAL;
while (1)
{
tnow = SysTick->VAL;
if (tnow != told)
{
if (tnow < told)
{
tcnt += told - tnow;
}
else
{
tcnt += reload - tnow + told;
}
told = tnow;
if (tcnt >= ticks)
{
break;
}
}
}
}
/**
* if i2c is locked, this function will unlock it
*
* @param stm32 config class
*
* @return RT_EOK indicates successful unlock.
*/
static rt_err_t stm32_i2c_bus_unlock(const struct stm32_soft_i2c_config *cfg)
{
rt_int32_t i = 0;
if (PIN_LOW == rt_pin_read(cfg->sda))
{
while (i++ < 9)
{
rt_pin_write(cfg->scl, PIN_HIGH);
stm32_udelay(100);
rt_pin_write(cfg->scl, PIN_LOW);
stm32_udelay(100);
}
}
if (PIN_LOW == rt_pin_read(cfg->sda))
{
return -RT_ERROR;
}
return RT_EOK;
}
/* I2C initialization function */
int rt_hw_i2c_init(void)
{
rt_int8_t ret = RT_ERROR;
rt_size_t obj_num = NR(hard_i2c_config);
rt_err_t result;
for (int i = 0; i < obj_num; i++)
{
//GPIO初始化
stm32_i2c_gpio_init(&hard_i2c_config[i]);
//检测SDA是否为低电平，低电平则通过管脚模拟9个CLK解锁
stm32_i2c_bus_unlock(&hard_i2c_config[i]);
//调用Hal库MX_I2Cx_Init()，配置硬件I2C
hard_i2c_config[i].pFunc();
//向内核注册I2C Bus设备
if(rt_i2c_bus_device_register(&(hard_i2c_config[i].i2c_bus), hard_i2c_config[i].pName) != RT_EOK)
{
LOG_E("%s bus init failed!\r\n", hard_i2c_config[i].pName);
ret |= RT_ERROR;
}
else
{
ret |= RT_EOK;
LOG_I("%s bus init success!\r\n", hard_i2c_config[i].pName);
}
}
return ret;
}
//INIT_BOARD_EXPORT(rt_hw_i2c_init);
#endif /* BSP_USING_HARD_I2C */
此文件中则主要根据宏定义开关创建I2C实例对象，并对其进行初始化。主要函数为rt_hw_i2c_init()，此函数中所需要的gpio init、delay函数等，则保留软件i2c中的初始化操作。
user_i2c.h：
/*
* Copyright (c) 2006-2021, RT-Thread Development Team
*
* SPDX-License-Identifier: Apache-2.0
*
* Change Logs:
* Date Author Notes
* 2023-08-27 14187 the first version
*/
#ifndef DRIVERS_HARD_I2C_H_
#define DRIVERS_HARD_I2C_H_
//硬件i2c宏开关
//#define BSP_USING_HARD_I2C
#ifdef BSP_USING_HARD_I2C
// #define BSP_USING_HARD_I2C1
// #define BSP_USING_HARD_I2C2
// #define BSP_USING_HARD_I2C3
// #define BSP_USING_HARD_I2C4
#if defined(BSP_USING_HARD_I2C1 || BSP_USING_HARD_I2C2 || BSP_USING_HARD_I2C3 || BSP_USING_HARD_I2C4)
//#define BSP_USING_DMA_I2C_TX
//#define BSP_USING_DMA_I2C_RX
#endif
#endif
#endif /* DRIVERS_HARD_I2C_H_ */
为了不在每次保存RT Thread Settings时，自己的配置被覆盖刷新，所以额外定义了一个头文件，用于保存自定义的I2C宏开关，这样每次刷新后只需要重新在board.h中包含此头文件即可。
至此自定义的硬件I2C宏开关及设备对象创建已完成，剩下的则只需要替换内核中的bit_ops操作函数即可。
四、i2c-bit-ops操作函数替换
在rt thread项目根目录下的 rt-thread/components/drivers/i2c/ 目录下，有一个i2c-bit-ops.c文件，其中则保存了i2c驱动框架中注册的ops操作函数：
static rt_size_t i2c_bit_xfer(struct rt_i2c_bus_device *bus,
struct rt_i2c_msg msgs[],
rt_uint32_t num)
{
struct rt_i2c_msg *msg;
struct rt_i2c_bit_ops *ops = (struct rt_i2c_bit_ops *)bus->priv;
rt_int32_t i, ret;
rt_uint16_t ignore_nack;
if (num == 0) return 0;
for (i = 0; i < num; i++)
{
msg = &msgs[i];
ignore_nack = msg->flags & RT_I2C_IGNORE_NACK;
if (!(msg->flags & RT_I2C_NO_START))
{
if (i)
{
i2c_restart(ops);
}
else
{
LOG_D("send start condition");
i2c_start(ops);
}
ret = i2c_bit_send_address(bus, msg);
if ((ret != RT_EOK) && !ignore_nack)
{
LOG_D("receive NACK from device addr 0x%02x msg %d",
msgs[i].addr, i);
goto out;
}
}
if (msg->flags & RT_I2C_RD)
{
ret = i2c_recv_bytes(bus, msg);
if (ret >= 1)
{
LOG_D("read %d byte%s", ret, ret == 1 ? "" : "s");
}
if (ret < msg->len)
{
if (ret >= 0)
ret = -RT_EIO;
goto out;
}
}
else
{
ret = i2c_send_bytes(bus, msg);
if (ret >= 1)
{
LOG_D("write %d byte%s", ret, ret == 1 ? "" : "s");
}
if (ret < msg->len)
{
if (ret >= 0)
ret = -RT_ERROR;
goto out;
}
}
}
ret = i;
out:
if (!(msg->flags & RT_I2C_NO_STOP))
{
LOG_D("send stop condition");
i2c_stop(ops);
}
return ret;
}
...
static const struct rt_i2c_bus_device_ops i2c_bit_bus_ops =
{
i2c_bit_xfer,
RT_NULL,
RT_NULL
};
这段代码中实现了对每个i2c设备发送对应的i2c msg流程，将其修改为硬件i2c的发送方式：
static rt_size_t i2c_xfer(struct rt_i2c_bus_device *bus,
struct rt_i2c_msg msgs[],
rt_uint32_t num)
{
rt_uint32_t i;
struct rt_i2c_msg *msg;
struct stm32_hard_i2c_config *Pconfig = rt_container_of(bus, struct stm32_hard_i2c_config, i2c_bus);
fot(i = 0;i < num;i++)
{
msg = &msgs[i];
if(msg->flags & RT_I2C_RD)
{
#if defined(BSP_USING_DMA_I2C_RX)
HAL_I2C_Master_Receive_DMA(Pconfig->pHi2c, (msg->addr)<<1, msg->buf, msg->len);
rt_hw_us_delay(100);
#else
HAL_I2C_Master_Receive(Pconfig->pHi2c, (msg->addr)<<1, msg->buf, msg->len, 100);
#endif
}
else
{
#if defined(BSP_USING_DMA_I2C_TX)
HAL_I2C_Master_Transmit_DMA(Pconfig->pHi2c, (msg->addr)<<1, msg->buf, msg->len);
rt_hw_us_delay(100);
#else
HAL_I2C_Master_Transmit(Pconfig->pHi2c, (msg->addr)<<1, msg->buf, msg->len, 100);
#endif
}
}
return i;
}
static const struct rt_i2c_bus_device_ops i2c_bit_bus_ops =
{
i2c_xfer,
RT_NULL,
RT_NULL
};
参考软件i2c的发送方式，创建一个新的发送函数rt_size_t i2c_xfer()，并将rt_i2c_bus_device_ops 中对应的发送方式修改为此方式。
至此，硬件I2C的驱动则算是完成了一部分，可以通过与软件i2c一样的声明及挂载方式，将设备挂载到硬件I2C总线上。
五、Attention Please!
问题1：在上述的实现方式中，可以根据宏定义通过HAL_I2C_Master_Transmit()或HAL_I2C_Master_Transmit_DMA()方式发送I2C消息，但并未对是否发送成功做出判断。
问题2:ST官方的HAL库中，I2C发送消息共有三种方式，polling模式(轮询)、中断模式、DMA模式，HAL_I2C_Master_Transmit()则对应轮询模式，此模式相对于软件I2C虽然速率有所提升，但实际的提升效果其实不是特别大。而对于中断模式，则需要移植并实现对应的中断处理函数，可以按照参考文章2进行实现，不过笔者认为该篇需要注意的地方很多，比如在中断处理函数中释放信号量的操作，可能会造成一些隐患(可以直接去除信号量)。对于DMA模式，理论上也需要移植一些中断处理函数，但笔者目前没有用这种方式，所以也没有细究。所以理论上只能停留在polling模式。
问题3：在drv_hard_i2c.c中，INIT_BOARD_EXPORT(rt_hw_i2c_init);这个注册步骤，需要根据实际情况而定，如果想要使用DMA模式，则在此注册步骤之前，需要先注册MX_DMA_Init()，此函数为CubeMX生成，用来初始化DMA功能。中断模式同理。
六、总结
目前看来，移植ST的硬件I2C驱动还是困难重重，所以笔者选则了更换平台(我逃避。。。）将oled的电路修改成了SPI模式，并更换了芯片平台，手头还有一个LPC54110和一个CH32的开发板，这两个板子的RTT BSP支持包好像有适配硬件I2C驱动，ST再见，希望下次回来有大佬适配了硬件I2C。