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,均实现共享的I2cInstancetrait操作模式:
Blocking:轮询驱动
Async:中断驱动,基于
embassywaker
备注
驱动当前公开 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/ 下提供两个示例项目:
-
I2C0 主机,blocking 模式。向不存在的从机地址
0x55写数据,验证驱动是否正确报告 NACK 错误。接线:SCL = PA25,SDA = PA26,需要外部或内部上拉。无需外接从机设备——示例故意向没有挂载任何设备的地址发送数据。
[I2C BLK] start [PASS] I2C blocking: NACK OK
-
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 模式一节。