Add new driver implementations and workspace updates

drivers/0x0b_spi_rust/src/board.rs

@@ -0,0 +1,199 @@
+//! @file board.rs
+//! @brief Board-level HAL helpers for the SPI driver
+//! @author Kevin Thomas
+//! @date 2025
+//!
+//! MIT License
+//!
+//! Copyright (c) 2025 Kevin Thomas
+//!
+//! Permission is hereby granted, free of charge, to any person obtaining a copy
+//! of this software and associated documentation files (the "Software"), to deal
+//! in the Software without restriction, including without limitation the rights
+//! to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+//! copies of the Software, and to permit persons to whom the Software is
+//! furnished to do so, subject to the following conditions:
+//!
+//! The above copyright notice and this permission notice shall be included in
+//! all copies or substantial portions of the Software.
+//!
+//! THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//! IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//! FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//! AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//! LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//! OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+//! SOFTWARE.
+
+// SPI pure-logic helpers and constants
+use crate::spi;
+// Digital output trait for software-controlled chip select
+use embedded_hal::digital::OutputPin;
+// SPI bus trait for full-duplex transfer
+use embedded_hal::spi::SpiBus;
+// Rate extension trait for .Hz() baud rate construction
+use fugit::RateExtU32;
+// Clock trait for accessing system clock frequency
+use hal::Clock;
+// GPIO pin types and function selectors
+use hal::gpio::{FunctionNull, FunctionSio, FunctionSpi, FunctionUart, Pin, PullDown, PullNone};
+// SPI peripheral type
+use hal::spi::Spi;
+// UART configuration and peripheral types
+use hal::uart::{DataBits, Enabled, StopBits, UartConfig, UartPeripheral};
+
+// Alias our HAL crate
+#[cfg(rp2350)]
+use rp235x_hal as hal;
+#[cfg(rp2040)]
+use rp2040_hal as hal;
+
+/// External crystal frequency in Hz (12 MHz).
+pub(crate) const XTAL_FREQ_HZ: u32 = 12_000_000u32;
+
+/// UART baud rate in bits per second.
+pub(crate) const UART_BAUD: u32 = 115_200;
+
+/// Delay between loopback transfers in milliseconds.
+pub(crate) const POLL_MS: u32 = 1_000;
+
+/// Type alias for the configured TX pin (GPIO 0, UART function, no pull).
+pub(crate) type TxPin = Pin<hal::gpio::bank0::Gpio0, FunctionUart, PullNone>;
+
+/// Type alias for the configured RX pin (GPIO 1, UART function, no pull).
+pub(crate) type RxPin = Pin<hal::gpio::bank0::Gpio1, FunctionUart, PullNone>;
+
+/// Type alias for the default TX pin state from `Pins::new()`.
+pub(crate) type TxPinDefault = Pin<hal::gpio::bank0::Gpio0, FunctionNull, PullDown>;
+
+/// Type alias for the default RX pin state from `Pins::new()`.
+pub(crate) type RxPinDefault = Pin<hal::gpio::bank0::Gpio1, FunctionNull, PullDown>;
+
+/// Type alias for the configured SPI RX pin (GPIO16).
+pub(crate) type MisoPin = Pin<hal::gpio::bank0::Gpio16, FunctionSpi, PullNone>;
+
+/// Type alias for the configured SPI chip-select pin (GPIO17).
+pub(crate) type CsPin = Pin<hal::gpio::bank0::Gpio17, FunctionSio<hal::gpio::SioOutput>, PullNone>;
+
+/// Type alias for the configured SPI clock pin (GPIO18).
+pub(crate) type SckPin = Pin<hal::gpio::bank0::Gpio18, FunctionSpi, PullNone>;
+
+/// Type alias for the configured SPI TX pin (GPIO19).
+pub(crate) type MosiPin = Pin<hal::gpio::bank0::Gpio19, FunctionSpi, PullNone>;
+
+/// Type alias for the fully-enabled UART0 peripheral with TX/RX pins.
+pub(crate) type EnabledUart = UartPeripheral<Enabled, hal::pac::UART0, (TxPin, RxPin)>;
+
+/// Type alias for the SPI0 peripheral configured in 8-bit master mode.
+pub(crate) type EnabledSpi = Spi<
+    hal::spi::Enabled,
+    hal::pac::SPI0,
+    (MosiPin, MisoPin, SckPin),
+    8,
+>;
+
+/// Initialise system clocks and PLLs from the external 12 MHz crystal.
+pub(crate) fn init_clocks(
+    xosc: hal::pac::XOSC,
+    clocks: hal::pac::CLOCKS,
+    pll_sys: hal::pac::PLL_SYS,
+    pll_usb: hal::pac::PLL_USB,
+    resets: &mut hal::pac::RESETS,
+    watchdog: &mut hal::Watchdog,
+) -> hal::clocks::ClocksManager {
+    hal::clocks::init_clocks_and_plls(
+        XTAL_FREQ_HZ, xosc, clocks, pll_sys, pll_usb, resets, watchdog,
+    )
+    .unwrap()
+}
+
+/// Unlock the GPIO bank and return the pin set.
+pub(crate) fn init_pins(
+    io_bank0: hal::pac::IO_BANK0,
+    pads_bank0: hal::pac::PADS_BANK0,
+    sio: hal::pac::SIO,
+    resets: &mut hal::pac::RESETS,
+) -> hal::gpio::Pins {
+    let sio = hal::Sio::new(sio);
+    hal::gpio::Pins::new(io_bank0, pads_bank0, sio.gpio_bank0, resets)
+}
+
+/// Initialise UART0 for serial output.
+pub(crate) fn init_uart(
+    uart0: hal::pac::UART0,
+    tx_pin: TxPinDefault,
+    rx_pin: RxPinDefault,
+    resets: &mut hal::pac::RESETS,
+    clocks: &hal::clocks::ClocksManager,
+) -> EnabledUart {
+    let pins = (
+        tx_pin.reconfigure::<FunctionUart, PullNone>(),
+        rx_pin.reconfigure::<FunctionUart, PullNone>(),
+    );
+    let cfg = UartConfig::new(UART_BAUD.Hz(), DataBits::Eight, None, StopBits::One);
+    UartPeripheral::new(uart0, pins, resets)
+        .enable(cfg, clocks.peripheral_clock.freq())
+        .unwrap()
+}
+
+/// Create a blocking delay timer from the ARM SysTick peripheral.
+pub(crate) fn init_delay(clocks: &hal::clocks::ClocksManager) -> cortex_m::delay::Delay {
+    let core = cortex_m::Peripherals::take().unwrap();
+    cortex_m::delay::Delay::new(core.SYST, clocks.system_clock.freq().to_Hz())
+}
+
+/// Configure SPI0 and the software-controlled chip-select pin.
+pub(crate) fn init_spi(
+    spi0: hal::pac::SPI0,
+    miso: hal::gpio::Pin<hal::gpio::bank0::Gpio16, FunctionNull, PullDown>,
+    cs: hal::gpio::Pin<hal::gpio::bank0::Gpio17, FunctionNull, PullDown>,
+    sck: hal::gpio::Pin<hal::gpio::bank0::Gpio18, FunctionNull, PullDown>,
+    mosi: hal::gpio::Pin<hal::gpio::bank0::Gpio19, FunctionNull, PullDown>,
+    resets: &mut hal::pac::RESETS,
+    clocks: &hal::clocks::ClocksManager,
+) -> (EnabledSpi, CsPin) {
+    let miso = miso.reconfigure::<FunctionSpi, PullNone>();
+    let sck = sck.reconfigure::<FunctionSpi, PullNone>();
+    let mosi = mosi.reconfigure::<FunctionSpi, PullNone>();
+    let mut cs = cs.reconfigure::<FunctionSio<hal::gpio::SioOutput>, PullNone>();
+    let _ = cs.set_high();
+    let spi = Spi::<_, _, _, 8>::new(spi0, (mosi, miso, sck)).init(
+        resets,
+        clocks.peripheral_clock.freq(),
+        spi::SPI_BAUD_HZ.Hz(),
+        embedded_hal::spi::MODE_0,
+    );
+    (spi, cs)
+}
+
+/// Drive chip select active (low).
+fn cs_select(cs: &mut CsPin) {
+    let _ = cs.set_low();
+}
+
+/// Drive chip select inactive (high).
+fn cs_deselect(cs: &mut CsPin) {
+    let _ = cs.set_high();
+}
+
+/// Perform one SPI loopback transfer and print TX/RX text over UART.
+pub(crate) fn loopback_transfer(
+    spi_dev: &mut EnabledSpi,
+    cs: &mut CsPin,
+    uart: &EnabledUart,
+    delay: &mut cortex_m::delay::Delay,
+) {
+    let tx = spi::TX_MESSAGE;
+    let mut rx = [0u8; spi::TX_MESSAGE.len()];
+    cs_select(cs);
+    let _ = spi_dev.transfer(&mut rx, tx);
+    cs_deselect(cs);
+
+    let mut line_buf = [0u8; 24];
+    let tx_len = spi::format_tx_line(&mut line_buf, tx);
+    uart.write_full_blocking(&line_buf[..tx_len]);
+    let rx_len = spi::format_rx_line(&mut line_buf, &rx);
+    uart.write_full_blocking(&line_buf[..rx_len]);
+    spi::clear_rx_buffer(&mut rx);
+    delay.delay_ms(POLL_MS);
+}

drivers/0x0b_spi_rust/src/lib.rs

@@ -0,0 +1,9 @@
+//! @file lib.rs
+//! @brief Library root for the SPI driver crate
+//! @author Kevin Thomas
+//! @date 2025
+
+#![no_std]
+
+// SPI driver module
+pub mod spi;

drivers/0x0b_spi_rust/src/main.rs

@@ -0,0 +1,115 @@
+//! @file main.rs
+//! @brief SPI loopback demonstration
+//! @author Kevin Thomas
+//! @date 2025
+//!
+//! MIT License
+//!
+//! Copyright (c) 2025 Kevin Thomas
+//!
+//! Permission is hereby granted, free of charge, to any person obtaining a copy
+//! of this software and associated documentation files (the "Software"), to deal
+//! in the Software without restriction, including without limitation the rights
+//! to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+//! copies of the Software, and to permit persons to whom the Software is
+//! furnished to do so, subject to the following conditions:
+//!
+//! The above copyright notice and this permission notice shall be included in
+//! all copies or substantial portions of the Software.
+//!
+//! THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//! IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//! FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//! AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//! LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//! OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+//! SOFTWARE.
+//!
+//! -----------------------------------------------------------------------------
+//!
+//! Demonstrates SPI in master mode using the spi.rs driver. A loopback wiring
+//! of MOSI to MISO verifies full-duplex transfer, and transmitted plus received
+//! data is printed over UART every second.
+//!
+//! Wiring (loopback test):
+//!   GPIO19 (MOSI) -> GPIO16 (MISO)
+//!   GPIO18 (SCK)  -> logic analyzer or slave SCK
+//!   GPIO17 (CS)   -> slave CS (active-low)
+
+#![no_std]
+#![no_main]
+
+// Board-level helpers: constants, type aliases, and init functions
+mod board;
+// SPI driver module — suppress warnings for unused public API functions
+#[allow(dead_code)]
+mod spi;
+
+// Debugging output over RTT
+use defmt_rtt as _;
+// Panic handler for RISC-V targets
+#[cfg(target_arch = "riscv32")]
+use panic_halt as _;
+// Panic handler for ARM targets
+#[cfg(target_arch = "arm")]
+use panic_probe as _;
+
+// HAL entry-point macro
+use hal::entry;
+
+// Alias our HAL crate
+#[cfg(rp2350)]
+use rp235x_hal as hal;
+#[cfg(rp2040)]
+use rp2040_hal as hal;
+
+// Second-stage boot loader for RP2040
+#[unsafe(link_section = ".boot2")]
+#[used]
+#[cfg(rp2040)]
+pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER_W25Q080;
+
+// Boot metadata for the RP2350 Boot ROM
+#[unsafe(link_section = ".start_block")]
+#[used]
+#[cfg(rp2350)]
+pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
+
+/// Application entry point for the SPI loopback demo.
+#[entry]
+fn main() -> ! {
+    let mut pac = hal::pac::Peripherals::take().unwrap();
+    let clocks = board::init_clocks(
+        pac.XOSC, pac.CLOCKS, pac.PLL_SYS, pac.PLL_USB, &mut pac.RESETS,
+        &mut hal::Watchdog::new(pac.WATCHDOG),
+    );
+    let pins = board::init_pins(pac.IO_BANK0, pac.PADS_BANK0, pac.SIO, &mut pac.RESETS);
+    let uart = board::init_uart(pac.UART0, pins.gpio0, pins.gpio1, &mut pac.RESETS, &clocks);
+    let mut delay = board::init_delay(&clocks);
+    let (mut spi_dev, mut cs) = board::init_spi(
+        pac.SPI0,
+        pins.gpio16,
+        pins.gpio17,
+        pins.gpio18,
+        pins.gpio19,
+        &mut pac.RESETS,
+        &clocks,
+    );
+    uart.write_full_blocking(b"SPI driver initialized on SPI0 at 1000000 Hz\r\n");
+    loop {
+        board::loopback_transfer(&mut spi_dev, &mut cs, &uart, &mut delay);
+    }
+}
+
+// Picotool binary info metadata
+#[unsafe(link_section = ".bi_entries")]
+#[used]
+pub static PICOTOOL_ENTRIES: [hal::binary_info::EntryAddr; 5] = [
+    hal::binary_info::rp_cargo_bin_name!(),
+    hal::binary_info::rp_cargo_version!(),
+    hal::binary_info::rp_program_description!(c"SPI Loopback Demo"),
+    hal::binary_info::rp_cargo_homepage_url!(),
+    hal::binary_info::rp_program_build_attribute!(),
+];
+
+// End of file

drivers/0x0b_spi_rust/src/spi.rs

@@ -0,0 +1,150 @@
+//! @file spi.rs
+//! @brief Implementation of the SPI loopback driver helper logic
+//! @author Kevin Thomas
+//! @date 2025
+//!
+//! MIT License
+//!
+//! Copyright (c) 2025 Kevin Thomas
+//!
+//! Permission is hereby granted, free of charge, to any person obtaining a copy
+//! of this software and associated documentation files (the "Software"), to deal
+//! in the Software without restriction, including without limitation the rights
+//! to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+//! copies of the Software, and to permit persons to whom the Software is
+//! furnished to do so, subject to the following conditions:
+//!
+//! The above copyright notice and this permission notice shall be included in
+//! all copies or substantial portions of the Software.
+//!
+//! THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//! IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//! FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//! AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//! LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//! OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+//! SOFTWARE.
+
+/// SPI port number used by the loopback demo.
+pub const SPI_PORT: u8 = 0;
+
+/// SPI clock frequency used by the loopback demo.
+pub const SPI_BAUD_HZ: u32 = 1_000_000;
+
+/// GPIO pin number for MISO.
+pub const PIN_MISO: u8 = 16;
+
+/// GPIO pin number for chip select.
+pub const PIN_CS: u8 = 17;
+
+/// GPIO pin number for SCK.
+pub const PIN_SCK: u8 = 18;
+
+/// GPIO pin number for MOSI.
+pub const PIN_MOSI: u8 = 19;
+
+/// Fixed transmit message used by the SPI loopback demo.
+pub const TX_MESSAGE: &[u8; 16] = b"SPI loopback OK\0";
+
+/// Return true when the selected SPI port is supported by the driver.
+pub fn is_valid_port(port: u8) -> bool {
+    port <= 1
+}
+
+/// Clear a receive buffer to all zeros.
+pub fn clear_rx_buffer(rx: &mut [u8]) {
+    rx.fill(0);
+}
+
+/// Copy `src` into `dst` up to the minimum length of both slices.
+pub fn copy_transfer_result(src: &[u8], dst: &mut [u8]) {
+    let len = core::cmp::min(src.len(), dst.len());
+    dst[..len].copy_from_slice(&src[..len]);
+}
+
+/// Format the `TX:` line with trailing CRLF.
+pub fn format_tx_line(buf: &mut [u8], tx: &[u8]) -> usize {
+    format_line(buf, b"TX: ", tx, false)
+}
+
+/// Format the `RX:` line with an extra blank line after it.
+pub fn format_rx_line(buf: &mut [u8], rx: &[u8]) -> usize {
+    format_line(buf, b"RX: ", rx, true)
+}
+
+/// Format a single ASCII line for UART output.
+fn format_line(buf: &mut [u8], prefix: &[u8], text: &[u8], extra_blank_line: bool) -> usize {
+    let mut pos = 0;
+    buf[pos..pos + prefix.len()].copy_from_slice(prefix);
+    pos += prefix.len();
+    let text_len = c_string_len(text);
+    buf[pos..pos + text_len].copy_from_slice(&text[..text_len]);
+    pos += text_len;
+    buf[pos] = b'\r';
+    pos += 1;
+    buf[pos] = b'\n';
+    pos += 1;
+    if extra_blank_line {
+        buf[pos] = b'\r';
+        pos += 1;
+        buf[pos] = b'\n';
+        pos += 1;
+    }
+    pos
+}
+
+/// Return the length up to the first NUL byte or full slice length.
+fn c_string_len(text: &[u8]) -> usize {
+    let mut len = 0usize;
+    while len < text.len() && text[len] != 0 {
+        len += 1;
+    }
+    len
+}
+
+#[cfg(test)]
+mod tests {
+    // Import all parent module items
+    use super::*;
+
+    #[test]
+    fn valid_ports_are_zero_and_one() {
+        assert!(is_valid_port(0));
+        assert!(is_valid_port(1));
+        assert!(!is_valid_port(2));
+    }
+
+    #[test]
+    fn clear_rx_buffer_zeroes_all_bytes() {
+        let mut rx = [1u8, 2, 3, 4];
+        clear_rx_buffer(&mut rx);
+        assert_eq!(rx, [0u8; 4]);
+    }
+
+    #[test]
+    fn copy_transfer_result_copies_common_prefix() {
+        let src = b"abcd";
+        let mut dst = [0u8; 3];
+        copy_transfer_result(src, &mut dst);
+        assert_eq!(&dst, b"abc");
+    }
+
+    #[test]
+    fn format_tx_line_omits_trailing_nul() {
+        let mut buf = [0u8; 32];
+        let n = format_tx_line(&mut buf, TX_MESSAGE);
+        assert_eq!(&buf[..n], b"TX: SPI loopback OK\r\n");
+    }
+
+    #[test]
+    fn format_rx_line_adds_blank_line() {
+        let mut buf = [0u8; 32];
+        let n = format_rx_line(&mut buf, TX_MESSAGE);
+        assert_eq!(&buf[..n], b"RX: SPI loopback OK\r\n\r\n");
+    }
+
+    #[test]
+    fn c_string_len_stops_at_nul() {
+        assert_eq!(c_string_len(b"abc\0xyz"), 3);
+    }
+}