From 60b18303ed194e323e54790eaa81b4d6a2788286 Mon Sep 17 00:00:00 2001 From: bunnie Date: Fri, 26 Dec 2025 00:55:00 +0800 Subject: [PATCH] define the BIO API in the abstract API this is a fully abstracted API that should be fully hardware independent. This is meant to supercede the xous-bio-bdma library. The xous-bio-bdma library will stick around, but its main purpose is as an experimental, baremetal library that contains low level code and test code for developing the hardware. We could try to merge this into the abstract APIs but I think it doesn't make sense from a methodology standpoint - hardware development has a different tempo and flow from the software development process, and so by keeping these two separate we end up with potentially diverging APIs - but actually, this is a good thing. It allows us to develop e.g. v2 of the hardware without having to roll uncertain/experimental v2 hardware APIs into the abstract APIs right away. there is one hairy point in all of this, which is I'm trying to get fancy and have a hardware "handle" be dropped automatically when it goes out of scope. This requires me to pass around a phantom lifetime parameter, something I haven't done before. If this works, it could be a good template for dealing with other abstract hardware APIs that will help remove some unsafe code. --- libs/bao1x-api/src/bio.rs | 438 ++++++++++++++++++++++++++++++++++++++ libs/bao1x-api/src/lib.rs | 2 + 2 files changed, 440 insertions(+) create mode 100644 libs/bao1x-api/src/bio.rs diff --git a/libs/bao1x-api/src/bio.rs b/libs/bao1x-api/src/bio.rs new file mode 100644 index 000000000..a81cf9da1 --- /dev/null +++ b/libs/bao1x-api/src/bio.rs @@ -0,0 +1,438 @@ +//! FIFO - 8-deep fifo head/tail access. Cores halt on overflow/underflow. +//! - x16 r/w fifo[0] +//! - x17 r/w fifo[1] +//! - x18 r/w fifo[2] +//! - x19 r/w fifo[3] +//! +//! Quantum - core will halt until host-configured clock divider pules occurs, +//! or an external event comes in on a host-specified GPIO pin. +//! - x20 -/w halt to quantum +//! +//! GPIO - note clear-on-0 semantics for bit-clear for data pins! +//! This is done so we can do a shift-and-move without an invert to +//! bitbang a data pin. Direction retains a more "conventional" meaning +//! where a write of `1` to either clear or set will cause the action, +//! as pin direction toggling is less likely to be in a tight inner loop. +//! - x21 r/w write: (x26 & x21) -> gpio pins; read: gpio pins -> x21 +//! - x22 -/w (x26 & x22) -> `1` will set corresponding pin on gpio +//! - x23 -/w (x26 & x23) -> `0` will clear corresponding pin on gpio +//! - x24 -/w (x26 & x24) -> `1` will make corresponding gpio pin an output +//! - x25 -/w (x26 & x25) -> `1` will make corresponding gpio pin an input +//! - x26 r/w mask GPIO action outputs +//! +//! Events - operate on a shared event register. Bits [31:24] are hard-wired to FIFO +//! level flags, configured by the host; writes to bits [31:24] are ignored. +//! - x27 -/w mask event sensitivity bits +//! - x28 -/w `1` will set the corresponding event bit. Only [23:0] are wired up. +//! - x29 -/w `1` will clear the corresponding event bit Only [23:0] are wired up. +//! - x30 r/- halt until ((x27 & events) != 0), and return unmasked `events` value +//! +//! Core ID & debug: +//! - x31 r/- [31:30] -> core ID; [29:0] -> cpu clocks since reset + +// clock divider equation: +// output frequency = fclk / (div_int + div_frac / 256) + +// WS2812B timings - base cycle time is 210ns +// 0: Hi 2 cycles, low 4 cycles +// 1: Hi 4 cycles, low 2 cycles +// WS2812C timings - base cycle time is 312.5ns -0/+50ns +// 0: Hi 1 cycle, low 3 cycle +// 1: Hi 2 cycle, low 2 cycle + +use core::num::NonZeroU32; +use std::marker::PhantomData; + +use bitbybit::bitfield; +use num_traits::ToPrimitive; + +pub const BIO_SERVER_NAME: &'static str = "_BIO server_"; + +#[derive(Debug, Copy, Clone, num_derive::FromPrimitive, num_derive::ToPrimitive)] +pub enum BioOp { + InitCore, + DeInitCore, + SetCoreFreq, + GetCoreFreq, + CoreState, + GetCoreHandle, + ReleaseCoreHandle, + IrqConfig, + DmaWindows, + IoConfig, + FifoEventTriggers, + GetVersion, +} + +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +// align this so it can be passed as a memory message +#[repr(align(4096))] +pub struct CoreInitRkyv { + pub core: BioCore, + pub offset: usize, + pub config: CoreConfigRkyv, + pub code: [u8; 4096], +} + +#[repr(usize)] +#[derive(Copy, Clone, Debug, PartialEq, Eq, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub enum BioCore { + Core0 = 0, + Core1 = 1, + Core2 = 2, + Core3 = 3, +} + +#[repr(usize)] +#[derive(Copy, Clone, Debug, PartialEq, Eq, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub enum CoreRunSetting { + Unchanged = 0, + Start = 1, + Stop = 2, +} + +impl From for BioCore { + fn from(value: usize) -> Self { + match value { + 0 => BioCore::Core0, + 1 => BioCore::Core1, + 2 => BioCore::Core2, + 3 => BioCore::Core3, + _ => panic!("Invalid BioCore value: {}", value), + } + } +} + +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub enum BioError { + /// specified state machine is not valid + InvalidSm, + /// program can't fit in memory, for one reason or another + Oom, + /// no more machines available + NoFreeMachines, + /// Loaded code did not match, first error at argument + CodeCheck(usize), +} + +impl From for BioError { + fn from(error: xous::Error) -> Self { + match error { + xous::Error::OutOfMemory => BioError::Oom, + xous::Error::ServerNotFound => BioError::InvalidSm, + xous::Error::ServerExists => BioError::NoFreeMachines, + // Handle unmapped cases with a panic + _ => panic!("Cannot convert Error::{:?} to BioError", error), + } + } +} + +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct BioPin { + pin_number: u8, +} +impl BioPin { + pub fn pin_number(&self) -> u8 { self.pin_number } + + pub fn new(pin: u8) -> Self { + if pin < 32 { Self { pin_number: pin } } else { panic!("Pin value out of range") } + } +} + +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct CoreConfig { + pub div_int: u16, + pub div_frac: u8, + /// When some, configures use_extclk of the corresponding core to use the GPIO pin specified as the + /// argument + pub quantum_from_pin: Option, +} + +impl From for CoreConfigRkyv { + fn from(config: CoreConfig) -> Self { + CoreConfigRkyv { + div_int: config.div_int, + div_frac: config.div_frac, + quantum_from_pin: config.quantum_from_pin.map(|pin| pin.pin_number().into()), + } + } +} + +impl From for CoreConfig { + fn from(config: CoreConfigRkyv) -> Self { + CoreConfig { + div_int: config.div_int, + div_frac: config.div_frac, + quantum_from_pin: config.quantum_from_pin.map(|pin_num| BioPin::new(pin_num)), + } + } +} + +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct CoreConfigRkyv { + pub div_int: u16, + pub div_frac: u8, + /// When some, configures use_extclk of the corresponding core to use the GPIO pin specified as the + /// argument + pub quantum_from_pin: Option, +} + +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct IoConfig { + /// bits set to `1` here are mapped to the BIO instead of the GPIO + pub mapped: u32, + /// bits set to `1` in the u32 corresponding to BIO inputs passed in as raw, unsynchronized + /// values. This can lead to instability, but reduces latency. + pub sync_bypass: u32, + /// bits set to `1` in the u32 corresponding to BIO outputs that have the OE inverted + pub oe_inv: u32, + /// bits set to `1` in the u32 corresponding to BIO outputs that have the output value inverted + /// compared to the value written into the register + pub o_inv: u32, + /// bits set to `1` in the u32 corresponding to BIO inputs that have the input value inverted + /// before being passed into the register accessed by the core + pub i_inv: u32, + /// When specified all GPIO inputs are aligned to the divided clock of the specified core + pub snap_inputs: Option, + /// When specified all GPIO outputs are aligned to the divided clock of the specified core + pub snap_outputs: Option, +} + +#[bitfield(u8)] +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct TriggerSlot { + #[bits(1..=7)] + _reserved: arbitrary_int::u7, + #[bit(0, rw)] + trigger_slot: arbitrary_int::u1, +} + +#[bitfield(u8)] +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct FifoLevel { + #[bits(3..=7)] + _reserved: arbitrary_int::u5, + #[bits(0..=2, rw)] + level: arbitrary_int::u3, +} + +/// The event register is divided into 24 code-settable event bits + 8 FIFO event bits +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct FifoEventConfig { + // for which FIFO we're configuring its event triggers + pub which: Fifo, + // there are up to two trigger slots per FIFO, specify 0 or 1 here. + pub trigger_slot: TriggerSlot, + // the level used for the triggers. Any number from 0-7. + pub level: FifoLevel, + // when set, the trigger condition happens compared to the level above + pub trigger_less_than: bool, + pub trigger_greater_than: bool, + pub trigger_equal_to: bool, +} + +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct FifoEventConfigRkyv { + // for which FIFO we're configuring its event triggers + pub which: Fifo, + // there are up to two trigger slots per FIFO, specify 0 or 1 here. + pub trigger_slot: bool, + // the level used for the triggers. Any number from 0-7. + pub level: u8, + // when set, the trigger condition happens compared to the level above + pub trigger_less_than: bool, + pub trigger_greater_than: bool, + pub trigger_equal_to: bool, +} + +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub enum Fifo { + Fifo0, + Fifo1, + Fifo2, + Fifo3, +} + +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub enum Irq { + Irq0, + Irq1, + Irq2, + Irq3, +} + +#[bitfield(u32)] +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct IrqMask { + #[bit(31, rw)] + fifo3_trigger1: bool, + #[bit(30, rw)] + fifo3_trigger0: bool, + #[bit(29, rw)] + fifo2_trigger1: bool, + #[bit(28, rw)] + fifo2_trigger0: bool, + #[bit(27, rw)] + fifo1_trigger1: bool, + #[bit(26, rw)] + fifo1_trigger0: bool, + #[bit(25, rw)] + fifo0_trigger1: bool, + #[bit(24, rw)] + fifo0_trigger0: bool, + #[bits(0..=23, rw)] + software: arbitrary_int::u24, +} + +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct IrqConfig { + /// Specifies which of the four BIO IRQ lines are being configured + pub which: Irq, + pub edge_triggered: bool, + /// Bits set to 1 here will cause an interrupt to be passed up when they are set in the + /// aggregated BIO event state. + pub mask: IrqMask, +} + +/// Defines an accessible window by DMA from BIO cores. It's a slice starting from `base` going for `bounds` +/// bytes. +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct DmaWindow { + pub base: u32, + pub bounds: NonZeroU32, +} + +/// Structure that defines all of the windows allowed by the system +#[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] +pub struct DmaFilterWindows { + pub windows: [Option; 4], +} + +/* +#[bitfield(u32)] +pub struct PackedFifoLevels { + #[bits(16..=31)] + _padding: u16, + #[bits(12..=15)] + fifo3_level: arbitrary_int::u4, + #[bits(8..=11)] + fifo2_level: arbitrary_int::u4, + #[bits(4..=7)] + fifo1_level: arbitrary_int::u4, + #[bits(0..=3)] + fifo0_level: arbitrary_int::u4, +} + +#[bitfield(u32)] +pub struct PackedEvent { + #[bits(24..=31)] + _padding: u8, + #[bits(0..=23)] + event: arbitrary_int::u24, +} +/// Memory-mapped structure for a FIFO endpoint. The returned structure +/// is literally mapped on top of the virtual address of the FIFO page starting at offset 0xC. +/// You could also access these fields using the UTRA abstractions, but with the the CSR base +/// set to the FIFO alias region +#[repr(C)] +pub struct FifoHandle { + pub packed_fifo_levels: PackedFifoLevels, + pub tx_fifo: [u32; 4], + pub rx_fifo: [u32; 4], + pub _unused: [u32; 2], + pub set_event: PackedEvent, + pub clear_event: PackedEvent, + pub event_status: PackedEvent, +} +*/ + +pub struct CoreHandle<'a> { + conn: xous::CID, + handle: usize, + _phantom: PhantomData<&'a ()>, +} + +impl<'a> CoreHandle<'a> { + pub fn new(conn: xous::CID, handle: usize) -> Self { Self { conn, handle, _phantom: PhantomData } } + + /// safety: this needs to be wrapped in a hardware-level CSR object that tracks the lifetime of + /// the underlying pointer handle. + pub unsafe fn handle(&self) -> (usize, PhantomData<&'a ()>) { (self.handle, self._phantom) } +} + +impl Drop for CoreHandle<'_> { + fn drop(&mut self) { + xous::send_message( + self.conn, + xous::Message::new_blocking_scalar( + BioOp::ReleaseCoreHandle.to_usize().unwrap(), + self.handle, + 0, + 0, + 0, + ), + ) + .unwrap(); + } +} + +/// A platform-neutral API for the BIO. Intended to be usable in both baremetal and `std` environments +pub trait BioApi<'a> { + /// Initializes a core with the given `code`, loading into `offset`, with a given + /// core configuration. + fn init_core( + &self, + core: BioCore, + code: &[u8], + offset: usize, + config: CoreConfig, + ) -> Result<(), BioError>; + + /// Releases the core. As a side effect, the core is stopped. + fn de_init_core(&self, core: BioCore) -> Result<(), BioError>; + + /// Sets the frequency of the cores, used to calculate dividers etc. + /// Returns the previous frequency used by the system. Setting this frequency + /// allows the sleep/wake clock manager to do a best-effort rescaling of the + /// clock dividers for each core as DVFS is applied for power savings. + fn set_core_freq(&self, freq: u32) -> Result; + + /// Returns the frequency, in Hz, of the incoming clock to the BIO cores. + fn get_freq(&self) -> u32; + + /// The index of `which` corresponds to each of the cores, 0-3. + fn set_core_state(&self, which: [CoreRunSetting; 4]) -> Result<(), BioError>; + + /// Returns a `usize` which should be turned into a CSR as *mut u32 by the caller + /// this can then be dereferenced using UTRA abstractions to access the following + /// registers: + /// - SFR_FLEVEL + /// - SFR_TXF0-3 + /// - SFR_RXF0-3 + /// - SFR_EVENT_SET + /// - SFR_EVENT_CLR + /// - SFR_EVENT_STATUS + /// + /// The handle has a `Drop` implementation that releases it when it goes out of scope. + /// + /// Safety: this has to be wrapped in an object that derives a CSR that also tracks + /// the lifetime of this object, to prevent `Drop` from being called at the wrong time. + unsafe fn get_core_handle(&'a self) -> Result, BioError>; + + /// This call sets up the BIO's IRQ routing. It doesn't actually claim the IRQ + /// or install the handler - that's up to the caller to do with Xous API calls. + fn setup_irq_config(&self, config: IrqConfig) -> Result<(), BioError>; + + /// Allows BIO cores to DMA to/from the windows specified in `windows`. DMA filtering is + /// on by default with no windows allowed. + fn setup_dma_windows(&self, windows: DmaFilterWindows) -> Result<(), BioError>; + + /// Sets up the BIO I/O configuration + fn setup_io_config(&self, config: IoConfig) -> Result<(), BioError>; + + /// Sets up a FIFO event trigger + fn setup_fifo_event_triggers(&self, config: FifoEventConfig) -> Result<(), BioError>; + + /// Returns a version code for the underlying hardware. + fn get_version(&self) -> u32; +} diff --git a/libs/bao1x-api/src/lib.rs b/libs/bao1x-api/src/lib.rs index 241d3efb0..1ad9db0c3 100644 --- a/libs/bao1x-api/src/lib.rs +++ b/libs/bao1x-api/src/lib.rs @@ -21,6 +21,8 @@ pub mod pubkeys; use arbitrary_int::u31; use bitbybit::bitfield; pub use clocks::*; +#[cfg(feature = "std")] +pub mod bio; /// UF2 Family ID. Randomly generated, no collisions with the known list, still to be merged /// into the "official" list