From 81c6d9510b67d2344f993f1ffff36728d7674fd2 Mon Sep 17 00:00:00 2001 From: bunnie Date: Fri, 4 Oct 2024 22:59:02 +0800 Subject: [PATCH] modularize the udma module --- libs/cramium-hal/src/udma/i2c.rs | 0 libs/cramium-hal/src/udma/mod.rs | 409 +++++++++ .../cramium-hal/src/{udma.rs => udma/spim.rs} | 811 +----------------- libs/cramium-hal/src/udma/uart.rs | 414 +++++++++ 4 files changed, 824 insertions(+), 810 deletions(-) create mode 100644 libs/cramium-hal/src/udma/i2c.rs create mode 100644 libs/cramium-hal/src/udma/mod.rs rename libs/cramium-hal/src/{udma.rs => udma/spim.rs} (59%) create mode 100644 libs/cramium-hal/src/udma/uart.rs diff --git a/libs/cramium-hal/src/udma/i2c.rs b/libs/cramium-hal/src/udma/i2c.rs new file mode 100644 index 000000000..e69de29bb diff --git a/libs/cramium-hal/src/udma/mod.rs b/libs/cramium-hal/src/udma/mod.rs new file mode 100644 index 000000000..4717c1a6f --- /dev/null +++ b/libs/cramium-hal/src/udma/mod.rs @@ -0,0 +1,409 @@ +pub mod i2c; +pub mod spim; +pub mod uart; + +use core::mem::size_of; + +pub use i2c::*; +pub use spim::*; +pub use uart::*; +use utralib::*; + +use crate::SharedCsr; + +/// UDMA has a structure that Rust hates. The concept of UDMA is to take a bunch of +/// different hardware functions, and access them with a template register pattern. +/// But with small asterisks here and there depending upon the hardware block in question. +/// +/// It is essentially polymorphism at the hardware level, but with special cases meant +/// to be patched up with instance-specific peeks and pokes. It's probably possible +/// to create a type system that can safe-ify this kind of structure, but just because +/// something is possible does not mean it's a good idea to do it, nor would it be +/// maintainable and/or ergonomic to use. +/// +/// Anyways. Lots of unsafe code here. UDMA: specious concept, made entirely of footguns. + +// --------------------------- Global Shared State (!!🤌!!) -------------------------- +#[repr(usize)] +enum GlobalReg { + ClockGate = 0, + EventIn = 1, +} +impl Into for GlobalReg { + fn into(self) -> usize { self as usize } +} +#[repr(u32)] +#[derive(Copy, Clone, num_derive::FromPrimitive)] +pub enum PeriphId { + Uart0 = 1 << 0, + Uart1 = 1 << 1, + Uart2 = 1 << 2, + Uart3 = 1 << 3, + Spim0 = 1 << 4, + Spim1 = 1 << 5, + Spim2 = 1 << 6, + Spim3 = 1 << 7, + I2c0 = 1 << 8, + I2c1 = 1 << 9, + I2c2 = 1 << 10, + I2c3 = 1 << 11, + Sdio = 1 << 12, + I2s = 1 << 13, + Cam = 1 << 14, + Filter = 1 << 15, + Scif = 1 << 16, + Spis0 = 1 << 17, + Spis1 = 1 << 18, + Adc = 1 << 19, +} +impl Into for PeriphId { + fn into(self) -> u32 { self as u32 } +} + +impl From for PeriphId { + fn from(value: SpimChannel) -> Self { + match value { + SpimChannel::Channel0 => PeriphId::Spim0, + SpimChannel::Channel1 => PeriphId::Spim1, + SpimChannel::Channel2 => PeriphId::Spim2, + SpimChannel::Channel3 => PeriphId::Spim3, + } + } +} + +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum PeriphEventId { + Uart0 = 0, + Uart1 = 4, + Uart2 = 8, + Uart3 = 12, + Spim0 = 16, + Spim1 = 20, + Spim2 = 24, + Spim3 = 28, + I2c0 = 32, + I2c1 = 36, + I2c2 = 40, + I2c3 = 44, + Sdio = 48, + I2s = 52, + Cam = 56, + Adc = 57, // note exception to ordering here + Filter = 60, + Scif = 64, + Spis0 = 68, + Spis1 = 72, +} +impl From for PeriphEventId { + fn from(id: PeriphId) -> Self { + match id { + PeriphId::Uart0 => PeriphEventId::Uart0, + PeriphId::Uart1 => PeriphEventId::Uart1, + PeriphId::Uart2 => PeriphEventId::Uart2, + PeriphId::Uart3 => PeriphEventId::Uart3, + PeriphId::Spim0 => PeriphEventId::Spim0, + PeriphId::Spim1 => PeriphEventId::Spim1, + PeriphId::Spim2 => PeriphEventId::Spim2, + PeriphId::Spim3 => PeriphEventId::Spim3, + PeriphId::I2c0 => PeriphEventId::I2c0, + PeriphId::I2c1 => PeriphEventId::I2c1, + PeriphId::I2c2 => PeriphEventId::I2c2, + PeriphId::I2c3 => PeriphEventId::I2c3, + PeriphId::Sdio => PeriphEventId::Sdio, + PeriphId::I2s => PeriphEventId::I2s, + PeriphId::Cam => PeriphEventId::Cam, + PeriphId::Filter => PeriphEventId::Filter, + PeriphId::Scif => PeriphEventId::Scif, + PeriphId::Spis0 => PeriphEventId::Spis0, + PeriphId::Spis1 => PeriphEventId::Spis1, + PeriphId::Adc => PeriphEventId::Adc, + } + } +} +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum EventUartOffset { + Rx = 0, + Tx = 1, + RxChar = 2, + Err = 3, +} +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum EventSpimOffset { + Rx = 0, + Tx = 1, + Cmd = 2, + Eot = 3, +} +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum EventI2cOffset { + Rx = 0, + Tx = 1, + Cmd = 2, + Eot = 3, +} +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum EventSdioOffset { + Rx = 0, + Tx = 1, + Eot = 2, + Err = 3, +} +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum EventI2sOffset { + Rx = 0, + Tx = 1, +} +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum EventCamOffset { + Rx = 0, +} +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum EventAdcOffset { + Rx = 0, +} +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum EventFilterOffset { + Eot = 0, + Active = 1, +} +#[repr(u32)] +#[derive(Copy, Clone)] + +pub enum EventScifOffset { + Rx = 0, + Tx = 1, + RxChar = 2, + Err = 3, +} +#[repr(u32)] +#[derive(Copy, Clone)] +pub enum EventSpisOffset { + Rx = 0, + Tx = 1, + Eot = 2, +} +#[derive(Copy, Clone)] +pub enum PeriphEventType { + Uart(EventUartOffset), + Spim(EventSpimOffset), + I2c(EventI2cOffset), + Sdio(EventSdioOffset), + I2s(EventI2sOffset), + Cam(EventCamOffset), + Adc(EventAdcOffset), + Filter(EventFilterOffset), + Scif(EventScifOffset), + Spis(EventSpisOffset), +} +impl Into for PeriphEventType { + fn into(self) -> u32 { + match self { + PeriphEventType::Uart(t) => t as u32, + PeriphEventType::Spim(t) => t as u32, + PeriphEventType::I2c(t) => t as u32, + PeriphEventType::Sdio(t) => t as u32, + PeriphEventType::I2s(t) => t as u32, + PeriphEventType::Cam(t) => t as u32, + PeriphEventType::Adc(t) => t as u32, + PeriphEventType::Filter(t) => t as u32, + PeriphEventType::Scif(t) => t as u32, + PeriphEventType::Spis(t) => t as u32, + } + } +} + +/// Use a trait that will allow us to share code between both `std` and `no-std` implementations +pub trait UdmaGlobalConfig { + fn clock(&self, peripheral: PeriphId, enable: bool); + unsafe fn udma_event_map( + &self, + peripheral: PeriphId, + event_type: PeriphEventType, + to_channel: EventChannel, + ); +} + +#[repr(u32)] +#[derive(Debug, Copy, Clone, num_derive::FromPrimitive)] +pub enum EventChannel { + Channel0 = 0, + Channel1 = 8, + Channel2 = 16, + Channel3 = 24, +} +pub struct GlobalConfig { + csr: SharedCsr, +} +impl GlobalConfig { + pub fn new(base_addr: *mut u32) -> Self { GlobalConfig { csr: SharedCsr::new(base_addr) } } + + pub fn clock_on(&self, peripheral: PeriphId) { + // Safety: only safe when used in the context of UDMA registers. + unsafe { + self.csr.base().add(GlobalReg::ClockGate.into()).write_volatile( + self.csr.base().add(GlobalReg::ClockGate.into()).read_volatile() | peripheral as u32, + ); + } + } + + pub fn clock_off(&self, peripheral: PeriphId) { + // Safety: only safe when used in the context of UDMA registers. + unsafe { + self.csr.base().add(GlobalReg::ClockGate.into()).write_volatile( + self.csr.base().add(GlobalReg::ClockGate.into()).read_volatile() & !(peripheral as u32), + ); + } + } + + pub fn raw_clock_map(&self) -> u32 { + // Safety: only safe when used in the context of UDMA registers. + unsafe { self.csr.base().add(GlobalReg::ClockGate.into()).read_volatile() } + } + + pub fn is_clock_set(&self, peripheral: PeriphId) -> bool { + // Safety: only safe when used in the context of UDMA registers. + unsafe { + (self.csr.base().add(GlobalReg::ClockGate.into()).read_volatile() & (peripheral as u32)) != 0 + } + } + + pub fn map_event(&self, peripheral: PeriphId, event_type: PeriphEventType, to_channel: EventChannel) { + let event_type: u32 = event_type.into(); + let id: u32 = PeriphEventId::from(peripheral) as u32 + event_type; + // Safety: only safe when used in the context of UDMA registers. + unsafe { + self.csr.base().add(GlobalReg::EventIn.into()).write_volatile( + self.csr.base().add(GlobalReg::EventIn.into()).read_volatile() + & !(0xFF << (to_channel as u32)) + | id << (to_channel as u32), + ) + } + } + + /// Same as map_event(), but for cases where the offset is known. This would typically be the case + /// where a remote function transformed a PeriphEventType into a primitive `u32` and passed + /// it through an IPC interface. + pub fn map_event_with_offset(&self, peripheral: PeriphId, event_offset: u32, to_channel: EventChannel) { + let id: u32 = PeriphEventId::from(peripheral) as u32 + event_offset; + // Safety: only safe when used in the context of UDMA registers. + unsafe { + self.csr.base().add(GlobalReg::EventIn.into()).write_volatile( + self.csr.base().add(GlobalReg::EventIn.into()).read_volatile() + & !(0xFF << (to_channel as u32)) + | id << (to_channel as u32), + ) + } + } + + pub fn raw_event_map(&self) -> u32 { + // Safety: only safe when used in the context of UDMA registers. + unsafe { self.csr.base().add(GlobalReg::EventIn.into()).read_volatile() } + } +} + +impl UdmaGlobalConfig for GlobalConfig { + fn clock(&self, peripheral: PeriphId, enable: bool) { + if enable { + self.clock_on(peripheral); + } else { + self.clock_off(peripheral); + } + } + + unsafe fn udma_event_map( + &self, + peripheral: PeriphId, + event_type: PeriphEventType, + to_channel: EventChannel, + ) { + self.map_event(peripheral, event_type, to_channel); + } +} +// --------------------------------- DMA channel ------------------------------------ +const CFG_EN: u32 = 0b01_0000; // start a transfer +#[allow(dead_code)] +const CFG_CONT: u32 = 0b00_0001; // continuous mode +#[allow(dead_code)] +const CFG_SIZE_8: u32 = 0b00_0000; // 8-bit transfer +#[allow(dead_code)] +const CFG_SIZE_16: u32 = 0b00_0010; // 16-bit transfer +#[allow(dead_code)] +const CFG_SIZE_32: u32 = 0b00_0100; // 32-bit transfer +#[allow(dead_code)] +const CFG_CLEAR: u32 = 0b10_0000; // stop and clear all pending transfers +#[allow(dead_code)] +const CFG_PENDING: u32 = 0b10_0000; // on read, indicates a transfer pending +const CFG_SHADOW: u32 = 0b10_0000; // indicates a shadow transfer + +#[repr(usize)] +pub enum Bank { + Rx = 0, + Tx = 0x10 / size_of::(), + // woo dat special case... + Custom = 0x20 / size_of::(), +} +impl Into for Bank { + fn into(self) -> usize { self as usize } +} + +/// Crate-local struct that defines the offset of registers in UDMA banks, as words. +#[repr(usize)] +pub enum DmaReg { + Saddr = 0, + Size = 1, + Cfg = 2, + #[allow(dead_code)] + IntCfg = 3, +} +impl Into for DmaReg { + fn into(self) -> usize { self as usize } +} + +pub trait Udma { + /// Every implementation of Udma has to implement the csr_mut() accessor + fn csr_mut(&mut self) -> &mut CSR; + /// Every implementation of Udma has to implement the csr() accessor + fn csr(&self) -> &CSR; + + /// `bank` selects which UDMA bank is the target + /// `buf` is a slice that points to the memory that is the target of the UDMA. Needs to be accessible + /// by the UDMA subsystem, e.g. in IFRAM0/IFRAM1 range, and is a *physical address* even in a + /// system running on virtual memory (!!!) + /// `config` is a device-specific word that configures the DMA. + /// + /// Safety: the `buf` has to be allocated, length-checked, and in the range of memory + /// that is valid for UDMA targets + unsafe fn udma_enqueue(&self, bank: Bank, buf: &[T], config: u32) { + let bank_addr = self.csr().base().add(bank as usize); + let buf_addr = buf.as_ptr() as u32; + /* + crate::println!( + "udma_enqueue: @{:x}[{}]/{:x}", + buf_addr, + (buf.len() * size_of::()) as u32, + config | CFG_EN + ); */ + bank_addr.add(DmaReg::Saddr.into()).write_volatile(buf_addr); + bank_addr.add(DmaReg::Size.into()).write_volatile((buf.len() * size_of::()) as u32); + bank_addr.add(DmaReg::Cfg.into()).write_volatile(config | CFG_EN) + } + fn udma_can_enqueue(&self, bank: Bank) -> bool { + // Safety: only safe when used in the context of UDMA registers. + unsafe { + (self.csr().base().add(bank as usize).add(DmaReg::Cfg.into()).read_volatile() & CFG_SHADOW) == 0 + } + } + fn udma_busy(&self, bank: Bank) -> bool { + // Safety: only safe when used in the context of UDMA registers. + unsafe { self.csr().base().add(bank as usize).add(DmaReg::Saddr.into()).read_volatile() != 0 } + } +} diff --git a/libs/cramium-hal/src/udma.rs b/libs/cramium-hal/src/udma/spim.rs similarity index 59% rename from libs/cramium-hal/src/udma.rs rename to libs/cramium-hal/src/udma/spim.rs index 85a057931..147dd5a5d 100644 --- a/libs/cramium-hal/src/udma.rs +++ b/libs/cramium-hal/src/udma/spim.rs @@ -1,816 +1,7 @@ -use core::mem::size_of; - use utralib::*; -use crate::SharedCsr; use crate::ifram::{IframRange, UdmaWidths}; - -/// UDMA has a structure that Rust hates. The concept of UDMA is to take a bunch of -/// different hardware functions, and access them with a template register pattern. -/// But with small asterisks here and there depending upon the hardware block in question. -/// -/// It is essentially polymorphism at the hardware level, but with special cases meant -/// to be patched up with instance-specific peeks and pokes. It's probably possible -/// to create a type system that can safe-ify this kind of structure, but just because -/// something is possible does not mean it's a good idea to do it, nor would it be -/// maintainable and/or ergonomic to use. -/// -/// Anyways. Lots of unsafe code here. UDMA: specious concept, made entirely of footguns. - -// --------------------------- Global Shared State (!!🤌!!) -------------------------- -#[repr(usize)] -enum GlobalReg { - ClockGate = 0, - EventIn = 1, -} -impl Into for GlobalReg { - fn into(self) -> usize { self as usize } -} -#[repr(u32)] -#[derive(Copy, Clone, num_derive::FromPrimitive)] -pub enum PeriphId { - Uart0 = 1 << 0, - Uart1 = 1 << 1, - Uart2 = 1 << 2, - Uart3 = 1 << 3, - Spim0 = 1 << 4, - Spim1 = 1 << 5, - Spim2 = 1 << 6, - Spim3 = 1 << 7, - I2c0 = 1 << 8, - I2c1 = 1 << 9, - I2c2 = 1 << 10, - I2c3 = 1 << 11, - Sdio = 1 << 12, - I2s = 1 << 13, - Cam = 1 << 14, - Filter = 1 << 15, - Scif = 1 << 16, - Spis0 = 1 << 17, - Spis1 = 1 << 18, - Adc = 1 << 19, -} -impl Into for PeriphId { - fn into(self) -> u32 { self as u32 } -} - -impl From for PeriphId { - fn from(value: SpimChannel) -> Self { - match value { - SpimChannel::Channel0 => PeriphId::Spim0, - SpimChannel::Channel1 => PeriphId::Spim1, - SpimChannel::Channel2 => PeriphId::Spim2, - SpimChannel::Channel3 => PeriphId::Spim3, - } - } -} - -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum PeriphEventId { - Uart0 = 0, - Uart1 = 4, - Uart2 = 8, - Uart3 = 12, - Spim0 = 16, - Spim1 = 20, - Spim2 = 24, - Spim3 = 28, - I2c0 = 32, - I2c1 = 36, - I2c2 = 40, - I2c3 = 44, - Sdio = 48, - I2s = 52, - Cam = 56, - Adc = 57, // note exception to ordering here - Filter = 60, - Scif = 64, - Spis0 = 68, - Spis1 = 72, -} -impl From for PeriphEventId { - fn from(id: PeriphId) -> Self { - match id { - PeriphId::Uart0 => PeriphEventId::Uart0, - PeriphId::Uart1 => PeriphEventId::Uart1, - PeriphId::Uart2 => PeriphEventId::Uart2, - PeriphId::Uart3 => PeriphEventId::Uart3, - PeriphId::Spim0 => PeriphEventId::Spim0, - PeriphId::Spim1 => PeriphEventId::Spim1, - PeriphId::Spim2 => PeriphEventId::Spim2, - PeriphId::Spim3 => PeriphEventId::Spim3, - PeriphId::I2c0 => PeriphEventId::I2c0, - PeriphId::I2c1 => PeriphEventId::I2c1, - PeriphId::I2c2 => PeriphEventId::I2c2, - PeriphId::I2c3 => PeriphEventId::I2c3, - PeriphId::Sdio => PeriphEventId::Sdio, - PeriphId::I2s => PeriphEventId::I2s, - PeriphId::Cam => PeriphEventId::Cam, - PeriphId::Filter => PeriphEventId::Filter, - PeriphId::Scif => PeriphEventId::Scif, - PeriphId::Spis0 => PeriphEventId::Spis0, - PeriphId::Spis1 => PeriphEventId::Spis1, - PeriphId::Adc => PeriphEventId::Adc, - } - } -} -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum EventUartOffset { - Rx = 0, - Tx = 1, - RxChar = 2, - Err = 3, -} -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum EventSpimOffset { - Rx = 0, - Tx = 1, - Cmd = 2, - Eot = 3, -} -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum EventI2cOffset { - Rx = 0, - Tx = 1, - Cmd = 2, - Eot = 3, -} -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum EventSdioOffset { - Rx = 0, - Tx = 1, - Eot = 2, - Err = 3, -} -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum EventI2sOffset { - Rx = 0, - Tx = 1, -} -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum EventCamOffset { - Rx = 0, -} -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum EventAdcOffset { - Rx = 0, -} -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum EventFilterOffset { - Eot = 0, - Active = 1, -} -#[repr(u32)] -#[derive(Copy, Clone)] - -pub enum EventScifOffset { - Rx = 0, - Tx = 1, - RxChar = 2, - Err = 3, -} -#[repr(u32)] -#[derive(Copy, Clone)] -pub enum EventSpisOffset { - Rx = 0, - Tx = 1, - Eot = 2, -} -#[derive(Copy, Clone)] -pub enum PeriphEventType { - Uart(EventUartOffset), - Spim(EventSpimOffset), - I2c(EventI2cOffset), - Sdio(EventSdioOffset), - I2s(EventI2sOffset), - Cam(EventCamOffset), - Adc(EventAdcOffset), - Filter(EventFilterOffset), - Scif(EventScifOffset), - Spis(EventSpisOffset), -} -impl Into for PeriphEventType { - fn into(self) -> u32 { - match self { - PeriphEventType::Uart(t) => t as u32, - PeriphEventType::Spim(t) => t as u32, - PeriphEventType::I2c(t) => t as u32, - PeriphEventType::Sdio(t) => t as u32, - PeriphEventType::I2s(t) => t as u32, - PeriphEventType::Cam(t) => t as u32, - PeriphEventType::Adc(t) => t as u32, - PeriphEventType::Filter(t) => t as u32, - PeriphEventType::Scif(t) => t as u32, - PeriphEventType::Spis(t) => t as u32, - } - } -} - -/// Use a trait that will allow us to share code between both `std` and `no-std` implementations -pub trait UdmaGlobalConfig { - fn clock(&self, peripheral: PeriphId, enable: bool); - unsafe fn udma_event_map( - &self, - peripheral: PeriphId, - event_type: PeriphEventType, - to_channel: EventChannel, - ); -} - -#[repr(u32)] -#[derive(Debug, Copy, Clone, num_derive::FromPrimitive)] -pub enum EventChannel { - Channel0 = 0, - Channel1 = 8, - Channel2 = 16, - Channel3 = 24, -} -pub struct GlobalConfig { - csr: SharedCsr, -} -impl GlobalConfig { - pub fn new(base_addr: *mut u32) -> Self { GlobalConfig { csr: SharedCsr::new(base_addr) } } - - pub fn clock_on(&self, peripheral: PeriphId) { - // Safety: only safe when used in the context of UDMA registers. - unsafe { - self.csr.base().add(GlobalReg::ClockGate.into()).write_volatile( - self.csr.base().add(GlobalReg::ClockGate.into()).read_volatile() | peripheral as u32, - ); - } - } - - pub fn clock_off(&self, peripheral: PeriphId) { - // Safety: only safe when used in the context of UDMA registers. - unsafe { - self.csr.base().add(GlobalReg::ClockGate.into()).write_volatile( - self.csr.base().add(GlobalReg::ClockGate.into()).read_volatile() & !(peripheral as u32), - ); - } - } - - pub fn raw_clock_map(&self) -> u32 { - // Safety: only safe when used in the context of UDMA registers. - unsafe { self.csr.base().add(GlobalReg::ClockGate.into()).read_volatile() } - } - - pub fn is_clock_set(&self, peripheral: PeriphId) -> bool { - // Safety: only safe when used in the context of UDMA registers. - unsafe { - (self.csr.base().add(GlobalReg::ClockGate.into()).read_volatile() & (peripheral as u32)) != 0 - } - } - - pub fn map_event(&self, peripheral: PeriphId, event_type: PeriphEventType, to_channel: EventChannel) { - let event_type: u32 = event_type.into(); - let id: u32 = PeriphEventId::from(peripheral) as u32 + event_type; - // Safety: only safe when used in the context of UDMA registers. - unsafe { - self.csr.base().add(GlobalReg::EventIn.into()).write_volatile( - self.csr.base().add(GlobalReg::EventIn.into()).read_volatile() - & !(0xFF << (to_channel as u32)) - | id << (to_channel as u32), - ) - } - } - - /// Same as map_event(), but for cases where the offset is known. This would typically be the case - /// where a remote function transformed a PeriphEventType into a primitive `u32` and passed - /// it through an IPC interface. - pub fn map_event_with_offset(&self, peripheral: PeriphId, event_offset: u32, to_channel: EventChannel) { - let id: u32 = PeriphEventId::from(peripheral) as u32 + event_offset; - // Safety: only safe when used in the context of UDMA registers. - unsafe { - self.csr.base().add(GlobalReg::EventIn.into()).write_volatile( - self.csr.base().add(GlobalReg::EventIn.into()).read_volatile() - & !(0xFF << (to_channel as u32)) - | id << (to_channel as u32), - ) - } - } - - pub fn raw_event_map(&self) -> u32 { - // Safety: only safe when used in the context of UDMA registers. - unsafe { self.csr.base().add(GlobalReg::EventIn.into()).read_volatile() } - } -} - -impl UdmaGlobalConfig for GlobalConfig { - fn clock(&self, peripheral: PeriphId, enable: bool) { - if enable { - self.clock_on(peripheral); - } else { - self.clock_off(peripheral); - } - } - - unsafe fn udma_event_map( - &self, - peripheral: PeriphId, - event_type: PeriphEventType, - to_channel: EventChannel, - ) { - self.map_event(peripheral, event_type, to_channel); - } -} -// --------------------------------- DMA channel ------------------------------------ -const CFG_EN: u32 = 0b01_0000; // start a transfer -#[allow(dead_code)] -const CFG_CONT: u32 = 0b00_0001; // continuous mode -#[allow(dead_code)] -const CFG_SIZE_8: u32 = 0b00_0000; // 8-bit transfer -#[allow(dead_code)] -const CFG_SIZE_16: u32 = 0b00_0010; // 16-bit transfer -#[allow(dead_code)] -const CFG_SIZE_32: u32 = 0b00_0100; // 32-bit transfer -#[allow(dead_code)] -const CFG_CLEAR: u32 = 0b10_0000; // stop and clear all pending transfers -#[allow(dead_code)] -const CFG_PENDING: u32 = 0b10_0000; // on read, indicates a transfer pending -const CFG_SHADOW: u32 = 0b10_0000; // indicates a shadow transfer - -#[repr(usize)] -pub enum Bank { - Rx = 0, - Tx = 0x10 / size_of::(), - // woo dat special case... - Custom = 0x20 / size_of::(), -} -impl Into for Bank { - fn into(self) -> usize { self as usize } -} - -/// Crate-local struct that defines the offset of registers in UDMA banks, as words. -#[repr(usize)] -pub enum DmaReg { - Saddr = 0, - Size = 1, - Cfg = 2, - #[allow(dead_code)] - IntCfg = 3, -} -impl Into for DmaReg { - fn into(self) -> usize { self as usize } -} - -pub trait Udma { - /// Every implementation of Udma has to implement the csr_mut() accessor - fn csr_mut(&mut self) -> &mut CSR; - /// Every implementation of Udma has to implement the csr() accessor - fn csr(&self) -> &CSR; - - /// `bank` selects which UDMA bank is the target - /// `buf` is a slice that points to the memory that is the target of the UDMA. Needs to be accessible - /// by the UDMA subsystem, e.g. in IFRAM0/IFRAM1 range, and is a *physical address* even in a - /// system running on virtual memory (!!!) - /// `config` is a device-specific word that configures the DMA. - /// - /// Safety: the `buf` has to be allocated, length-checked, and in the range of memory - /// that is valid for UDMA targets - unsafe fn udma_enqueue(&self, bank: Bank, buf: &[T], config: u32) { - let bank_addr = self.csr().base().add(bank as usize); - let buf_addr = buf.as_ptr() as u32; - /* - crate::println!( - "udma_enqueue: @{:x}[{}]/{:x}", - buf_addr, - (buf.len() * size_of::()) as u32, - config | CFG_EN - ); */ - bank_addr.add(DmaReg::Saddr.into()).write_volatile(buf_addr); - bank_addr.add(DmaReg::Size.into()).write_volatile((buf.len() * size_of::()) as u32); - bank_addr.add(DmaReg::Cfg.into()).write_volatile(config | CFG_EN) - } - fn udma_can_enqueue(&self, bank: Bank) -> bool { - // Safety: only safe when used in the context of UDMA registers. - unsafe { - (self.csr().base().add(bank as usize).add(DmaReg::Cfg.into()).read_volatile() & CFG_SHADOW) == 0 - } - } - fn udma_busy(&self, bank: Bank) -> bool { - // Safety: only safe when used in the context of UDMA registers. - unsafe { self.csr().base().add(bank as usize).add(DmaReg::Saddr.into()).read_volatile() != 0 } - } -} - -// ----------------------------------- UART ------------------------------------ -#[repr(usize)] -enum UartReg { - Status = 0, - Setup = 1, -} -impl Into for UartReg { - fn into(self) -> usize { self as usize } -} - -#[repr(usize)] -pub enum UartChannel { - Uart0 = 0, - Uart1 = 1, - Uart2 = 2, - Uart3 = 3, -} -impl Into for UartChannel { - fn into(self) -> usize { self as usize } -} - -/// UDMA UART wrapper. Contains all the warts on top of the Channel abstraction. -pub struct Uart { - /// This is assumed to point to the base of the peripheral's UDMA register set. - csr: CSR, - #[allow(dead_code)] // suppress warning with `std` is not selected - ifram: IframRange, -} - -/// Blanket implementations to access the CSR within UART. Needed because you can't -/// have default fields in traits: https://github.com/rust-lang/rfcs/pull/1546 -impl Udma for Uart { - fn csr_mut(&mut self) -> &mut CSR { &mut self.csr } - - fn csr(&self) -> &CSR { &self.csr } -} -/// The sum of UART_TX_BUF_SIZE + UART_RX_BUF_SIZE should be 4096. -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 - /// - /// This function is `unsafe` because it can only be called after the - /// global shared UDMA state has been set up to un-gate clocks and set up - /// events. - /// - /// It is also `unsafe` on Drop because you have to remember to unmap - /// the clock manually as well once the object is dropped... - /// - /// Allocates a 4096-deep buffer for tx/rx purposes: the first 2048 bytes - /// are used for Tx, the second 2048 bytes for Rx. If this buffer size has - /// to change, be sure to update the loader, as it takes this as an assumption - /// since no IFRAM allocator is running at that time. - #[cfg(feature = "std")] - pub unsafe fn new(channel: UartChannel, baud: u32, clk_freq: u32) -> Self { - assert!(UART_RX_BUF_SIZE + UART_TX_BUF_SIZE == 4096, "Configuration error in UDMA UART"); - let bank_addr = match channel { - UartChannel::Uart0 => utra::udma_uart_0::HW_UDMA_UART_0_BASE, - UartChannel::Uart1 => utra::udma_uart_1::HW_UDMA_UART_1_BASE, - UartChannel::Uart2 => utra::udma_uart_2::HW_UDMA_UART_2_BASE, - UartChannel::Uart3 => utra::udma_uart_3::HW_UDMA_UART_3_BASE, - }; - let uart = xous::syscall::map_memory( - xous::MemoryAddress::new(bank_addr), - None, - 4096, - xous::MemoryFlags::R | xous::MemoryFlags::W, - ) - .expect("couldn't map serial port"); - - // now setup the channel - let csr = CSR::new(uart.as_mut_ptr() as *mut u32); - - let clk_counter: u32 = (clk_freq + baud / 2) / baud; - // setup baud, bits, parity, etc. - csr.base() - .add(Bank::Custom.into()) - .add(UartReg::Setup.into()) - .write_volatile(0x0306 | (clk_counter << 16)); - - Uart { csr, ifram: IframRange::request(UART_RX_BUF_SIZE + UART_TX_BUF_SIZE, None).unwrap() } - } - - /// Gets a handle to the UART. Used for re-acquiring previously initialized - /// UART hardware, such as from the loader booting into Xous - /// - /// Safety: only safe to call in the context of a previously initialized UART - pub unsafe fn get_handle(csr_virt_addr: usize, udma_phys_addr: usize, udma_virt_addr: usize) -> Self { - assert!(UART_RX_BUF_SIZE + UART_TX_BUF_SIZE == 4096, "Configuration error in UDMA UART"); - let csr = CSR::new(csr_virt_addr as *mut u32); - Uart { - csr, - ifram: IframRange::from_raw_parts( - udma_phys_addr, - udma_virt_addr, - UART_RX_BUF_SIZE + UART_TX_BUF_SIZE, - ), - } - } - - pub fn set_baud(&self, baud: u32, clk_freq: u32) { - let clk_counter: u32 = (clk_freq + baud / 2) / baud; - // setup baud, bits, parity, etc. - // safety: this is safe to call as long as the base address points at a valid UART. - unsafe { - self.csr - .base() - .add(Bank::Custom.into()) - .add(UartReg::Setup.into()) - .write_volatile(0x0306 | (clk_counter << 16)); - } - } - - pub fn disable(&mut self) { - self.wait_tx_done(); - // safe only in the context of a UART UDMA address - unsafe { - self.csr.base().add(Bank::Custom.into()).add(UartReg::Setup.into()).write_volatile(0x0050_0006); - } - } - - pub fn tx_busy(&self) -> bool { - // safe only in the context of a UART UDMA address - unsafe { - (self.csr.base().add(Bank::Custom.into()).add(UartReg::Status.into()).read_volatile() & 1) != 0 - } - } - - pub fn rx_busy(&self) -> bool { - // safe only in the context of a UART UDMA address - unsafe { - (self.csr.base().add(Bank::Custom.into()).add(UartReg::Status.into()).read_volatile() & 2) != 0 - } - } - - pub fn wait_tx_done(&self) { - while self.udma_busy(Bank::Tx) { - #[cfg(feature = "std")] - xous::yield_slice(); - } - while self.tx_busy() {} - } - - pub fn wait_rx_done(&self) { - while self.udma_busy(Bank::Rx) { - #[cfg(feature = "std")] - xous::yield_slice(); - } - } - - /// `buf` is assumed to be a virtual address (in `std`), or a machine address - /// (in baremetal mode). This function is safe because it will operate as intended - /// within a given environment, so long as the `std` flag is applied correctly. - /// - /// When not in `std`, it's *also* assumed that `buf` is range-checked to be valid - /// for the UDMA engine. - /// - /// returns: total length of bytes written - pub fn write(&mut self, buf: &[u8]) -> usize { - let mut writelen = 0; - for chunk in buf.chunks(UART_TX_BUF_SIZE) { - #[cfg(feature = "std")] - { - self.ifram.as_slice_mut()[..chunk.len()].copy_from_slice(chunk); - // safety: the slice is in the physical range for the UDMA, and length-checked - unsafe { - self.udma_enqueue( - Bank::Tx, - &self.ifram.as_phys_slice::()[..chunk.len()], - CFG_EN | CFG_SIZE_8, - ); - } - writelen += chunk.len(); - } - #[cfg(not(feature = "std"))] - { - self.ifram.as_slice_mut()[..chunk.len()].copy_from_slice(chunk); - unsafe { - self.udma_enqueue( - Bank::Tx, - &self.ifram.as_phys_slice::()[..chunk.len()], - CFG_EN | CFG_SIZE_8, - ); - writelen += chunk.len(); - } - } - - self.wait_tx_done(); - } - writelen - } - - pub fn read(&mut self, buf: &mut [u8]) { - for chunk in buf.chunks_mut(UART_RX_BUF_SIZE) { - #[cfg(feature = "std")] - unsafe { - self.udma_enqueue( - Bank::Rx, - &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + chunk.len()], - CFG_EN | CFG_SIZE_8, - ); - } - #[cfg(not(feature = "std"))] - unsafe { - self.udma_enqueue( - Bank::Rx, - &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + chunk.len()], - CFG_EN | CFG_SIZE_8, - ); - } - self.wait_rx_done(); - #[cfg(feature = "std")] - chunk.copy_from_slice( - &self.ifram.as_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + chunk.len()], - ); - #[cfg(not(feature = "std"))] - unsafe { - chunk.copy_from_slice( - &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + chunk.len()], - ); - } - } - } - - /// 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); -} +use crate::udma::*; // ----------------------------------- SPIM ------------------------------------ diff --git a/libs/cramium-hal/src/udma/uart.rs b/libs/cramium-hal/src/udma/uart.rs new file mode 100644 index 000000000..f83be9a89 --- /dev/null +++ b/libs/cramium-hal/src/udma/uart.rs @@ -0,0 +1,414 @@ +use utralib::*; + +use crate::ifram::IframRange; +use crate::udma::*; + +// ----------------------------------- UART ------------------------------------ +#[repr(usize)] +enum UartReg { + Status = 0, + Setup = 1, +} +impl Into for UartReg { + fn into(self) -> usize { self as usize } +} + +#[repr(usize)] +pub enum UartChannel { + Uart0 = 0, + Uart1 = 1, + Uart2 = 2, + Uart3 = 3, +} +impl Into for UartChannel { + fn into(self) -> usize { self as usize } +} + +/// UDMA UART wrapper. Contains all the warts on top of the Channel abstraction. +pub struct Uart { + /// This is assumed to point to the base of the peripheral's UDMA register set. + csr: CSR, + #[allow(dead_code)] // suppress warning with `std` is not selected + ifram: IframRange, +} + +/// Blanket implementations to access the CSR within UART. Needed because you can't +/// have default fields in traits: https://github.com/rust-lang/rfcs/pull/1546 +impl Udma for Uart { + fn csr_mut(&mut self) -> &mut CSR { &mut self.csr } + + fn csr(&self) -> &CSR { &self.csr } +} +/// The sum of UART_TX_BUF_SIZE + UART_RX_BUF_SIZE should be 4096. +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 + /// + /// This function is `unsafe` because it can only be called after the + /// global shared UDMA state has been set up to un-gate clocks and set up + /// events. + /// + /// It is also `unsafe` on Drop because you have to remember to unmap + /// the clock manually as well once the object is dropped... + /// + /// Allocates a 4096-deep buffer for tx/rx purposes: the first 2048 bytes + /// are used for Tx, the second 2048 bytes for Rx. If this buffer size has + /// to change, be sure to update the loader, as it takes this as an assumption + /// since no IFRAM allocator is running at that time. + #[cfg(feature = "std")] + pub unsafe fn new(channel: UartChannel, baud: u32, clk_freq: u32) -> Self { + assert!(UART_RX_BUF_SIZE + UART_TX_BUF_SIZE == 4096, "Configuration error in UDMA UART"); + let bank_addr = match channel { + UartChannel::Uart0 => utra::udma_uart_0::HW_UDMA_UART_0_BASE, + UartChannel::Uart1 => utra::udma_uart_1::HW_UDMA_UART_1_BASE, + UartChannel::Uart2 => utra::udma_uart_2::HW_UDMA_UART_2_BASE, + UartChannel::Uart3 => utra::udma_uart_3::HW_UDMA_UART_3_BASE, + }; + let uart = xous::syscall::map_memory( + xous::MemoryAddress::new(bank_addr), + None, + 4096, + xous::MemoryFlags::R | xous::MemoryFlags::W, + ) + .expect("couldn't map serial port"); + + // now setup the channel + let csr = CSR::new(uart.as_mut_ptr() as *mut u32); + + let clk_counter: u32 = (clk_freq + baud / 2) / baud; + // setup baud, bits, parity, etc. + csr.base() + .add(Bank::Custom.into()) + .add(UartReg::Setup.into()) + .write_volatile(0x0306 | (clk_counter << 16)); + + Uart { csr, ifram: IframRange::request(UART_RX_BUF_SIZE + UART_TX_BUF_SIZE, None).unwrap() } + } + + /// Gets a handle to the UART. Used for re-acquiring previously initialized + /// UART hardware, such as from the loader booting into Xous + /// + /// Safety: only safe to call in the context of a previously initialized UART + pub unsafe fn get_handle(csr_virt_addr: usize, udma_phys_addr: usize, udma_virt_addr: usize) -> Self { + assert!(UART_RX_BUF_SIZE + UART_TX_BUF_SIZE == 4096, "Configuration error in UDMA UART"); + let csr = CSR::new(csr_virt_addr as *mut u32); + Uart { + csr, + ifram: IframRange::from_raw_parts( + udma_phys_addr, + udma_virt_addr, + UART_RX_BUF_SIZE + UART_TX_BUF_SIZE, + ), + } + } + + pub fn set_baud(&self, baud: u32, clk_freq: u32) { + let clk_counter: u32 = (clk_freq + baud / 2) / baud; + // setup baud, bits, parity, etc. + // safety: this is safe to call as long as the base address points at a valid UART. + unsafe { + self.csr + .base() + .add(Bank::Custom.into()) + .add(UartReg::Setup.into()) + .write_volatile(0x0306 | (clk_counter << 16)); + } + } + + pub fn disable(&mut self) { + self.wait_tx_done(); + // safe only in the context of a UART UDMA address + unsafe { + self.csr.base().add(Bank::Custom.into()).add(UartReg::Setup.into()).write_volatile(0x0050_0006); + } + } + + pub fn tx_busy(&self) -> bool { + // safe only in the context of a UART UDMA address + unsafe { + (self.csr.base().add(Bank::Custom.into()).add(UartReg::Status.into()).read_volatile() & 1) != 0 + } + } + + pub fn rx_busy(&self) -> bool { + // safe only in the context of a UART UDMA address + unsafe { + (self.csr.base().add(Bank::Custom.into()).add(UartReg::Status.into()).read_volatile() & 2) != 0 + } + } + + pub fn wait_tx_done(&self) { + while self.udma_busy(Bank::Tx) { + #[cfg(feature = "std")] + xous::yield_slice(); + } + while self.tx_busy() {} + } + + pub fn wait_rx_done(&self) { + while self.udma_busy(Bank::Rx) { + #[cfg(feature = "std")] + xous::yield_slice(); + } + } + + /// `buf` is assumed to be a virtual address (in `std`), or a machine address + /// (in baremetal mode). This function is safe because it will operate as intended + /// within a given environment, so long as the `std` flag is applied correctly. + /// + /// When not in `std`, it's *also* assumed that `buf` is range-checked to be valid + /// for the UDMA engine. + /// + /// returns: total length of bytes written + pub fn write(&mut self, buf: &[u8]) -> usize { + let mut writelen = 0; + for chunk in buf.chunks(UART_TX_BUF_SIZE) { + #[cfg(feature = "std")] + { + self.ifram.as_slice_mut()[..chunk.len()].copy_from_slice(chunk); + // safety: the slice is in the physical range for the UDMA, and length-checked + unsafe { + self.udma_enqueue( + Bank::Tx, + &self.ifram.as_phys_slice::()[..chunk.len()], + CFG_EN | CFG_SIZE_8, + ); + } + writelen += chunk.len(); + } + #[cfg(not(feature = "std"))] + { + self.ifram.as_slice_mut()[..chunk.len()].copy_from_slice(chunk); + unsafe { + self.udma_enqueue( + Bank::Tx, + &self.ifram.as_phys_slice::()[..chunk.len()], + CFG_EN | CFG_SIZE_8, + ); + writelen += chunk.len(); + } + } + + self.wait_tx_done(); + } + writelen + } + + pub fn read(&mut self, buf: &mut [u8]) { + for chunk in buf.chunks_mut(UART_RX_BUF_SIZE) { + #[cfg(feature = "std")] + unsafe { + self.udma_enqueue( + Bank::Rx, + &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + chunk.len()], + CFG_EN | CFG_SIZE_8, + ); + } + #[cfg(not(feature = "std"))] + unsafe { + self.udma_enqueue( + Bank::Rx, + &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + chunk.len()], + CFG_EN | CFG_SIZE_8, + ); + } + self.wait_rx_done(); + #[cfg(feature = "std")] + chunk.copy_from_slice( + &self.ifram.as_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + chunk.len()], + ); + #[cfg(not(feature = "std"))] + unsafe { + chunk.copy_from_slice( + &self.ifram.as_phys_slice::()[UART_RX_BUF_START..UART_RX_BUF_START + chunk.len()], + ); + } + } + } + + /// 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); +}