UART

概述

RTL8721F 最多提供四个 UART 外设,用于异步串行通信。Rust 驱动 ameba_hal::uart 直接封装 PAC 寄存器块,不涉及裸位操作或 C FFI 调用。

功能特性

  • 最多四个外设实例 Uart0 到 Uart3,均实现共享的 UartInstance trait

  • 可配置波特率,7 位或 8 位数据位(DataBits::_7 / DataBits::_8),无/奇/偶校验(Parity::None / Parity::Odd / Parity::Even),以及 1 位或 2 位停止位(StopBits::One / StopBits::Two)

  • 可选 RTS/CTS 硬件流控,通过 FlowControl::RtsCts 设置

  • 通过 loopback_cmd 开启内部硬件 loopback,所有内置示例都用它来避免外部接线

  • 通过 rts_force_cmd 强制 RTS 输出,独立于自动流控路径

  • 通过 rx_to_thres_config / rx_reti_thres_config 配置 Rx 超时和 Rx FIFO 空闲超时阈值

  • 通过 rx_debounce_config / rx_debounce_cmd 配置 Rx 去抖滤波

  • 通过 irda_init / irda_cmd 提供带脉冲偏移和 Rx 滤波配置的 IrDA SIR 接口

  • 通过 monitor_para_config / lp_rx_baud_set / rx_monitor_cmd 提供 LP Rx 波特率监测,用于自动检测对端波特率

  • 通过 register_irq / UartIrqHandler 注册裸中断回调,独立于 async waker 路径

  • 操作模式:

    • Blocking:轮询驱动,实现 embedded_io::Read / embedded_io::Write

    • Async:基于 embassy waker 的中断驱动,实现 embedded_io_async::Read / embedded_io_async::Write

    • DMA:通过 into_dma_async 实现 GDMA 传输,使用两个 DmaChannel 实例分别用于 TX 和 RX

备注

驱动当前公开 API 尚未提供从机模式的异步操作。GDMA 传输需要单独从 DMA 驱动获取一对 DmaChannel 句柄。

工作模式

UART 可配置四种工作模式:Blocking 模式、Async 模式、DMA 模式和 Interrupt 模式。

Blocking 模式

CPU 轮询 UART 状态寄存器,按需读写 FIFO 缓冲区。这是 Uart::steal() 返回的默认模式,实现了 embedded_io::Read / embedded_io::Write。

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

use embedded_io::{Read, Write};
...
use ameba_hal::uart::{Uart, Uart0, UartConfig};
...
let mut uart = unsafe { Uart::<Uart0>::steal() };
uart.init(&UartConfig::default());
uart.loopback_cmd(true);
...
let _ = uart.write(&tx);

// Drain RX loopback bytes - blocks on first byte, then reads available
let mut rx = [0u8; 4];
let mut got = 0usize;
while got < 4 {
    match uart.read(&mut rx[got..]) {
        Ok(n) => got += n,
        Err(_) => break,
    }
}

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

Async 模式

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

use ameba_hal::Async;
use ameba_hal::uart::{InterruptHandler, Uart, Uart0, UartConfig};
...
ameba_hal::bind_interrupts!(struct Irqs {
    UART0_IRQ => InterruptHandler<Uart0>;
});
...
let uart = unsafe { Uart::<Uart0>::steal() };
uart.init(&UartConfig::default());
uart.loopback_cmd(true);

let uart_async = uart.into_async(Irqs);
...
let _ = uart.write(&tx).await;
...
let result = embassy_time::with_timeout(
    Duration::from_millis(500),
    uart.read(&mut rx),
).await;

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

DMA 模式

GDMA 传输,在已 enable 的 blocking 实例上调用 into_dma_async 并传入一对用于 TX 和 RX 的 DmaChannel 句柄获得。适合大块数据传输,因为 CPU 只需设置传输参数并等待完成,而不必逐字节操作 FIFO。

use ameba_hal::dma::{Blocking, DmaChannel};
use ameba_hal::uart::{Uart, Uart0, UartConfig, UartDma};
...
let uart = unsafe { Uart::<Uart0>::steal() };
uart.init(&UartConfig::default());
uart.loopback_cmd(true);

// into_dma_async configures FCR DMA mode, burst sizes, and enables NVIC IRQs.
let mut uart_dma: UartDma<Uart0, 0, 1> = uart.into_dma_async(
    unsafe { DmaChannel::<0, Blocking>::steal() },
    unsafe { DmaChannel::<1, Blocking>::steal() },
);
...
match embassy_time::with_timeout(
    Duration::from_millis(500),
    uart_dma.dma_transfer(tx_slice, rx_slice),
).await {
    Ok(()) => {
        println!("[UART DMA] transfer done");
    }
    Err(_) => {
        println!("[FAIL] UART DMA: timeout");
        loop { Timer::after(Duration::from_secs(1)).await; }
    }
}

完整示例见 examples/uart/dma/src/main.rs。UartDma 还提供 dma_write / dma_read 用于单方向传输。

Interrupt 模式

用户注册的裸 ISR 回调,在 blocking 实例上调用 register_irq 获得。与 Async 模式不同,回调通过 UartIrqHandler trait 直接在 UART 的 NVIC 中断上下文中运行,独立于 Embassy waker/executor 路径,适合主循环只发送、所有接收都交给 ISR 处理的场景。

use core::ptr::addr_of_mut;
use core::sync::atomic::{AtomicU32, Ordering};
...
use ameba_hal::uart::{
    InterruptHandler, UART0_PTR, Uart, Uart0, UartConfig, UartIrqEvent, UartIrqHandler, read_available,
};
...
ameba_hal::bind_interrupts!(struct Irqs {
    UART0_IRQ => InterruptHandler<Uart0>;
});

struct RxCounter {
    bytes: AtomicU32,
}

impl UartIrqHandler for RxCounter {
    fn on_irq(&mut self, event: UartIrqEvent) {
        if event.rx_error {
            println!("[UART-IRQ] rx error lsr=0x{:04X} (from ISR)", event.lsr);
            return;
        }
        let mut buf = [0u8; 16];
        let n = unsafe { read_available(UART0_PTR, &mut buf) };
        self.bytes.fetch_add(n as u32, Ordering::Relaxed);
        println!("[UART-IRQ] rx {} byte(s): {:02X?} (from ISR)", n, &buf[..n]);
    }
}

static mut RX_COUNTER: RxCounter = RxCounter { bytes: AtomicU32::new(0) };
...
let mut uart = unsafe { Uart::<Uart0>::steal() };
uart.init(&UartConfig::default());
uart.loopback_cmd(true);

let handler = unsafe { &mut *addr_of_mut!(RX_COUNTER) };
uart.register_irq(handler, Irqs);

完整示例见 examples/uart/interrupt/src/main.rs。

应用示例

Rust SDK 在 examples/uart/ 下提供四个示例项目:

  • uart/blocking

    UART0,blocking 模式,内部硬件 loopback。发送 3 轮 4 字节数据,blocking 读回并对比。

    接线:无需外接线,使用 UART0 内部 loopback(loopback_cmd(true))。

    [UART BLK] start
    [UART BLK] round 1 sent:[41424301] recv:[41424301]
    [UART BLK] round 2 sent:[42434402] recv:[42434402]
    [UART BLK] round 3 sent:[43444503] recv:[43444503]
    [PASS] UART blocking: OK
    
  • uart/async

    UART0,async 模式,内部硬件 loopback。Phase 1 运行 3 轮 4 字节回环,超时 500 ms。Phase 2 发送 256 字节的同时运行并发心跳任务,验证 executor 未被阻塞。

    接线:无需外接线,使用 UART0 内部 loopback。

    [UART ASYNC] start
    [UART ASYNC] round 1 tx=[41 42 43 01] rx=[41 42 43 01] OK
    ...
    [PASS] UART async: echo OK
    [UART] concurrent: 256B write start
    [UART] heartbeats seen: N
    [PASS] UART async: non-blocking write OK
    [HB] N
    ...
    

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

  • uart/dma

    UART0,DMA 模式,内部硬件 loopback。通过 GDMA 通道 0(TX)和通道 1(RX)并发传输 256 字节,完成后校验接收数据与发送数据一致。

    接线:无需外接线,使用 UART0 内部 loopback。

    [UART DMA] start
    [UART DMA] transfer done
    [PASS] UART DMA: 256 bytes loopback OK
    
  • uart/interrupt

    UART0,内部硬件 loopback。通过 register_irq 注册裸 ISR 回调,直接在中断上下文中读取并打印 Rx FIFO 数据,独立于 uart/async 所用的 async waker 路径。主循环 blocking 发送 5 轮 4 字节,所有接收都在 ISR 中完成。

    接线:无需外接线,使用 UART0 内部 loopback。

    [UART interrupt] start
    [UART] [1] sent [41, 42, 43, 01]
    [UART-IRQ] rx 1 byte(s): [41] (from ISR)
    [UART-IRQ] rx 3 byte(s): [42, 43, 01] (from ISR)
    ...
    [PASS] UART interrupt: 20 bytes echoed via ISR OK
    

    每轮的 4 个字节不一定在一次 ISR 中收完,可能分成多行 [UART-IRQ] 打印,每次运行的拆分方式可能与上面不同。

备注

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

API 参考

快速用法

use ameba_hal::uart::{Uart, Uart0, UartConfig};
use embedded_io::{Read, Write};

let mut uart = unsafe { Uart::<Uart0>::steal() };
uart.init(&UartConfig::default());

let _ = uart.write(&[0x42u8]);
let mut rx = [0u8; 4];
let _ = uart.read(&mut rx);

使用 into_async 转换后,Uart 还实现了 embedded_io_async::Read / embedded_io_async::Write,并可通过 into_dma_async 获得 DMA 传输能力——参见上文工作模式一节。