diff --git a/libs/cramium-hal/src/udma.rs b/libs/cramium-hal/src/udma.rs index c1b658c33..376dcf167 100644 --- a/libs/cramium-hal/src/udma.rs +++ b/libs/cramium-hal/src/udma.rs @@ -312,7 +312,7 @@ impl Into for Bank { /// Crate-local struct that defines the offset of registers in UDMA banks, as words. #[repr(usize)] -enum DmaReg { +pub enum DmaReg { Saddr = 0, Size = 1, Cfg = 2, @@ -371,15 +371,18 @@ enum UartReg { Status = 0, Setup = 1, } - -pub enum UartChannel { - Uart0, - Uart1, - Uart2, - Uart3, +impl Into for UartReg { + fn into(self) -> usize { self as usize } } -impl Into for UartReg { +#[repr(usize)] +pub enum UartChannel { + Uart0 = 0, + Uart1 = 1, + Uart2 = 2, + Uart3 = 3, +} +impl Into for UartChannel { fn into(self) -> usize { self as usize } } @@ -402,6 +405,7 @@ impl Udma for Uart { const UART_TX_BUF_SIZE: usize = 2048; const UART_RX_BUF_START: usize = UART_TX_BUF_SIZE; const UART_RX_BUF_SIZE: usize = 2048; +const RX_BUF_DEPTH: usize = 1; impl Uart { /// Configures for N81 /// @@ -586,6 +590,189 @@ impl Uart { } } } + + /// Call this to read one character on receiving an interrupt. + /// + /// Note that if the interrupt is not handled fast enough, characters are simply dropped. + /// + /// Returns actual number of bytes read (0 or 1). + pub fn read_async(&mut self, c: &mut u8) -> usize { + let bank_addr = unsafe { self.csr().base().add(Bank::Rx as usize) }; + // retrieve total bytes available + let pending = unsafe { bank_addr.add(DmaReg::Size.into()).read_volatile() } as usize; + + // recover the pending byte. Hard-coded for case of RX_BUF_DEPTH == 1 + assert!(RX_BUF_DEPTH == 1, "Need to refactor buf recovery code if RX_BUF_DEPTH > 1"); + #[cfg(feature = "std")] + { + *c = self.ifram.as_slice::()[UART_RX_BUF_START]; + } + #[cfg(not(feature = "std"))] + unsafe { + *c = self.ifram.as_phys_slice::()[UART_RX_BUF_START]; + } + + // queue the next round + #[cfg(feature = "std")] + unsafe { + self.udma_enqueue( + Bank::Rx, + &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + RX_BUF_DEPTH], + CFG_EN | CFG_CONT, + ); + } + #[cfg(not(feature = "std"))] + unsafe { + self.udma_enqueue( + Bank::Rx, + &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + RX_BUF_DEPTH], + CFG_EN | CFG_CONT, + ); + } + + pending + } + + /// Call this to prime the system for async reads. This must be called at least once if any characters + /// are ever to be received. + pub fn setup_async_read(&mut self) { + #[cfg(feature = "std")] + unsafe { + self.udma_enqueue( + Bank::Rx, + &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + RX_BUF_DEPTH], + CFG_EN | CFG_CONT, + ); + } + #[cfg(not(feature = "std"))] + unsafe { + self.udma_enqueue( + Bank::Rx, + &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + RX_BUF_DEPTH], + CFG_EN | CFG_CONT, + ); + } + } +} + +#[derive(Debug)] +pub struct UartIrq { + pub csr: CSR, + #[cfg(feature = "std")] + pub handlers: [Option; 4], + #[cfg(feature = "std")] + /// We can't claim the interrupt when the object is created, because the version we allocate + /// inside `new()` is a temporary instance that exists on the stack. It's recommend that the + /// caller put `UartIrq` inside a `Box` so that the location of the structure does not move + /// around. Later on, when `register_handler()` is invoked, the address of `self` is used to + /// pass into the handler. It is important that the caller ensures that `self` does not move around. + interrupt_claimed: bool, +} +impl UartIrq { + #[cfg(feature = "std")] + pub fn new() -> Self { + let uart = xous::syscall::map_memory( + xous::MemoryAddress::new(HW_IRQARRAY5_BASE), + None, + 4096, + xous::MemoryFlags::R | xous::MemoryFlags::W, + ) + .expect("couldn't map uart IRQ control"); + Self { + csr: CSR::new(uart.as_ptr() as *mut u32), + handlers: [None, None, None, None], + interrupt_claimed: false, + } + } + + #[cfg(not(feature = "std"))] + pub fn new() -> Self { + use riscv::register::vexriscv::mim; + mim::write(mim::read() | (1 << utra::irqarray5::IRQARRAY5_IRQ)); + Self { csr: CSR::new(HW_IRQARRAY5_BASE as *mut u32) } + } + + pub fn rx_irq_ena(&mut self, channel: UartChannel, enable: bool) { + let val = if enable { 1 } else { 0 }; + match channel { + UartChannel::Uart0 => self.csr.rmwf(utra::irqarray5::EV_ENABLE_UART0_RX, val), + UartChannel::Uart1 => self.csr.rmwf(utra::irqarray5::EV_ENABLE_UART1_RX, val), + UartChannel::Uart2 => self.csr.rmwf(utra::irqarray5::EV_ENABLE_UART2_RX, val), + UartChannel::Uart3 => self.csr.rmwf(utra::irqarray5::EV_ENABLE_UART3_RX, val), + } + } + + #[cfg(feature = "std")] + /// This needs to be invoked from a Pin'd Box wrapper of the UartIrq structure. Here is how the + /// pattern looks: + /// + /// ```rust + /// let mut uart_irq = Box::pin(cramium_hal::udma::UartIrq::new()); + /// Pin::as_mut(&mut uart_irq).register_handler(udma::UartChannel::Uart1, uart_handler); + /// ``` + /// + /// What this does is bind a `UartIrq` instance to an address in the heap (via Box), and + /// marks that address as non-moveable (via Pin), ensuring that the `register_handler` call's + /// view of `self` stays around forever. + /// + /// Note: this does not also enable the interrupt channel, it just registers the handler + /// + /// Safety: the function is only safe to use if `self` has a `static` lifetime, that is, the + /// `UartIrq` object will live the entire duration of the OS. If the object is destroyed, + /// the IRQ handler will point to an invalid location and the system will crash. In general, + /// we don't intend this kind of behavior, so we don't implement a `Drop` because simply + /// de-allocating the interrupt handler on an accidental Drop is probably not intentional + /// and can lead to even more confusing/harder-to-debug faults, i.e., the system won't crash, + /// but it will simply stop responding to interrupts. As a philosophical point, if an unregister behavior + /// is desired, it should be explicit. + pub unsafe fn register_handler( + mut self: std::pin::Pin<&mut Self>, + channel: UartChannel, + handler: HandlerFn, + ) { + if !self.interrupt_claimed { + xous::claim_interrupt( + utra::irqarray5::IRQARRAY5_IRQ, + main_uart_handler, + self.as_ref().get_ref() as *const UartIrq as *mut usize, + ) + .expect("couldn't claim UART IRQ channel"); + self.interrupt_claimed = true; + } + + self.handlers[channel as usize] = Some(handler); + } +} + +pub type HandlerFn = fn(usize, *mut usize); + +#[cfg(feature = "std")] +fn main_uart_handler(irq_no: usize, arg: *mut usize) { + // check ev_pending and dispatch handlers based on that + let uartirq = unsafe { &mut *(arg as *mut UartIrq) }; + let pending = uartirq.csr.r(utra::irqarray5::EV_PENDING); + if pending & uartirq.csr.ms(utra::irqarray5::EV_PENDING_UART0_RX, 1) != 0 { + if let Some(h) = uartirq.handlers[0] { + h(irq_no, arg); + } + } + if pending & uartirq.csr.ms(utra::irqarray5::EV_PENDING_UART1_RX, 1) != 0 { + if let Some(h) = uartirq.handlers[1] { + h(irq_no, arg); + } + } + if pending & uartirq.csr.ms(utra::irqarray5::EV_PENDING_UART2_RX, 1) != 0 { + if let Some(h) = uartirq.handlers[2] { + h(irq_no, arg); + } + } + if pending & uartirq.csr.ms(utra::irqarray5::EV_PENDING_UART3_RX, 1) != 0 { + if let Some(h) = uartirq.handlers[3] { + h(irq_no, arg); + } + } + // note that this will also clear other spurious interrupts without issuing a warning. + uartirq.csr.wo(utra::irqarray5::EV_PENDING, pending); } // ----------------------------------- SPIM ------------------------------------