UART
概述
RTL8721F 最多提供四个 UART 外设,用于异步串行通信。Rust 驱动 ameba_hal::uart 直接封装 PAC 寄存器块,不涉及裸位操作或 C FFI 调用。
功能特性
最多四个外设实例
Uart0到Uart3,均实现共享的UartInstancetrait可配置波特率,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::WriteAsync:基于
embassywaker 的中断驱动,实现embedded_io_async::Read/embedded_io_async::WriteDMA:通过
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/ 下提供四个示例项目:
-
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
-
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。 -
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
-
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 传输能力——参见上文工作模式一节。