refactor(uart): simplify driver architecture with ownership and trait-based APIs

This commit restructures the UART driver to use reference-based peripheral management instead of owned register blocks, introducing the UartExt trait for streamlined instance creation.

The Serial struct now operates on borrowed register blocks with lifetime tracking, reducing type complexity by eliminating redundant generic parameters.

Error messages for invalid pad connections are optimized to use standard TX/RX abbreviations and clearer phrasing. Peripheral release semantics are adjusted in free() to return only pads, reflecting the shift to non-owning register access.

Example code and HAL prelude are updated to leverage the new trait-based API, while macro expansions enable automatic UART instance implementations.

These changes improve type safety, reduce code duplication, and provide more idiomatic embedded-Rust interfaces.

Implement UartExt for UARTx or &'a mut UARTx. The former UARTx consumes and convert into &'static RegisterBlock, while &'a mut UARTx converts into &'a RegisterBlock.

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

Author: luojia65

allwinner-hal/src/lib.rs

@@ -21,6 +21,7 @@ pub mod uart;
 
 #[doc(hidden)]
 pub mod prelude {
+    pub use crate::uart::UartExt as _;
     pub use embedded_hal::{
         digital::{InputPin as _, OutputPin as _, StatefulOutputPin as _},
         spi::SpiBus as _,

allwinner-hal/src/uart.rs

@@ -81,23 +81,39 @@ impl core::ops::Deref for RegisterBlock {
     }
 }
 
+/// Extend constructor to owned UART register blocks.
+pub trait UartExt<'a, const I: usize> {
+    /// Creates a polling serial instance, without interrupt or DMA configurations.
+    fn serial<PADS>(
+        self,
+        pads: PADS,
+        config: impl Into<Config>,
+        clocks: &Clocks,
+        ccu: &ccu::RegisterBlock,
+    ) -> Serial<'a, PADS>
+    where
+        PADS: Pads<I>;
+}
+
 /// Managed serial structure with peripheral and pads.
-#[derive(Debug)]
-pub struct Serial<UART, const I: usize, PADS: Pads<I>> {
-    uart: UART,
+pub struct Serial<'a, PADS> {
+    uart: &'a RegisterBlock,
     pads: PADS,
 }
 
-impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Pads<I>> Serial<UART, I, PADS> {
+impl<'a, PADS> Serial<'a, PADS> {
     /// Create a serial instance.
     #[inline]
-    pub fn new(
-        uart: UART,
+    pub fn new<const I: usize>(
+        uart: &'a RegisterBlock,
         pads: PADS,
         config: impl Into<Config>,
         clocks: &Clocks,
         ccu: &ccu::RegisterBlock,
-    ) -> Self {
+    ) -> Self
+    where
+        PADS: Pads<I>,
+    {
         // 1. unwrap parameters
         let Config {
             baudrate,
@@ -111,8 +127,8 @@ impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Pads<I>> Serial<UART, I,
         unsafe { PADS::Clock::reset(ccu) };
         // 3. set interrupt configuration
         // on BT0 stage we disable all uart interrupts
-        let interrupt_types = uart.as_ref().ier().read();
-        uart.as_ref().ier().write(
+        let interrupt_types = uart.ier().read();
+        uart.ier().write(
             interrupt_types
                 .disable_ms()
                 .disable_rda()
@@ -121,7 +137,7 @@ impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Pads<I>> Serial<UART, I,
         );
         // 4. calculate and set baudrate
         let uart_clk = (clocks.apb1.0 + 8 * bps) / (16 * bps);
-        uart.as_ref().write_divisor(uart_clk as u16);
+        uart.write_divisor(uart_clk as u16);
         // 5. additional configurations
         let char_len = match wordlength {
             WordLength::Five => CharLen::FIVE,
@@ -135,8 +151,8 @@ impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Pads<I>> Serial<UART, I,
             Parity::Odd => PARITY::ODD,
             Parity::Even => PARITY::EVEN,
         };
-        let lcr = uart.as_ref().lcr().read();
-        uart.as_ref().lcr().write(
+        let lcr = uart.lcr().read();
+        uart.lcr().write(
             lcr.set_char_len(char_len)
                 .set_one_stop_bit(one_stop_bit)
                 .set_parity(parity),
@@ -154,22 +170,27 @@ impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Pads<I>> Serial<UART, I,
     }
     /// Close uart and release peripheral.
     #[inline]
-    pub fn free(self, ccu: &ccu::RegisterBlock) -> (UART, PADS) {
+    pub fn free<const I: usize>(self, ccu: &ccu::RegisterBlock) -> PADS
+    where
+        PADS: Pads<I>,
+    {
         // clock is closed for self.clock_gate is dropped
         unsafe { PADS::Clock::free(ccu) };
-        (self.uart, self.pads)
+        self.pads
     }
 }
 
-impl<UART: AsRef<RegisterBlock>, const I: usize, TX: Transmit<I>, RX: Receive<I>>
-    Serial<UART, I, (TX, RX)>
-{
+impl<'a, TX, RX> Serial<'a, (TX, RX)> {
     /// Split serial instance into transmit and receive halves.
     #[inline]
-    pub fn split(self) -> (TransmitHalf<UART, I, TX>, ReceiveHalf<UART, I, RX>) {
+    pub fn split<const I: usize>(self) -> (TransmitHalf<'a, TX>, ReceiveHalf<'a, RX>)
+    where
+        TX: Transmit<I>,
+        RX: Receive<I>,
+    {
         (
             TransmitHalf {
-                uart: unsafe { core::ptr::read_volatile(&self.uart) },
+                uart: self.uart,
                 _pads: self.pads.0,
             },
             ReceiveHalf {
@@ -181,16 +202,14 @@ impl<UART: AsRef<RegisterBlock>, const I: usize, TX: Transmit<I>, RX: Receive<I>
 }
 
 /// Transmit half from splitted serial structure.
-#[derive(Debug)]
-pub struct TransmitHalf<UART, const I: usize, PADS: Transmit<I>> {
-    uart: UART,
+pub struct TransmitHalf<'a, PADS> {
+    uart: &'a RegisterBlock,
     _pads: PADS,
 }
 
 /// Receive half from splitted serial structure.
-#[derive(Debug)]
-pub struct ReceiveHalf<UART, const I: usize, PADS: Receive<I>> {
-    uart: UART,
+pub struct ReceiveHalf<'a, PADS> {
+    uart: &'a RegisterBlock,
     _pads: PADS,
 }
 
@@ -200,9 +219,11 @@ pub trait Pads<const I: usize> {
 }
 
 /// Valid transmit pin for UART peripheral.
+#[diagnostic::on_unimplemented(message = "selected pad does not connect to UART{I} TX signal")]
 pub trait Transmit<const I: usize> {}
 
 /// Valid receive pin for UART peripheral.
+#[diagnostic::on_unimplemented(message = "selected pad does not connect to UART{I} RX signal")]
 pub trait Receive<const I: usize> {}
 
 #[inline]
@@ -251,67 +272,53 @@ where
     type Clock = ccu::UART<I>;
 }
 
-impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Pads<I>> embedded_io::ErrorType
-    for Serial<UART, I, PADS>
-{
+impl<'a, PADS> embedded_io::ErrorType for Serial<'a, PADS> {
     type Error = core::convert::Infallible;
 }
 
-impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Transmit<I>> embedded_io::ErrorType
-    for TransmitHalf<UART, I, PADS>
-{
+impl<'a, PADS> embedded_io::ErrorType for TransmitHalf<'a, PADS> {
     type Error = core::convert::Infallible;
 }
 
-impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Receive<I>> embedded_io::ErrorType
-    for ReceiveHalf<UART, I, PADS>
-{
+impl<'a, PADS> embedded_io::ErrorType for ReceiveHalf<'a, PADS> {
     type Error = core::convert::Infallible;
 }
 
-impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Pads<I>> embedded_io::Write
-    for Serial<UART, I, PADS>
-{
+impl<'a, PADS> embedded_io::Write for Serial<'a, PADS> {
     #[inline]
     fn write(&mut self, buffer: &[u8]) -> Result<usize, Self::Error> {
-        uart_write_blocking(self.uart.as_ref(), buffer)
+        uart_write_blocking(self.uart, buffer)
     }
 
     #[inline]
     fn flush(&mut self) -> Result<(), Self::Error> {
-        uart_flush_blocking(self.uart.as_ref())
+        uart_flush_blocking(self.uart)
     }
 }
 
-impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Transmit<I>> embedded_io::Write
-    for TransmitHalf<UART, I, PADS>
-{
+impl<'a, PADS> embedded_io::Write for TransmitHalf<'a, PADS> {
     #[inline]
     fn write(&mut self, buffer: &[u8]) -> Result<usize, Self::Error> {
-        uart_write_blocking(self.uart.as_ref(), buffer)
+        uart_write_blocking(self.uart, buffer)
     }
 
     #[inline]
     fn flush(&mut self) -> Result<(), Self::Error> {
-        uart_flush_blocking(self.uart.as_ref())
+        uart_flush_blocking(self.uart)
     }
 }
 
-impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Pads<I>> embedded_io::Read
-    for Serial<UART, I, PADS>
-{
+impl<'a, PADS> embedded_io::Read for Serial<'a, PADS> {
     #[inline]
     fn read(&mut self, buffer: &mut [u8]) -> Result<usize, Self::Error> {
-        uart_read_blocking(self.uart.as_ref(), buffer)
+        uart_read_blocking(self.uart, buffer)
     }
 }
 
-impl<UART: AsRef<RegisterBlock>, const I: usize, PADS: Receive<I>> embedded_io::Read
-    for ReceiveHalf<UART, I, PADS>
-{
+impl<'a, PADS> embedded_io::Read for ReceiveHalf<'a, PADS> {
     #[inline]
     fn read(&mut self, buffer: &mut [u8]) -> Result<usize, Self::Error> {
-        uart_read_blocking(self.uart.as_ref(), buffer)
+        uart_read_blocking(self.uart, buffer)
     }
 }
 

allwinner-rt/examples/fn-main.rs

@@ -5,7 +5,7 @@
 
 #![no_std]
 #![no_main]
-use allwinner_hal::uart::{Config, Serial};
+use allwinner_hal::{prelude::*, uart::Config};
 use allwinner_rt::{Clocks, Peripherals, entry};
 use embedded_hal::digital::{InputPin, OutputPin};
 
@@ -19,7 +19,7 @@ fn main(p: Peripherals, c: Clocks) {
 
     let tx = p.gpio.pb8.into_function::<7>();
     let rx = p.gpio.pb9.into_function::<7>();
-    let mut serial = Serial::new(p.uart0, (tx, rx), Config::default(), &c, &p.ccu);
+    let mut serial = p.uart0.serial((tx, rx), Config::default(), &c, &p.ccu);
 
     let _borrow_input_high = serial.pads(|(_, rx)| rx.with_input(|pad| pad.is_high()));
 }

allwinner-rt/src/macros.rs

@@ -2,8 +2,7 @@ macro_rules! soc {
     (
         $(
             $(#[$doc:meta])*
-            pub struct $Ty:ident => $paddr:expr_2021
-            $(, $DerefTy:ty)+ ;
+            pub struct $Ty:ident => $paddr:expr_2021, $DerefTy:ty;
         )+
     ) => {
         $(
@@ -12,24 +11,64 @@ macro_rules! soc {
             pub struct $Ty {
                 _private: (),
             }
+            impl $Ty {
+                #[inline]
+                pub const fn ptr() -> *const $DerefTy {
+                    $paddr as *const _
+                }
+            }
 
-            $(
-                impl core::ops::Deref for $Ty {
-                    type Target = $DerefTy;
+            impl core::ops::Deref for $Ty {
+                type Target = $DerefTy;
+                #[inline(always)]
+                fn deref(&self) -> &Self::Target {
+                    unsafe { &*($paddr as *const _) }
+                }
+            }
+            impl core::convert::AsRef<$DerefTy> for $Ty {
+                #[inline(always)]
+                fn as_ref(&self) -> &$DerefTy {
+                    unsafe { &*($paddr as *const _) }
+                }
+            }
+        )+
+    };
+}
 
-                    #[inline(always)]
-                    fn deref(&self) -> &Self::Target {
-                        unsafe { &*($paddr as *const _) }
-                    }
+macro_rules! impl_uart {
+    ($($i:expr => $UARTi:ident,)+) => {
+        $(
+            impl<'a> UartExt<'a, $i> for &'a mut $UARTi {
+                fn serial<PADS>(
+                    self,
+                    pads: PADS,
+                    config: impl Into<allwinner_hal::uart::Config>,
+                    clocks: &Clocks,
+                    ccu: &allwinner_hal::ccu::RegisterBlock,
+                ) -> allwinner_hal::uart::Serial<'a, PADS>
+                where
+                    PADS: allwinner_hal::uart::Pads<$i>,
+                {
+                    allwinner_hal::uart::Serial::new(self, pads, config, clocks, ccu)
                 }
+            }
 
-                impl core::convert::AsRef<$DerefTy> for $Ty {
-                    #[inline(always)]
-                    fn as_ref(&self) -> &$DerefTy {
-                        unsafe { &*($paddr as *const _) }
-                    }
+            impl UartExt<'static, $i> for $UARTi {
+                fn serial<PADS>(
+                    self,
+                    pads: PADS,
+                    config: impl Into<allwinner_hal::uart::Config>,
+                    clocks: &Clocks,
+                    ccu: &allwinner_hal::ccu::RegisterBlock,
+                ) -> allwinner_hal::uart::Serial<'static, PADS>
+                where
+                    PADS: allwinner_hal::uart::Pads<$i>,
+                {
+                    let uart = unsafe { &*$UARTi::ptr() };
+                    allwinner_hal::uart::Serial::new(uart, pads, config, clocks, ccu)
                 }
-            )+
+            }
+
         )+
     };
 }

allwinner-rt/src/soc/d1.rs

@@ -1,6 +1,6 @@
 //! D1-H, D1s, F133, F133A/B chip platforms.
 
-use allwinner_hal::{ccu::Clocks, gpio::Disabled, wafer::d1::Pads};
+use allwinner_hal::{ccu::Clocks, gpio::Disabled, uart::UartExt, wafer::d1::Pads};
 use embedded_time::rate::Extensions;
 
 /// ROM runtime peripheral ownership and configurations.
@@ -50,6 +50,10 @@ soc! {
     pub struct PLIC => 0x10000000, plic::Plic;
 }
 
+impl_uart! {
+    0 => UART0,
+}
+
 #[doc(hidden)]
 #[inline]
 pub fn __rom_init_params() -> (Peripherals<'static>, Clocks) {

examples/nezha-d1/src/bin/uart.rs

@@ -1,7 +1,7 @@
 #![no_std]
 #![no_main]
 
-use allwinner_hal::uart::{Config, Serial};
+use allwinner_hal::{prelude::*, uart::Config};
 use allwinner_rt::{Clocks, Peripherals, entry};
 use embedded_io::{Read, Write};
 use panic_halt as _;
@@ -10,7 +10,7 @@ use panic_halt as _;
 fn main(p: Peripherals, c: Clocks) {
     let tx = p.gpio.pb8.into_function::<6>();
     let rx = p.gpio.pb9.into_function::<6>();
-    let mut serial = Serial::new(p.uart0, (tx, rx), Config::default(), &c, &p.ccu);
+    let mut serial = p.uart0.serial((tx, rx), Config::default(), &c, &p.ccu);
 
     writeln!(serial, "Hello World!").ok();
 

examples/sdmmc/src/main.rs

@@ -2,8 +2,9 @@
 #![no_main]
 
 use allwinner_hal::{
+    prelude::*,
     smhc::{SdCard, Smhc},
-    uart::{Config, Serial},
+    uart::Config,
 };
 use allwinner_rt::{Clocks, Peripherals, entry};
 use embedded_io::Write;
@@ -23,7 +24,7 @@ impl embedded_sdmmc::TimeSource for MyTimeSource {
 fn main(p: Peripherals, c: Clocks) {
     let tx = p.gpio.pb8.into_function::<6>();
     let rx = p.gpio.pb9.into_function::<6>();
-    let mut serial = Serial::new(p.uart0, (tx, rx), Config::default(), &c, &p.ccu);
+    let mut serial = p.uart0.serial((tx, rx), Config::default(), &c, &p.ccu);
 
     writeln!(serial, "Hello World!").ok();