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,均实现共享的 SpiInstance trait

  • 操作模式:

    • Blocking:轮询驱动

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

    • DMA 异步:基于 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/ 下提供了四个示例项目:

  • spi/blocking

    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
    
  • spi/async

    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。

  • spi/dma

    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
    
  • spi/interrupt

    主循环阻塞发送 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 传输能力——参见上文工作模式一节。