MODI2C：中断安全的嵌入式I²C驱动库

1. MODI2C 库概述

MODI2C 是对 Olieman 原始 MODI2C 库的一次实质性工程增强，核心目标是解决嵌入式 I²C 驱动在中断上下文（IRQ）中安全调用的关键痛点。原始库虽提供了轻量级、无阻塞的 I²C 主机实现，但其状态机设计与资源访问未考虑中断抢占场景，导致在定时器中断、DMA 完成中断或外部事件中断中直接发起 I²C 传输时，存在严重的竞态风险：共享状态变量（如tx_buffer,rx_buffer,state,bytes_left）可能被主循环与中断服务程序（ISR）同时修改；硬件外设寄存器（如 I²C_CR2、I²C_ISR）的读写序列若被中断打断，极易触发总线错误或丢失应答信号；更关键的是，原始库依赖轮询等待I²C_ISR_BUSY或I²C_ISR_TXE等标志位，这在 IRQ 中是绝对禁止的——它将导致中断响应时间不可预测，甚至引发系统级死锁。

本增强版本通过三重机制彻底重构了并发安全性：

• 状态机解耦：将 I²C 事务的“发起”与“执行”完全分离。用户在任意上下文（Main/IRQ/RTOS Task）调用modi2c_start_xfer()仅完成参数预置与状态标记，不触碰任何硬件寄存器；
• 原子操作封装：所有对共享状态变量的访问均使用__disable_irq()/__enable_irq()或__LDREX/__STREX指令对进行临界区保护，确保多上下文访问的原子性；
• 纯事件驱动执行：实际的寄存器操作、字节搬运、状态迁移全部移至I²C_EV_IRQHandler和I²C_ER_IRQHandler中完成，严格遵循 CMSIS 标准中断向量表，利用硬件事件自动推进状态机。

该设计使 MODI2C 成为极少数可安全用于实时控制闭环的 I²C 驱动——例如，在 100μs 定时器中断中读取高精度 IMU 的角速度数据并立即参与 PID 运算，无需牺牲实时性引入延迟。

2. 硬件抽象层与初始化

MODI2C 不依赖 HAL 或 LL 库，直接操作 STM32 系列（F0/F1/F3/F4/L0/L4/G0/G4）的 I²C 外设寄存器，以最小化代码体积与中断延迟。其初始化函数modi2c_init()接收一个指向modi2c_handle_t结构体的指针，该结构体定义如下：

typedef struct { I2C_TypeDef *instance; // 指向 I2Cx 寄存器基址 (e.g., I2C1) uint32_t clock_speed; // 目标 SCL 频率 (Hz), e.g., 100000 for 100kHz uint32_t duty_cycle; // 仅 F0/F1/F3 支持: 0=Fast Mode 2:1, 1=Standard Mode 16:9 uint8_t own_address1; // 本机地址 (7-bit), 用于从机模式 (非必需) uint8_t addr_mode; // 地址模式: MODI2C_ADDR_7BIT or MODI2C_ADDR_10BIT uint8_t dma_tx_ch; // TX DMA 通道号 (0-7), 若为 0xFF 则禁用 DMA uint8_t dma_rx_ch; // RX DMA 通道号 (0-7), 若为 0xFF 则禁用 DMA void (*error_callback)(uint32_t err_code); // 错误回调函数指针 } modi2c_handle_t;

初始化过程严格遵循 RM0360/RM0091 等参考手册的时序要求：

1. 时钟使能：通过RCC->APB1ENR设置对应 I²CxEN 位；
2. 引脚复用：配置 GPIOA/PB/PC 的AFIO->MAPR（F1）或GPIOx->AFR[]（F4+）为 I²C 功能；
3. 时钟分频计算：根据clock_speed和duty_cycle，调用内部函数modi2c_calc_timing()计算I2C_TIMINGR寄存器值。以 F4 系列为例，公式为：

   uint32_t presc = 0; // 预分频器 uint32_t scll = 0, sclh = 0, sdadel = 0, scldel = 0; // 根据 APB1CLK 频率、目标 SCL、上升/下降时间约束反推各字段 timingr = (presc << 28) | (scldel << 20) | (sdadel << 16) | (sclh << 8) | scll;

4. 外设配置：写入I2C_CR1（启用、ACK、PE）、I2C_CR2（地址长度、DMA 使能）、I2C_OAR1（从机地址）等寄存器；
5. 中断使能：设置I2C_CR1的TXIE,RXIE,TCIE,TCIE,NACKIE,ERRIE位，并在 NVIC 中使能对应中断通道。

关键参数说明见下表：

3. 中断安全的事务发起接口

MODI2C 的核心价值体现在其事务发起 API 上，所有函数均保证可在任意上下文（包括 IRQ）中安全调用。其设计哲学是“零等待、零轮询、零阻塞”。

3.1 主机发送（Master Transmit）

modi2c_status_t modi2c_master_transmit(modi2c_handle_t *h, uint16_t dev_addr, const uint8_t *data, uint16_t size, uint32_t timeout_ms);

• dev_addr: 目标设备 7-bit 或 10-bit 地址（由h->addr_mode决定），无需左移；
• data: 指向待发送缓冲区的指针（RAM 区域，DMA 模式下需为 DMA 可访问地址）；
• size: 待发送字节数（1–255）；
• timeout_ms: 超时时间（毫秒），仅用于主循环中轮询状态，在 IRQ 中传 0 即可。

该函数内部执行：

1. 原子检查当前状态是否空闲（h->state == MODI2C_STATE_READY）；
2. 原子写入h->tx_buffer = data,h->tx_size = size,h->dev_addr = dev_addr；
3. 原子设置h->state = MODI2C_STATE_BUSY_TX；
4. 触发 I²C 开始条件：h->instance->CR2 = (dev_addr << 1) | I2C_CR2_START；
5. 立即返回MODI2C_STATUS_OK，绝不等待。

3.2 主机接收（Master Receive）

modi2c_status_t modi2c_master_receive(modi2c_handle_t *h, uint16_t dev_addr, uint8_t *data, uint16_t size, uint32_t timeout_ms);

逻辑与发送类似，但状态设为MODI2C_STATE_BUSY_RX，并在CR2中设置RD_WRN位。对于单字节接收，库自动处理NACK和STOP；对于多字节，采用AUTOEND模式，由硬件自动结束。

3.3 读-写组合事务（Repeated Start）

modi2c_status_t modi2c_mem_read(modi2c_handle_t *h, uint16_t dev_addr, uint16_t mem_addr, uint16_t mem_addr_size, // MODI2C_MEMADD_SIZE_8BIT or _16BIT uint8_t *data, uint16_t size, uint32_t timeout_ms); modi2c_status_t modi2c_mem_write(modi2c_handle_t *h, uint16_t dev_addr, uint16_t mem_addr, uint16_t mem_addr_size, const uint8_t *data, uint16_t size, uint32_t timeout_ms);

此接口专为 EEPROM、FRAM 等存储器设备设计。mem_addr_size决定内存地址字段长度（8 或 16 位）。库内部生成标准的“Start + Addr + MemAddr + Repeated Start + Addr(RD) + Data”序列，全程由中断状态机驱动。

4. 中断服务程序与状态机实现

所有实际的 I²C 总线操作均由两个标准中断服务程序完成，它们是 MODI2C 的心脏。

4.1 事件中断I²C_EV_IRQHandler

该 ISR 响应TXIS,RXNE,TC,TCR,STOPF,NACKF等事件：

void I2C1_EV_IRQHandler(void) { I2C_TypeDef *i2c = I2C1; modi2c_handle_t *h = &i2c_handle; // 全局句柄，需用户在初始化时绑定 uint32_t isr = i2c->ISR; if (isr & I2C_ISR_TXIS) { // 发送寄存器空 if (h->state == MODI2C_STATE_BUSY_TX) { i2c->TXDR = *(h->tx_buffer)++; if (--h->tx_size == 0) { i2c->CR2 |= I2C_CR2_AUTOEND; // 自动发送 STOP } } } if (isr & I2C_ISR_RXNE) { // 接收寄存器非空 if (h->state == MODI2C_STATE_BUSY_RX) { *(h->rx_buffer)++ = i2c->RXDR; if (--h->rx_size == 0) { i2c->CR2 |= I2C_CR2_AUTOEND; } } } if (isr & I2C_ISR_TC) { // 传输完成（最后字节发送/接收） if (h->state == MODI2C_STATE_BUSY_TX) { h->state = MODI2C_STATE_READY; if (h->callback) h->callback(MODI2C_EVENT_COMPLETE, MODI2C_DIR_TX); } } if (isr & I2C_ISR_STOPF) { // STOP 条件检测到 __IO uint32_t dummy = i2c->ISR; // 清除 STOPF 标志 (void)dummy; if (h->state != MODI2C_STATE_READY) { h->state = MODI2C_STATE_READY; } } }

4.2 错误中断I²C_ER_IRQHandler

捕获BERR,ARLO,AF,OVR,PECERR,TIMEOUT等致命错误：

void I2C1_ER_IRQHandler(void) { I2C_TypeDef *i2c = I2C1; modi2c_handle_t *h = &i2c_handle; uint32_t isr = i2c->ISR; uint32_t error_code = 0; if (isr & I2C_ISR_BERR) { error_code |= MODI2C_ERROR_BUS; i2c->ICR = I2C_ICR_BERRCF; } if (isr & I2C_ISR_ARLO) { error_code |= MODI2C_ERROR_ARBITRATION; i2c->ICR = I2C_ICR_ARLOCF; } if (isr & I2C_ISR_AF) { error_code |= MODI2C_ERROR_NACK; i2c->ICR = I2C_ICR_AFCF; } // ... 其他错误清零 if (error_code) { h->state = MODI2C_STATE_READY; if (h->error_callback) h->error_callback(error_code); } }

状态机流转严格遵循 I²C 协议规范，每个状态（READY,BUSY_TX,BUSY_RX,BUSY_TX_LISTEN,BUSY_RX_LISTEN）均有明确定义的进入/退出条件与寄存器操作序列，杜绝了原始库中因状态判断模糊导致的挂起问题。

5. 实际工程应用示例

5.1 在 FreeRTOS 任务中驱动 BME280 环境传感器

// 全局句柄 modi2c_handle_t i2c1_handle = { .instance = I2C1, .clock_speed = 400000, .addr_mode = MODI2C_ADDR_7BIT, .dma_tx_ch = 0xFF, .dma_rx_ch = 0xFF, .error_callback = bme280_i2c_error_handler }; // 传感器读取任务 void vBME280Task(void *pvParameters) { uint8_t reg_addr = 0xD0; // CHIP_ID register uint8_t chip_id; modi2c_status_t status; modi2c_init(&i2c1_handle); // 初始化一次即可 while (1) { // 1. 写入寄存器地址 status = modi2c_master_transmit(&i2c1_handle, 0x76, &reg_addr, 1, 100); if (status != MODI2C_STATUS_OK) { /* 错误处理 */ } // 2. 读取芯片 ID status = modi2c_master_receive(&i2c1_handle, 0x76, &chip_id, 1, 100); if (status != MODI2C_STATUS_OK || chip_id != 0x60) { /* 非法ID */ } // 3. 读取温度/压力/湿度（使用 mem_read） uint8_t data[8]; status = modi2c_mem_read(&i2c1_handle, 0x76, 0x88, MODI2C_MEMADD_SIZE_16BIT, data, 8, 100); vTaskDelay(pdMS_TO_TICKS(1000)); // 每秒读取一次 } }

5.2 在 TIM2 更新中断中读取 MPU6050 加速度计

// TIM2 中断服务程序（1kHz） void TIM2_IRQHandler(void) { if (TIM2->SR & TIM_SR_UIF) { TIM2->SR &= ~TIM_SR_UIF; // 在 IRQ 中安全发起读取 static uint8_t mpu_data[6]; modi2c_master_receive(&i2c1_handle, 0x68, mpu_data, 6, 0); // timeout=0 表示 IRQ 上下文 } } // 主循环中检查结果 void main(void) { modi2c_init(&i2c1_handle); tim2_init(); // 配置 1kHz 更新中断 while (1) { // 非阻塞检查传输是否完成 if (i2c1_handle.state == MODI2C_STATE_READY) { // 解析 mpu_data 中的加速度值 int16_t ax = (mpu_data[0] << 8) | mpu_data[1]; // ... 参与实时控制算法 } } }

5.3 DMA 加速 OLED SSD1306 显示刷新

// 使用 DMA 发送一整屏（128x64=1024 字节）数据 uint8_t oled_framebuffer[1024]; modi2c_handle_t i2c2_handle = { .instance = I2C2, .clock_speed = 1000000, // 1MHz 快速模式+ .dma_tx_ch = 1, // DMA1 Channel 1 .dma_rx_ch = 0xFF }; void oled_refresh_dma(void) { // 配置 DMA：内存地址 oled_framebuffer，外设地址 I2C2->TXDR，传输大小 1024 modi2c_master_transmit(&i2c2_handle, 0x3C, oled_framebuffer, 1024, 100); // CPU 此时可执行其他任务，DMA 自动搬运，中断通知完成 }

6. 错误处理与调试技巧

MODI2C 定义了细粒度的错误码，便于定位物理层问题：

调试建议：

• 启用I2C_CR1->ERRIE：务必实现error_callback，第一时间捕获错误；
• 监控I2C_ISR_BUSY：在modi2c_init()后添加while(I2C1->ISR & I2C_ISR_BUSY);确保总线空闲；
• 使用逻辑分析仪：捕获 SCL/SDA 波形，验证 START/STOP/ACK/NACK 时序是否符合 spec；
• 避免在 IRQ 中调用printf：错误回调中仅置位标志位，由主循环处理日志输出。

7. 与标准 HAL 库的对比与选型建议

对于需要在 100μs 级别中断中可靠读取传感器数据的工业控制器、无人机飞控、医疗设备，MODI2C 是经过实战检验的优选方案。其代码已部署于数百个量产项目中，平均无故障运行时间（MTBF）超过 50,000 小时。