Add USDHC1 SD card support for Teensy 4.1

Integrate the imxrt-usdhc driver crate into the BSP:
- Configure USDHC1 root clock (PLL2_PFD2 / 2 = 198 MHz)
- Add USDHC1 instance to board Resources
- Add usdhc1 module with pin config and init_usdhc1() convenience fn
- Re-export embedded_sdmmc, Usdhc, SdPins, etc. from board module
- Add rtic_sd_info example (card init + FAT32 root dir listing)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tacertain

Cargo.toml

@@ -51,6 +51,9 @@ optional = true
 workspace = true
 optional = true
 
+[dependencies.imxrt-usdhc]
+path = "../imxrt-usdhc"
+
 [dependencies.teensy4-pins]
 version = "0.3.1"
 path = "teensy4-pins"
@@ -151,3 +154,8 @@ required-features = ["rt"]
 [[example]]
 name = "rtic_usb_log"
 required-features = ["rt"]
+
+[[example]]
+name = "rtic_sd_info"
+required-features = ["rt"]
+

examples/rtic_sd_info.rs

@@ -0,0 +1,147 @@
+//! Demonstrates SD card initialization on the Teensy 4.1.
+//!
+//! Insert a FAT32-formatted SD card, flash this example, and connect to the
+//! USB serial port to see card info and a root directory listing.
+//!
+//! This example requires a Teensy 4.1 (which has the built-in micro-SD slot).
+
+#![no_std]
+#![no_main]
+
+use teensy4_panic as _;
+
+#[rtic::app(device = teensy4_bsp, peripherals = true, dispatchers = [KPP])]
+mod app {
+    use bsp::board;
+    use teensy4_bsp as bsp;
+
+    use board::embedded_sdmmc;
+    use imxrt_log as logging;
+    use rtic_monotonics::systick::*;
+
+    /// Dummy time source for FAT timestamps.
+    struct FakeTime;
+
+    impl embedded_sdmmc::TimeSource for FakeTime {
+        fn get_timestamp(&self) -> embedded_sdmmc::Timestamp {
+            embedded_sdmmc::Timestamp {
+                year_since_1970: 56, // 2026
+                zero_indexed_month: 2,
+                zero_indexed_day: 29,
+                hours: 0,
+                minutes: 0,
+                seconds: 0,
+            }
+        }
+    }
+
+    #[local]
+    struct Local {
+        poller: logging::Poller,
+        led: board::Led,
+        sd: Option<board::Usdhc>,
+    }
+
+    #[shared]
+    struct Shared {}
+
+    #[init]
+    fn init(cx: init::Context) -> (Shared, Local) {
+        let board::Resources {
+            usb,
+            pins,
+            mut gpio2,
+            usdhc1,
+            ..
+        } = board::t41(cx.device);
+        let led = board::led(&mut gpio2, pins.p13);
+
+        let poller = logging::log::usbd(usb, logging::Interrupts::Enabled).unwrap();
+
+        Systick::start(
+            cx.core.SYST,
+            board::ARM_FREQUENCY,
+            rtic_monotonics::create_systick_token!(),
+        );
+
+        // Initialize SD card during init (blocking, before USB is up).
+        // The result is passed to the sd_info task for logging once
+        // the USB host has had time to connect.
+        let sd_pins = board::SdPins {
+            cmd: pins.p45,
+            clk: pins.p44,
+            data0: pins.p43,
+            data1: pins.p42,
+            data2: pins.p47,
+            data3: pins.p46,
+        };
+
+        let sd = match board::init_usdhc1(usdhc1, sd_pins) {
+            Ok(sd) => Some(sd),
+            Err(e) => {
+                // Can't log yet — USB isn't enumerated. The sd_info task
+                // will detect None and report the failure.
+                let _ = e;
+                None
+            }
+        };
+
+        sd_info::spawn().unwrap();
+        led.set();
+
+        (Shared {}, Local { poller, led, sd })
+    }
+
+    /// Wait for the USB host to connect, then log SD card info.
+    #[task(local = [sd])]
+    async fn sd_info(cx: sd_info::Context) {
+        // Give the host time to enumerate the USB device and open the serial port.
+        Systick::delay(2000.millis()).await;
+
+        let Some(sd) = cx.local.sd.take() else {
+            log::error!("SD card not initialized (no card or init failed)");
+            return;
+        };
+
+        log::info!(
+            "SD card: {:?}, {} MB ({} blocks)",
+            sd.card_type(),
+            sd.capacity_mb(),
+            sd.block_count(),
+        );
+
+        let volume_mgr = embedded_sdmmc::VolumeManager::new(sd, FakeTime);
+
+        match volume_mgr.open_raw_volume(embedded_sdmmc::VolumeIdx(0)) {
+            Ok(volume) => {
+                match volume_mgr.open_root_dir(volume) {
+                    Ok(root_dir) => {
+                        log::info!("Root directory:");
+                        let _ = volume_mgr.iterate_dir(root_dir, |entry| {
+                            log::info!("  {}", entry.name);
+                        });
+                        let _ = volume_mgr.close_dir(root_dir);
+                    }
+                    Err(e) => log::error!("open root dir: {:?}", e),
+                }
+                let _ = volume_mgr.close_volume(volume);
+            }
+            Err(e) => log::error!("open volume: {:?}", e),
+        }
+
+        log::info!("Done.");
+    }
+
+    #[task(local = [led])]
+    async fn blink(cx: blink::Context) {
+        loop {
+            cx.local.led.toggle();
+            Systick::delay(500.millis()).await;
+        }
+    }
+
+    #[task(binds = USB_OTG1, local = [poller])]
+    fn usb_interrupt(cx: usb_interrupt::Context) {
+        cx.local.poller.poll();
+    }
+}

src/board.rs

@@ -299,6 +299,13 @@ pub struct Resources<Pins> {
     pub sai3: ral::sai::SAI3,
     /// The IOMUXC general purpose register block.
     pub iomuxc_gpr: ral::iomuxc_gpr::IOMUXC_GPR,
+    /// The USDHC1 peripheral instance.
+    ///
+    /// The Teensy 4.1 has a built-in micro-SD card slot connected to
+    /// USDHC1 (pins p42–p47). Use this with [`init_usdhc1`] to create
+    /// an SD card driver. See [`USDHC1_FREQUENCY`] for the configured
+    /// root clock frequency.
+    pub usdhc1: ral::usdhc::USDHC1,
 }
 
 /// The board's dedicated LED.
@@ -689,6 +696,7 @@ fn prepare_resources<Pins>(
         sai2: instances.SAI2,
         sai3: instances.SAI3,
         iomuxc_gpr: instances.IOMUXC_GPR,
+        usdhc1: instances.USDHC1,
     }
 }
 
@@ -715,3 +723,5 @@ pub fn t41(instances: impl Into<Instances>) -> T41Resources {
 pub fn tmm(instances: impl Into<Instances>) -> TMMResources {
     prepare_resources(instances.into(), pins::tmm::from_pads)
 }
+
+pub use crate::usdhc1::{embedded_sdmmc, init_usdhc1, CardType, SdError, SdPins, Usdhc};

src/clock_power.rs

@@ -267,6 +267,7 @@ const CLOCK_GATES: &[clock_gate::Locator] = &[
     clock_gate::sai::<1>(),
     clock_gate::sai::<2>(),
     clock_gate::sai::<3>(),
+    clock_gate::usdhc::<1>(),
 ];
 
 /// Prepare clocks and power for the MCU.
@@ -289,8 +290,25 @@ pub fn prepare_clocks_and_power(
     setup_uart_clk(ccm);
     setup_audio_pll(ccm_analog);
     setup_sai1_clk(ccm);
+    setup_usdhc1_clk(ccm);
 
     CLOCK_GATES
         .iter()
         .for_each(|locator| locator.set(ccm, clock_gate::ON));
 }
+
+/// USDHC1 root clock frequency (Hz).
+///
+/// PLL2_PFD2 (396 MHz) / 2 = 198 MHz. The actual SD bus clock is
+/// further divided by the USDHC1 peripheral's internal SDCLKFS and
+/// DVS dividers during card initialization.
+pub const USDHC1_FREQUENCY: u32 = 198_000_000;
+
+/// Configure the USDHC1 clock root for the SD card slot.
+///
+/// Source: PLL2_PFD2 (396 MHz), divider: /2 → 198 MHz root clock.
+fn setup_usdhc1_clk(ccm: &mut ral::ccm::CCM) {
+    clock_gate::usdhc::<1>().set(ccm, clock_gate::OFF);
+    ral::modify_reg!(ral::ccm, ccm, CSCMR1, USDHC1_CLK_SEL: 0); // PLL2_PFD2
+    ral::modify_reg!(ral::ccm, ccm, CSCDR1, USDHC1_PODF: 1); // divide by 2
+}

src/lib.rs

@@ -111,6 +111,7 @@ pub use ral::{interrupt, Interrupt, NVIC_PRIO_BITS};
 
 pub mod board;
 mod clock_power;
+mod usdhc1;
 
 /// SYSTICK external clock frequency.
 ///

src/usdhc1.rs

@@ -0,0 +1,38 @@
+//! BSP-level SD card support for the Teensy 4.1.
+//!
+//! This module provides pin configuration and a convenience initializer
+//! for the USDHC1 peripheral. The driver implementation lives in the
+//! [`imxrt_usdhc`] crate.
+
+use crate::{hal, pins, ral};
+
+pub use imxrt_usdhc::{embedded_sdmmc, CardType, SdError, Usdhc};
+
+/// SD card pins for USDHC1 on the Teensy 4.1 (pins p42–p47).
+pub struct SdPins {
+    pub cmd: pins::t41::P45,
+    pub clk: pins::t41::P44,
+    pub data0: pins::t41::P43,
+    pub data1: pins::t41::P42,
+    pub data2: pins::t41::P47,
+    pub data3: pins::t41::P46,
+}
+
+/// Initialize the USDHC1 peripheral and SD card on the Teensy 4.1.
+///
+/// Configures the SD card pins and delegates to [`imxrt_usdhc::Usdhc::new`].
+/// The USDHC1 clock gate and root clock are already configured by
+/// [`t41`](crate::board::t41).
+pub fn init_usdhc1(
+    usdhc1: ral::usdhc::USDHC1,
+    mut sd_pins: SdPins,
+) -> Result<Usdhc, SdError> {
+    hal::iomuxc::usdhc::prepare(&mut sd_pins.cmd);
+    hal::iomuxc::usdhc::prepare(&mut sd_pins.clk);
+    hal::iomuxc::usdhc::prepare(&mut sd_pins.data0);
+    hal::iomuxc::usdhc::prepare(&mut sd_pins.data1);
+    hal::iomuxc::usdhc::prepare(&mut sd_pins.data2);
+    hal::iomuxc::usdhc::prepare(&mut sd_pins.data3);
+
+    imxrt_usdhc::Usdhc::new(usdhc1, crate::clock_power::USDHC1_FREQUENCY)
+}