I2C

概述

RTL8721F 提供 I2C 接口,是一种两线制的低速串行同步通信总线,支持主机和从机角色。Rust 驱动 ameba_hal::i2c 直接封装 PAC 寄存器块,不涉及裸位操作或 C FFI 调用。

功能特性

  • 两线制 I2C 串行接口,包括一根数据线 SDA 和一根时钟线 SCL

  • 主机或从机角色,通过 Role::Master / Role::Slave 设置

  • 7 位或 10 位地址模式,通过 AddrFormat::Bit7 / AddrFormat::Bit10 设置

  • 标准速率 ≤100 kHz(SpeedMode::Ss)或快速速率 ≤400 kHz(SpeedMode::Fs),高速模式 SpeedMode::Hs 已声明但 RTL8721F 的 I2C0 不支持

  • 可通过 Config 配置 SDA 保持/建立时间、RX/TX FIFO 阈值、SCL/SDA 毛刺滤波器

  • 支持主机模式下的 General Call 和 NULL DATA 传输

  • 两个外设实例 I2c0 和 I2c1,均实现共享的 I2cInstance trait

  • 操作模式:

    • Blocking:轮询驱动

    • Async:中断驱动,基于 embassy waker

备注

驱动当前公开 API 尚未提供 DMA 传输和从机异步模式。中断驱动的主机传输可通过 I2c::into_async 获得。

工作模式

I2C 可配置两种工作模式:Blocking 模式和 Async 模式。

Blocking 模式

CPU 轮询 I2C 状态寄存器,按需读写 FIFO 缓冲区。这是 I2c::init(...).enable() 返回的默认模式,实现了 embedded_hal::i2c::I2c。

适合可以接受阻塞当前任务的简单、低频传输场景。

use embedded_hal::i2c::I2c as _;

use ameba_hal::i2c::{Config, I2c, I2c0};

use ameba_hal::{
    pinmux::{self, Pin, PinFunction, Pull},
    rcc,
};
...
rcc::enable(rcc::Peripheral::I2C0);
pinmux::set(Pin::PA26, PinFunction::I2C0_SDA);
pinmux::set(Pin::PA25, PinFunction::I2C0_SCL);
pinmux::set_pull(Pin::PA26, Pull::Up);
pinmux::set_pull(Pin::PA25, Pull::Up);

let mut i2c = unsafe {
    I2c::<I2c0, _>::steal()
        .init(Config::default())
        .enable()
};
...
match i2c.write(0x55u8, &[0x42u8]) {
    Err(_) => {
        println!("[PASS] I2C blocking: NACK OK");
    }
    Ok(()) => {
        println!("[FAIL] I2C blocking: unexpected ACK");
    }
}

完整示例见 examples/i2c/blocking/src/main.rs。

Async 模式

基于 Embassy waker 机制的中断驱动传输,在已 enable 的 blocking 实例上调用 into_async 获得。实现了 embedded_hal_async::i2c::I2c,传输进行期间当前 async 任务会让出执行权,而不是忙等。

use embassy_time::{Duration, Timer, with_timeout};
use embedded_hal_async::i2c::I2c as _;

use ameba_hal::Async;
use ameba_hal::i2c::{self, Config, I2c, I2c0};
...
ameba_hal::bind_interrupts!(struct Irqs {
    I2C0_IRQ => i2c::InterruptHandler<I2c0>;
});
...
async fn i2c_task(mut i2c: I2c<I2c0, i2c::Enabled, Async>) {
    // Phase 1: NACK error handling — write to address 0x55 (no device present).
    let result = with_timeout(Duration::from_millis(500), i2c.write(0x55u8, &[0x42u8])).await;
    match result {
        Ok(Err(_)) => println!("[PASS] I2C async: NACK OK"),
        Ok(Ok(())) => println!("[FAIL] I2C async: unexpected ACK"),
        Err(_) => println!("[FAIL] I2C async: timeout (>500ms)"),
    }
    ...
}
...
let i2c = unsafe {
    I2c::<I2c0, _>::steal().init(Config::default()).enable()
};
let i2c_async = i2c.into_async(Irqs);
...
spawner.spawn(i2c_task(i2c_async)).unwrap();

完整示例见 examples/i2c/async/src/main.rs。

应用示例

Rust SDK 在 examples/i2c/ 下提供两个示例项目:

  • i2c/blocking

    I2C0 主机,blocking 模式。向不存在的从机地址 0x55 写数据,验证驱动是否正确报告 NACK 错误。

    接线:SCL = PA25,SDA = PA26,需要外部或内部上拉。无需外接从机设备——示例故意向没有挂载任何设备的地址发送数据。

    [I2C BLK] start
    [PASS] I2C blocking: NACK OK
    
  • i2c/async

    I2C0 主机,async 模式。与 i2c/blocking 相同的 NACK 检测场景,通过 into_async 而非轮询驱动;随后连续发起 30 次写操作,同时由并发的心跳任务确认 executor 没有被阻塞。

    接线:与 i2c/blocking 相同。

    [I2C ASYNC] start
    [PASS] I2C async: NACK OK
    [I2C] concurrent: 30 writes start
    [HB] N
    ...
    [I2C] heartbeats seen: N
    [PASS] I2C async: non-blocking OK
    [HB] N
    ...
    

    最后一个 [PASS] 之后,心跳任务会持续打印 [HB] N。

备注

编译任意示例:cargo xtask build example --name i2c/<demo>。

API 参考

快速用法

use ameba_hal::i2c::{Config, I2c, I2c0};
use embedded_hal::i2c::I2c as _;

let mut i2c = unsafe {
    I2c::<I2c0, _>::steal()
        .init(Config::default())
        .enable()
};

i2c.write(0x55u8, &[0x42u8])?;
i2c.read(0x55u8, &mut [0u8; 4])?;

使用 into_async 转换为异步模式后,I2c 还实现了 embedded_hal_async::i2c::I2c,请参见上文 Async 模式一节。