SPI
概述
RTL8721F 提供 SPI 接口,是一种支持全双工传输的同步串行总线,支持主机和从机角色。Rust 驱动 ameba_hal::spi 直接封装 PAC 寄存器块,不涉及裸位操作或 C FFI 调用。
功能特性
Motorola SPI 帧格式,通过
FrameFormat::MotorolaSpi设置,数据帧长度可通过FrameSize配置为 4 到 16 位主机或从机角色,通过
Role::Master/Role::Slave设置,需在init之前调用Spi::set_role可配置时钟相位与极性,通过
ClkPhase/ClkPolarity设置,传输方向通过TransferMode::TransmitReceive/TransmitOnly/ReceiveOnly设置可通过
Config配置 RX/TX FIFO 阈值、DMA 突发级别、从机选择信号切换行为,以及 TX/RX 字节或位交换两个外设实例
Spi0和Spi1,均实现共享的SpiInstancetrait操作模式:
Blocking:轮询驱动
Async:中断驱动,基于
embassywakerDMA 异步:基于 GDMA 驱动的传输,通过
SpiDma实现裸 ISR 回调:用户通过
Spi::register_irq注册处理函数,独立于 async/waker 路径
备注
异步从机模式可通过 Spi::into_async_slave 获得,返回一个独立的 SpiSlaveAsync 句柄。
工作模式
SPI 支持五种操作模式:Blocking Mode、Async Mode、Async Slave Mode、DMA Mode 和 Interrupt Mode。
Blocking Mode
CPU 轮询 SPI 状态寄存器,按需读写 FIFO 缓冲区。这是 Spi::steal() 返回的默认模式,实现了 embedded_hal::spi::SpiBus。角色必须在 init 之前通过 set_role 设置,因为外设上电后默认为从机。
use ameba_hal::spi::{Role, Spi, Spi0, SpiConfig};
use ameba_hal::{
pinmux::{self, Pin, PinFunction, Pull},
rcc,
};
...
rcc::enable(rcc::Peripheral::SPI0);
pinmux::set(Pin::PA7, PinFunction::SPI0);
pinmux::set(Pin::PA8, PinFunction::SPI0);
pinmux::set(Pin::PA9, PinFunction::SPI0);
pinmux::set(Pin::PA10, PinFunction::SPI0);
pinmux::set_pull(Pin::PA10, Pull::Up);
let spi = unsafe { Spi::<Spi0>::steal() };
// Set master role BEFORE init (default power-on is slave).
spi.set_role(Role::Master);
let cfg = SpiConfig::default();
spi.init(&cfg);
spi.set_slave_enable(0);
...
let tx: [u8; 16] = [
0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10,
];
let mut rx = [0u8; 16];
// Write all bytes to TX FIFO (< 64 entries, no overflow risk).
for &b in tx.iter() {
spi.write_data(b as u32);
}
// Wait until TX FIFO drains and peripheral is idle.
while spi.is_busy() {}
完整示例见 examples/spi/blocking/src/main.rs。
Async Mode
基于 Embassy waker 机制的中断驱动主机传输,通过在已启用的 blocking 实例上调用 into_async 获得。实现了 embedded_hal_async::spi::SpiBus,同时也直接暴露 write_async / read_async / transfer_async / transfer_in_place_async / flush_async。
use ameba_hal::spi::{InterruptHandler, Role, Spi, Spi0, SpiConfig};
use ameba_hal::{Async, Config};
use ameba_hal::{
pinmux::{self, Pin, PinFunction, Pull},
rcc,
};
...
ameba_hal::bind_interrupts!(struct Irqs {
SPI0_IRQ => InterruptHandler<Spi0>;
});
...
rcc::enable(rcc::Peripheral::SPI0);
pinmux::set(Pin::PA7, PinFunction::SPI0);
pinmux::set(Pin::PA8, PinFunction::SPI0);
pinmux::set(Pin::PA9, PinFunction::SPI0);
pinmux::set(Pin::PA10, PinFunction::SPI0);
pinmux::set_pull(Pin::PA10, Pull::Up);
let spi = unsafe { Spi::<Spi0>::steal() };
spi.set_role(Role::Master);
...
spi.init(&cfg);
spi.set_slave_enable(0);
...
let mut spi_async: Spi<Spi0, Async> = spi.into_async(Irqs);
...
let tx: [u8; 16] = [
0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10,
];
let mut rx = [0u8; 16];
...
spi_async.transfer_async(&mut rx, &tx).await;
完整示例见 examples/spi/async/src/main.rs。
Async Slave Mode
全双工从机传输,通过在已用 set_role(Role::Slave) 和 init 配置好的 blocking 实例上调用 into_async_slave 获得。返回的是独立的 SpiSlaveAsync 句柄,而不经过 SpiBus,因为从机不驱动时钟,只暴露单一的 transfer_async 方法,在主机把约定帧数全部发送完毕后完成。
use ameba_hal::spi::{InterruptHandler, Role, Spi, Spi0, SpiConfig, SpiSlaveAsync};
use ameba_hal::{
pinmux::{self, Pin, PinFunction, Pull},
rcc,
};
...
ameba_hal::bind_interrupts!(struct Irqs {
SPI0_IRQ => InterruptHandler<Spi0>;
});
...
rcc::enable(rcc::Peripheral::SPI0);
pinmux::set(Pin::PA7, PinFunction::SPI0);
pinmux::set(Pin::PA8, PinFunction::SPI0);
pinmux::set(Pin::PA9, PinFunction::SPI0);
pinmux::set(Pin::PA10, PinFunction::SPI0);
pinmux::set_pull(Pin::PA10, Pull::Up);
let spi = unsafe { Spi::<Spi0>::steal() };
spi.set_role(Role::Slave);
let cfg = SpiConfig { role: Role::Slave, ..SpiConfig::default() };
spi.init(&cfg);
while spi.is_rx_not_empty() { let _ = spi.read_data(); }
let mut slave: SpiSlaveAsync<Spi0> = spi.into_async_slave(Irqs);
...
let mut tx = [0u8; LEN];
for (i, b) in tx.iter_mut().enumerate() {
*b = 0xA0u8 + i as u8; // [0xA0..0xAF]
}
let mut rx = [0u8; LEN];
// Preload `tx` onto MISO, wait for the master to clock LEN frames,
// receive the master's data into `rx`.
slave.transfer_async(&tx, &mut rx).await;
完整示例见 examples/board2board/spi-slave/src/main.rs``(``examples/spi/ 下只有单板 loopback 示例,从机角色的真实实现在这里)。
DMA Mode
GDMA 传输,通过在已启用的 blocking 实例上调用 into_dma_async 并传入一对用于 TX 和 RX 的 DmaChannel 句柄获得。适合大缓冲区场景,因为 CPU 只需设置好传输并等待完成,而不必逐帧操作 FIFO。
use ameba_hal::dma::{Blocking, DmaChannel};
use ameba_hal::spi::{Role, Spi, Spi0, SpiConfig, SpiDma};
use ameba_hal::{
pinmux::{self, Pin, PinFunction, Pull},
rcc,
};
...
rcc::enable(rcc::Peripheral::SPI0);
pinmux::set(Pin::PA7, PinFunction::SPI0);
pinmux::set(Pin::PA8, PinFunction::SPI0);
pinmux::set(Pin::PA9, PinFunction::SPI0);
pinmux::set(Pin::PA10, PinFunction::SPI0);
pinmux::set_pull(Pin::PA10, Pull::Up);
let spi = unsafe { Spi::<Spi0>::steal() };
spi.set_role(Role::Master);
spi.init(&SpiConfig::default());
spi.set_slave_enable(0);
// into_dma_async takes ownership of both DMA channels, selects HS IDs, enables NVIC.
let mut spi_dma: SpiDma<Spi0, 0, 1> = spi.into_dma_async(
unsafe { DmaChannel::<0, Blocking>::steal() },
unsafe { DmaChannel::<1, Blocking>::steal() },
);
...
let tx_slice = unsafe { core::slice::from_raw_parts(tx_ptr as *const u8, BUF_SIZE) };
let rx_slice = unsafe { core::slice::from_raw_parts_mut(rx_ptr, BUF_SIZE) };
match embassy_time::with_timeout(
Duration::from_millis(500),
spi_dma.transfer_async(rx_slice, tx_slice),
).await {
Ok(()) => { ... }
Err(_) => { ... }
}
完整示例见 examples/spi/dma/src/main.rs。
Interrupt Mode
主机模式下用户注册的裸中断回调,通过在 blocking 实例上调用 register_irq 获得。回调通过 SpiIrqHandler trait 直接运行在 SPI 的 NVIC 中断上下文中,独立于 Embassy waker/executor 路径,适合主循环只负责发送、所有接收都交由 ISR 处理的场景。
use core::ptr::addr_of_mut;
use core::sync::atomic::{AtomicU32, Ordering};
...
use ameba_hal::pinmux::{self, Pin, PinFunction, Pull};
use ameba_hal::println;
use ameba_hal::rcc;
use ameba_hal::spi::{
InterruptHandler, Role, Spi, Spi0, SpiConfig, SpiInstance, SpiIrqEvent, SpiIrqHandler,
read_available,
};
...
ameba_hal::bind_interrupts!(struct Irqs {
SPI0_IRQ => InterruptHandler<Spi0>;
});
struct RxCounter {
bytes: AtomicU32,
}
impl SpiIrqHandler for RxCounter {
fn on_irq(&mut self, event: SpiIrqEvent) {
if event.error {
println!("[SPI-IRQ] error isr=0x{:08X} (from ISR)", event.isr);
return;
}
let mut buf = [0u8; 16];
let n = unsafe { read_available(Spi0::PTR, &mut buf) };
self.bytes.fetch_add(n as u32, Ordering::Relaxed);
println!("[SPI-IRQ] rx {} byte(s): {:02X?} (from ISR)", n, &buf[..n]);
}
}
static mut RX_COUNTER: RxCounter = RxCounter { bytes: AtomicU32::new(0) };
...
rcc::enable(rcc::Peripheral::SPI0);
pinmux::set(Pin::PA7, PinFunction::SPI0);
pinmux::set(Pin::PA8, PinFunction::SPI0);
pinmux::set(Pin::PA9, PinFunction::SPI0);
pinmux::set(Pin::PA10, PinFunction::SPI0);
pinmux::set_pull(Pin::PA10, Pull::Up);
let spi = unsafe { Spi::<Spi0>::steal() };
// Set master role BEFORE init (default power-on is slave).
spi.set_role(Role::Master);
let cfg = SpiConfig::default();
spi.init(&cfg);
spi.set_slave_enable(0);
// Drain any stale RX FIFO data before registering the callback.
while spi.is_rx_not_empty() {
let _ = spi.read_data();
}
while spi.is_busy() {}
let handler = unsafe { &mut *addr_of_mut!(RX_COUNTER) };
spi.register_irq(handler, Irqs);
完整示例见 examples/spi/interrupt/src/main.rs。
应用示例
Rust SDK 在 examples/spi/ 下提供了四个示例项目:
-
Master 模式,向 TX FIFO 写入 16 字节(0x01-0x10),经 MOSI-MISO 回环后读回对比。
接线:SPI0 —— CLK=PA7,MOSI=PA8,MISO=PA9,CS=PA10。需要 MOSI ↔ MISO 跳线短接。
[SPI BLK] start [PASS] SPI blocking: OK
-
Master 模式,时钟约 10 kHz,传输 16 字节,同时运行每 5 ms 一次的 heartbeat 任务,验证传输期间 executor 未被阻塞且回环数据正确。
接线:SPI0 —— CLK=PA7,MOSI=PA8,MISO=PA9,CS=PA10。需要 MOSI ↔ MISO 跳线短接。
[SPI async] start [HB] 1 [HB] 2 ... [SPI] heartbeats during transfer: N [PASS] SPI async: loopback + non-blocking OK [HB] N ...
最后一个
[PASS]之后,心跳任务会持续打印[HB] N。 -
Master 模式,通过 GDMA 通道 0(TX)和通道 1(RX)传输 1024 字节回环数据,传输完成后比对数据。
接线:SPI0 —— CLK=PA7,MOSI=PA8,MISO=PA9,CS=PA10。需要 MOSI ↔ MISO 跳线短接。
[SPI DMA] start [SPI DMA] transfer done [PASS] SPI DMA: 1024 bytes loopback OK
-
主循环阻塞发送 5 轮 × 4 字节,每轮间隔 50 ms,接收全部由通过
register_irq/SpiIrqHandler注册的裸 ISR 回调在中断上下文中直接完成打印,独立于spi/async所走的 waker/executor 调度路径。接线:SPI0 —— CLK=PA7,MOSI=PA8,MISO=PA9,CS=PA10。需要 MOSI ↔ MISO 跳线短接。
[SPI interrupt] start ... [SPI] [2] sent [42, 43, 44, 02] [SPI-IRQ] rx 3 byte(s): [42, 43, 44] (from ISR) [SPI-IRQ] rx 1 byte(s): [02] (from ISR) ... [PASS] SPI interrupt: 20 bytes echoed via ISR OK
每轮收到的字节可能分成多行
[SPI-IRQ]打印,[SPI-IRQ]行也可能先于对应的[SPI] [n] sent行出现,所以顺序和拆分方式每次运行可能不同。
备注
编译任意示例:cargo xtask build example --name spi/<demo>。
API 参考
快速用法
use ameba_hal::spi::{Role, Spi, Spi0, SpiConfig};
use embedded_hal::spi::SpiBus;
let spi = unsafe { Spi::<Spi0>::steal() };
spi.set_role(Role::Master);
spi.init(&SpiConfig::default());
spi.set_slave_enable(0);
let mut spi = spi;
let tx = [0x01u8, 0x02, 0x03, 0x04];
let mut rx = [0u8; 4];
let _ = spi.transfer(&mut rx, &tx);
使用 into_async 转换后,Spi 还实现了 embedded_hal_async::spi::SpiBus,并可通过 into_dma_async 获得 DMA 传输能力——参见上文工作模式一节。