Skip to main content

esp_hal/sdmmc/
mod.rs

1//! # Secure Digital / MultiMedia Card host (SDMMC / SDIO)
2//!
3//! ## Overview
4//!
5//! Driver for the SDMMC/SDIO host controller (`SDHOST`). The controller exposes
6//! up to two independent card slots that share a single transfer engine.
7//!
8//! Blocking engine operations return [`BlockingError`]; [`BlockingError::Busy`]
9//! if another slot or an async transfer holds the engine. Async ops await the
10//! engine mutex instead. Bus width and card clock are cached and applied on
11//! engine acquire (lock order: engine, then settings).
12//!
13//! ## Configuration
14//!
15//! [`SdHostController::new`] takes a [`Config`] for the shared module clock.
16//! Each slot is obtained via [`SdHostController::slot`] with a [`SlotConfig`],
17//! then wired with `with_clk`, `with_cmd`, `with_data*`, and optional
18//! card-detect / write-protect pins.
19//!
20//! ## Usage
21//!
22//! Blocking commands and block transfers are available on [`Slot`] in
23//! [`Blocking`] mode. [`Slot::into_async`] enables interrupt-driven operation
24//! and implements [`sdio::MmcBus`] for the `sdio` crate stack.
25//!
26//! ## Implementation State
27//!
28//! SDIO device (I/O) mode is supported via [`sdio::MmcBus`]. SPI mode and
29//! UHS-I (1.8 V switching) are not implemented.
30
31use core::{
32    cell::UnsafeCell,
33    future::poll_fn,
34    marker::PhantomData,
35    pin::Pin,
36    sync::atomic::Ordering,
37    task::{Context, Poll},
38};
39
40use embassy_sync::{mutex::MutexGuard, waitqueue::WakerRegistration};
41use esp_sync::{NonReentrantMutex, RawMutex};
42use portable_atomic::AtomicBool;
43use procmacros::{BuilderLite, handler};
44use sdio::{self as _, MmcError};
45
46#[cfg(sdmmc_has_gpio_matrix)]
47use crate::gpio::{OutputSignal, PinGuard, Pull};
48use crate::{
49    Async,
50    Blocking,
51    DriverMode,
52    asynch::{AtomicWaker, wait_until},
53    clock::CpuFrequencyLock,
54    dma::{
55        DmaBufError,
56        aligned::{DmaAlignedMut, DmaAlignedRef, InternalMemory},
57    },
58    gpio::{
59        InputSignal,
60        OutputConfig,
61        interconnect::{self, PeripheralInput, PeripheralOutput},
62    },
63    peripherals::{Interrupt, SDHOST},
64    private::DropGuard,
65    system::{Peripheral, PeripheralGuard},
66    time::{Duration, Instant},
67};
68
69#[cfg_attr(esp32, path = "esp32.rs")]
70#[cfg_attr(esp32s3, path = "esp32s3.rs")]
71#[cfg_attr(esp32p4, path = "esp32p4.rs")]
72#[cfg_attr(esp32s31, path = "esp32s31.rs")]
73mod chip_specific;
74
75#[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
76mod bounce;
77
78/// Card clock source feeding the controller's divider.
79#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
80#[cfg_attr(feature = "defmt", derive(defmt::Format))]
81pub enum ClockSource {
82    /// 160 MHz PLL.
83    #[cfg(not(esp32s31))]
84    Pll160m,
85    /// Configured MPLL clock.
86    #[cfg(esp32s31)]
87    Mpll,
88    /// Crystal oscillator.
89    #[cfg(not(esp32p4))]
90    Xtal,
91}
92
93/// Clocks input sampling phase used for high-speed tuning.
94#[cfg(sdmmc_delay_phase_num_is_set)]
95#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
96#[cfg_attr(feature = "defmt", derive(defmt::Format))]
97pub enum DelayPhase {
98    /// 0°.
99    #[default]
100    _0,
101    /// 90°.
102    _1,
103    /// 180°.
104    _2,
105    /// 270°.
106    _3,
107}
108
109/// Card data bus width.
110#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
111#[cfg_attr(feature = "defmt", derive(defmt::Format))]
112pub enum BusWidth {
113    /// 1-bit bus (DAT0 only).
114    #[default]
115    Bit1,
116    /// 4-bit bus (DAT0–DAT3).
117    Bit4,
118    /// 8-bit bus (DAT0–DAT7, Card slot 0 only).
119    Bit8,
120}
121
122/// Controller-wide (engine) configuration.
123///
124/// These settings drive the shared module clock and therefore apply to the
125/// whole controller, not an individual slot.
126#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, BuilderLite)]
127#[cfg_attr(feature = "defmt", derive(defmt::Format))]
128#[non_exhaustive]
129pub struct Config {
130    /// The clock source for the module clock.
131    clock_source: ClockSource,
132
133    /// The module-clock divider (valid range `2..=16`).
134    module_div: u8,
135}
136
137impl Default for Config {
138    fn default() -> Self {
139        Self::const_default()
140    }
141}
142
143impl Config {
144    pub(crate) const fn const_default() -> Self {
145        cfg_select! {
146            esp32s31 => Self {
147                clock_source: ClockSource::Mpll,
148                module_div: 8,
149            },
150            _ => Self {
151                clock_source: ClockSource::Pll160m,
152                module_div: 2,
153            },
154        }
155    }
156
157    /// Validates field ranges.
158    fn validate(&self) -> Result<(), ConfigError> {
159        if !(2..=16).contains(&self.module_div) {
160            return Err(ConfigError::InvalidModuleDivider);
161        }
162        Ok(())
163    }
164}
165
166/// Per-slot configuration.
167#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, BuilderLite)]
168#[cfg_attr(feature = "defmt", derive(defmt::Format))]
169#[non_exhaustive]
170pub struct SlotConfig {
171    /// Input sampling delay phase used for high-speed tuning.
172    #[cfg(sdmmc_delay_phase_num_is_set)]
173    input_delay_phase: DelayPhase,
174
175    /// Write-protect signal polarity (active-high or active-low).
176    wp_active_high: bool,
177}
178
179/// Length of the response a command expects.
180#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
181#[cfg_attr(feature = "defmt", derive(defmt::Format))]
182pub enum ResponseLen {
183    /// No response.
184    None,
185    /// Short 48-bit response (`resp[0]`).
186    Short,
187    /// Long 136-bit response (`resp[0..4]`).
188    Long,
189}
190
191/// Per-command engine flags.
192#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
193#[cfg_attr(feature = "defmt", derive(defmt::Format))]
194pub struct CommandFlags {
195    /// Waits for the data line to be free before issuing.
196    pub wait_complete: bool,
197    /// Stop/abort command (CMD12, CMD52 abort).
198    pub stop_abort: bool,
199    /// Polls DAT0 until the card releases busy (R1b).
200    pub busy: bool,
201}
202
203/// Error returned by host operations.
204#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
205#[cfg_attr(feature = "defmt", derive(defmt::Format))]
206#[non_exhaustive]
207#[expect(clippy::enum_variant_names)]
208pub enum Error {
209    /// A hardware operation did not complete in time.
210    Timeout,
211    /// Response CRC check failed.
212    ResponseCrc,
213    /// Data CRC or end-bit error.
214    DataCrc,
215    /// Card did not respond to the command.
216    ResponseTimeout,
217    /// Data transfer timed out.
218    DataTimeout,
219    /// FIFO under- or overrun during a transfer.
220    FifoOverrun,
221    /// Data start-bit error.
222    StartBitError,
223    /// Command could not be loaded (hardware locked).
224    HardwareLocked,
225    /// Controller flagged a response error.
226    ResponseError,
227    /// IDMAC transfer error.
228    DmaError,
229    /// No card present in the slot.
230    NoCard,
231    /// Buffer lies in a region the IDMAC cannot reach.
232    BufferNotDmaCapable,
233    /// Operation not supported.
234    Unsupported,
235}
236
237impl core::error::Error for Error {}
238
239impl core::fmt::Display for Error {
240    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
241        match self {
242            Error::Timeout => write!(f, "A hardware operation did not complete in time"),
243            Error::ResponseCrc => write!(f, "Response CRC check failed"),
244            Error::DataCrc => write!(f, "Data CRC or end-bit error"),
245            Error::ResponseTimeout => write!(f, "Card did not respond to the command"),
246            Error::DataTimeout => write!(f, "Data transfer timed out"),
247            Error::FifoOverrun => write!(f, "FIFO under- or overrun during a transfer"),
248            Error::StartBitError => write!(f, "Data start-bit error"),
249            Error::HardwareLocked => write!(f, "Command could not be loaded (hardware locked)"),
250            Error::ResponseError => write!(f, "Controller flagged a response error"),
251            Error::DmaError => write!(f, "IDMAC transfer error"),
252            Error::NoCard => write!(f, "No card present in the slot"),
253            Error::BufferNotDmaCapable => {
254                write!(f, "Buffer lies in a region the IDMAC cannot reach")
255            }
256            Error::Unsupported => write!(f, "Operation not supported"),
257        }
258    }
259}
260
261/// Error returned when applying a [`Config`].
262#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
263#[cfg_attr(feature = "defmt", derive(defmt::Format))]
264#[non_exhaustive]
265pub enum ConfigError {
266    /// Module-clock divider is outside `2..=16`.
267    InvalidModuleDivider,
268    /// The slot is already in use.
269    SlotInUse,
270    /// The clock or command pin was not connected.
271    MissingClkOrCmd,
272    /// Data line 0 was not connected.
273    NoData0,
274}
275
276impl core::error::Error for ConfigError {}
277
278impl core::fmt::Display for ConfigError {
279    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
280        match self {
281            ConfigError::InvalidModuleDivider => {
282                write!(f, "Module-clock divider is outside 2..=16")
283            }
284            ConfigError::SlotInUse => write!(f, "The slot is already in use"),
285            ConfigError::MissingClkOrCmd => write!(f, "The clock or command pin was not connected"),
286            ConfigError::NoData0 => write!(f, "Data line 0 was not connected"),
287        }
288    }
289}
290
291/// Error from blocking engine operations ([`BlockingError::Busy`] is mutex contention, not CIU
292/// HLE).
293#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
294#[cfg_attr(feature = "defmt", derive(defmt::Format))]
295#[non_exhaustive]
296pub enum BlockingError {
297    /// The shared engine is held by another slot or an async transfer.
298    Busy,
299    /// The operation failed after the engine was acquired.
300    Op(Error),
301}
302
303impl core::error::Error for BlockingError {}
304
305impl core::fmt::Display for BlockingError {
306    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
307        match self {
308            BlockingError::Busy => write!(f, "The shared SDMMC engine is busy"),
309            BlockingError::Op(e) => write!(f, "{e}"),
310        }
311    }
312}
313
314impl From<Error> for BlockingError {
315    fn from(error: Error) -> Self {
316        BlockingError::Op(error)
317    }
318}
319
320impl From<BlockingError> for MmcError {
321    fn from(error: BlockingError) -> Self {
322        match error {
323            BlockingError::Busy => MmcError::Other,
324            BlockingError::Op(e) => e.into(),
325        }
326    }
327}
328
329impl From<Error> for MmcError {
330    fn from(error: Error) -> Self {
331        warn!("{:?}", error);
332        match error {
333            Error::ResponseTimeout | Error::DataTimeout | Error::Timeout | Error::NoCard => {
334                MmcError::Timeout
335            }
336            Error::ResponseCrc | Error::DataCrc | Error::StartBitError => MmcError::Crc,
337            Error::FifoOverrun
338            | Error::DmaError
339            | Error::ResponseError
340            | Error::BufferNotDmaCapable => MmcError::Io,
341            Error::HardwareLocked => MmcError::Other,
342            Error::Unsupported => MmcError::Unsupported,
343        }
344    }
345}
346
347impl From<DmaBufError> for MmcError {
348    fn from(error: DmaBufError) -> Self {
349        warn!("{:?}", error);
350        match error {
351            DmaBufError::InvalidAlignment(_) => MmcError::Other,
352            _ => MmcError::Io,
353        }
354    }
355}
356
357/// Spin-poll bound for self-clearing hardware bits.
358const POLL_LIMIT: u32 = 1_000_000;
359
360/// Upper bound for the card to release DAT0 after an R1b command in async mode.
361///
362/// Generous because `CMD38` (erase) is R1b and may keep the card busy for seconds.
363const BUSY_TIMEOUT: Duration = Duration::from_secs(5);
364
365/// Interval between DAT0 busy checks in async mode.
366const BUSY_POLL_INTERVAL: Duration = Duration::from_micros(100);
367
368// `rintsts` event bits (see `sdmmc_ll.h` `SDMMC_LL_EVENT_*`).
369const EVT_RESP_ERR: u32 = 1 << 1;
370const EVT_CMD_DONE: u32 = 1 << 2;
371const EVT_DATA_OVER: u32 = 1 << 3;
372const EVT_RCRC: u32 = 1 << 6;
373const EVT_DCRC: u32 = 1 << 7;
374const EVT_RTO: u32 = 1 << 8;
375const EVT_DTO: u32 = 1 << 9;
376const EVT_HTO: u32 = 1 << 10;
377const EVT_FRUN: u32 = 1 << 11;
378const EVT_HLE: u32 = 1 << 12;
379const EVT_SBE: u32 = 1 << 13;
380const EVT_ACD: u32 = 1 << 14;
381const EVT_EBE: u32 = 1 << 15;
382
383// `ctrl` IDMAC-enable bits not modeled by the PAC (raw writes only).
384const CTRL_DMA_ENABLE: u32 = 1 << 5;
385const CTRL_USE_INTERNAL_DMA: u32 = 1 << 25;
386
387/// IDMAC descriptor count in the driver-owned ring.
388const RING_LEN: usize = 4;
389/// Maximum bytes per descriptor (`SDMMC_DMA_MAX_BUF_LEN`).
390const DMA_MAX_BUF_LEN: usize = 4096;
391
392// `Desc.flags` bits (see `sdmmc_desc_t`).
393const DESC_LAST: u32 = 1 << 2;
394const DESC_FIRST: u32 = 1 << 3;
395const DESC_CHAINED: u32 = 1 << 4;
396const DESC_OWN: u32 = 1 << 31;
397
398/// One 16-byte IDMAC linked-list descriptor.
399#[repr(C, align(4))]
400#[derive(Clone, Copy)]
401struct Desc {
402    flags: u32,
403    sizes: u32,
404    buf1: u32,
405    next: u32,
406}
407
408impl Desc {
409    const ZERO: Self = Desc {
410        flags: 0,
411        sizes: 0,
412        buf1: 0,
413        next: 0,
414    };
415}
416
417/// One contiguous DMA segment: `(buffer address, remaining bytes)`.
418type Seg = (u32, usize);
419
420/// Tracks progress while filling the descriptor ring.
421///
422/// A transfer is described as up to three back-to-back segments so that a
423/// cache-unaligned caller buffer can still be DMA'd: the aligned middle is
424/// transferred in place, while the unaligned head and tail are bounced
425/// through an aligned scratch buffer. A fully aligned buffer uses a single
426/// segment ([`Transfer::single`]) and the other two are left empty.
427#[derive(Clone, Copy)]
428struct Transfer {
429    segs: [Seg; 3],
430    /// Index of the segment currently being linked into descriptors.
431    seg: usize,
432    next_desc: usize,
433}
434
435impl Transfer {
436    /// A single, already-DMA-capable contiguous segment.
437    fn single(ptr: u32, len: usize) -> Self {
438        Transfer {
439            segs: [(ptr, len), (0, 0), (0, 0)],
440            seg: 0,
441            next_desc: 0,
442        }
443    }
444
445    /// Head / middle / tail segments; any zero-length entry is skipped while
446    /// filling descriptors.
447    #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
448    fn split(head: Seg, middle: Seg, tail: Seg) -> Self {
449        Transfer {
450            segs: [head, middle, tail],
451            seg: 0,
452            next_desc: 0,
453        }
454    }
455
456    /// Bytes not yet linked into a descriptor. Before any descriptor is
457    /// filled this equals the total transfer length.
458    fn remaining(&self) -> usize {
459        self.segs.iter().map(|(_, len)| *len).sum()
460    }
461}
462
463/// Driver-owned descriptor ring in internal DMA-capable RAM.
464struct DescRing(UnsafeCell<InternalMemory<[Desc; RING_LEN]>>);
465// Access only while `ENGINE` is held.
466unsafe impl Sync for DescRing {}
467
468static DESC_RING: DescRing = DescRing(UnsafeCell::new(InternalMemory::new([Desc::ZERO; RING_LEN])));
469
470fn ring() -> DmaAlignedMut<'static, [Desc; RING_LEN]> {
471    unsafe { &mut *DESC_RING.0.get() }.get_mut()
472}
473
474/// Exclusive engine session: bounce scratch and last HW-programmed slot.
475struct EngineSession {
476    #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
477    bounce: bounce::Bounce,
478    active_slot: Option<SlotId>,
479}
480
481impl EngineSession {
482    const INIT: Self = EngineSession {
483        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
484        bounce: bounce::Bounce::INIT,
485        active_slot: None,
486    };
487
488    fn select_and_apply(&mut self, slot: SlotId) -> Result<(), Error> {
489        let wait = SETTINGS.with(|s| {
490            let idx = slot.index() as usize;
491            let cached = &mut s.slots[idx];
492            if self.active_slot == Some(slot) && !cached.dirty {
493                return Ok(false);
494            }
495            self.program_slot_hw(slot, cached, s.module)?;
496            cached.dirty = false;
497            self.active_slot = Some(slot);
498            Ok(true)
499        })?;
500
501        if wait {
502            crate::rom::ets_delay_us(10);
503        }
504        Ok(())
505    }
506
507    fn program_slot_hw(
508        &mut self,
509        slot: SlotId,
510        cached: &SlotSettings,
511        module: Config,
512    ) -> Result<(), Error> {
513        self.set_card_width(slot, cached.width);
514        let card_div =
515            freq_to_card_div(module_hz(module.clock_source, module.module_div), cached.hz);
516        self.set_card_clock(slot, card_div)?;
517        #[cfg(sdmmc_delay_phase_num_is_set)]
518        if cached.hz > 25_000_000 {
519            chip_specific::set_input_delay_phase(cached.input_delay_phase, cached.hz);
520        }
521        Ok(())
522    }
523
524    fn set_card_width(&mut self, id: SlotId, width: BusWidth) {
525        let slot = id.index();
526        SDHOST::regs().ctype().modify(|rd, w| unsafe {
527            let mut w4 = rd.card_width4().bits() & !(1 << slot);
528            let mut w8 = rd.card_width8().bits() & !(1 << slot);
529            match width {
530                BusWidth::Bit8 => w8 |= 1 << slot,
531                BusWidth::Bit4 => w4 |= 1 << slot,
532                BusWidth::Bit1 => {}
533            }
534            w.card_width4().bits(w4);
535            w.card_width8().bits(w8)
536        });
537    }
538
539    fn set_card_clock(&mut self, id: SlotId, card_div: u8) -> Result<(), Error> {
540        let slot = id.index();
541        let r = SDHOST::regs();
542
543        r.clkena().modify(|rd, w| unsafe {
544            w.cclk_enable().bits(rd.cclk_enable().bits() & !(1 << slot))
545        });
546        self.apply_clock_update(id)?;
547
548        r.clksrc().modify(|rd, w| unsafe {
549            let mut v = rd.clksrc().bits();
550            match id {
551                SlotId::_0 => v &= !0b11,
552                SlotId::_1 => {
553                    v &= !0b1100;
554                    v |= 1 << 2;
555                }
556            }
557            w.clksrc().bits(v)
558        });
559        r.clkdiv().modify(|_, w| unsafe {
560            match id {
561                SlotId::_0 => w.clk_divider0().bits(card_div),
562                SlotId::_1 => w.clk_divider1().bits(card_div),
563            }
564        });
565
566        r.clkena().modify(|rd, w| unsafe {
567            w.cclk_enable().bits(rd.cclk_enable().bits() | (1 << slot));
568            w.lp_enable().bits(rd.lp_enable().bits() | (1 << slot))
569        });
570        self.apply_clock_update(id)
571    }
572
573    fn apply_clock_update(&mut self, id: SlotId) -> Result<(), Error> {
574        let r = SDHOST::regs();
575        r.cmdarg().write(|w| unsafe { w.bits(0) });
576        r.cmd().write(|w| unsafe {
577            w.update_clock_registers_only().set_bit();
578            w.wait_prvdata_complete().set_bit();
579            w.card_number().bits(id.index());
580            w.start_cmd().set_bit()
581        });
582        wait_command_accepted()
583    }
584
585    fn send_init_sequence(&mut self, slot: SlotId) -> Result<(), Error> {
586        let r = SDHOST::regs();
587        r.rintsts().write(|w| unsafe { w.bits(EVT_CMD_DONE) });
588        r.cmdarg().write(|w| unsafe { w.bits(0) });
589        r.cmd().write(|w| unsafe {
590            w.send_initialization().set_bit();
591            w.wait_prvdata_complete().set_bit();
592            w.card_number().bits(slot.index());
593            w.start_cmd().set_bit()
594        });
595        wait_command_accepted()?;
596
597        let result = poll_until(|| r.rintsts().read().bits() & EVT_CMD_DONE != 0);
598        if result.is_ok() {
599            r.rintsts().write(|w| unsafe { w.bits(EVT_CMD_DONE) });
600        }
601        result
602    }
603
604    fn send_command_blocking(
605        &mut self,
606        slot: SlotId,
607        index: u8,
608        arg: u32,
609        resp_len: ResponseLen,
610        check_crc: bool,
611        flags: CommandFlags,
612    ) -> Result<[u32; 4], Error> {
613        let r = SDHOST::regs();
614        let consume = EVT_CMD_DONE | EVT_RTO | EVT_RCRC | EVT_RESP_ERR | EVT_HLE;
615
616        r.rintsts().write(|w| unsafe { w.bits(consume) });
617
618        self.issue_command(slot, index, arg, resp_len, check_crc, flags)?;
619
620        let done = EVT_CMD_DONE | EVT_RTO | EVT_RCRC | EVT_RESP_ERR;
621        let mut sts = 0;
622        poll_until(|| {
623            sts = r.rintsts().read().bits();
624            sts & done != 0
625        })?;
626        map_rintsts(sts)?;
627
628        let resp = read_response(resp_len);
629        r.rintsts().write(|w| unsafe { w.bits(consume) });
630
631        if flags.busy {
632            wait_busy_cleared()?;
633        }
634        Ok(resp)
635    }
636
637    #[allow(clippy::too_many_arguments)]
638    fn transfer_blocking(
639        &mut self,
640        slot: SlotId,
641        index: u8,
642        arg: u32,
643        write: bool,
644        mut t: Transfer,
645        block_size: u16,
646        block_count: u32,
647    ) -> Result<[u32; 4], Error> {
648        let r = SDHOST::regs();
649
650        reset_transfer()?;
651        let total_len = t.remaining();
652        r.blksiz().write(|w| unsafe { w.bits(block_size as u32) });
653        r.bytcnt().write(|w| unsafe { w.bits(total_len as u32) });
654
655        let mut ring = ring();
656        *ring.reborrow().into_inner() = [Desc::ZERO; RING_LEN];
657        ring[0].flags |= DESC_FIRST;
658        fill_descriptors(ring.reborrow(), &mut t, RING_LEN);
659        enable_idmac(ring.as_ptr() as u32);
660        r.pldmnd().write(|w| unsafe { w.bits(1) });
661
662        let auto_stop = needs_auto_stop(index, block_count);
663        self.issue_data_command(slot, index, arg, write, auto_stop)?;
664
665        let result = run_data_phase(&mut t, ring, write, auto_stop);
666
667        disable_idmac();
668        r.rintsts().write(|w| unsafe { w.bits(0xFFFF_FFFF) });
669        r.idsts().write(|w| unsafe { w.bits(0xFFFF_FFFF) });
670
671        result?;
672        Ok(read_response(ResponseLen::Short))
673    }
674
675    fn issue_command(
676        &mut self,
677        slot: SlotId,
678        index: u8,
679        arg: u32,
680        resp_len: ResponseLen,
681        check_crc: bool,
682        flags: CommandFlags,
683    ) -> Result<(), Error> {
684        let r = SDHOST::regs();
685        r.cmdarg().write(|w| unsafe { w.bits(arg) });
686        r.cmd().write(|w| unsafe {
687            w.index().bits(index);
688            w.response_expect()
689                .bit(!matches!(resp_len, ResponseLen::None));
690            w.response_length()
691                .bit(matches!(resp_len, ResponseLen::Long));
692            w.check_response_crc().bit(check_crc);
693            w.wait_prvdata_complete().bit(flags.wait_complete);
694            w.stop_abort_cmd().bit(flags.stop_abort);
695            w.use_hole().set_bit();
696            w.card_number().bits(slot.index());
697            w.start_cmd().set_bit()
698        });
699        wait_command_accepted()
700    }
701
702    fn issue_data_command(
703        &mut self,
704        slot: SlotId,
705        index: u8,
706        arg: u32,
707        write: bool,
708        auto_stop: bool,
709    ) -> Result<(), Error> {
710        let r = SDHOST::regs();
711        r.cmdarg().write(|w| unsafe { w.bits(arg) });
712        r.cmd().write(|w| unsafe {
713            w.index().bits(index);
714            w.response_expect().set_bit();
715            w.check_response_crc().set_bit();
716            w.data_expected().set_bit();
717            w.read_write().bit(write);
718            w.send_auto_stop().bit(auto_stop);
719            w.wait_prvdata_complete().set_bit();
720            w.use_hole().set_bit();
721            w.card_number().bits(slot.index());
722            w.start_cmd().set_bit()
723        });
724        wait_command_accepted()
725    }
726
727    async fn send_command_async(
728        &mut self,
729        slot: SlotId,
730        index: u8,
731        arg: u32,
732        resp_len: ResponseLen,
733        check_crc: bool,
734        flags: CommandFlags,
735    ) -> Result<[u32; 4], Error> {
736        let r = SDHOST::regs();
737        let guard = DropGuard::new((), |()| abort_transfer());
738
739        r.rintsts().write(|w| unsafe { w.bits(INTMASK_CMD) });
740        arm_transfer(false, false, None);
741        r.intmask()
742            .write(|w| unsafe { w.bits(idle_intmask() | INTMASK_CMD) });
743
744        self.issue_command(slot, index, arg, resp_len, check_crc, flags)?;
745        wait_result().await?;
746        let resp = read_response(resp_len);
747        if flags.busy {
748            wait_busy_poll().await?;
749        }
750        guard.defuse();
751        Ok(resp)
752    }
753
754    #[allow(clippy::too_many_arguments)]
755    async fn transfer_async(
756        &mut self,
757        slot: SlotId,
758        index: u8,
759        arg: u32,
760        write: bool,
761        mut t: Transfer,
762        block_size: u16,
763        auto_stop: bool,
764    ) -> Result<[u32; 4], Error> {
765        let _cpu_frequency_lock = CpuFrequencyLock::new();
766        let guard = DropGuard::new((), |()| abort_transfer());
767        let r = SDHOST::regs();
768
769        reset_transfer()?;
770        let total_len = t.remaining();
771        r.blksiz().write(|w| unsafe { w.bits(block_size as u32) });
772        r.bytcnt().write(|w| unsafe { w.bits(total_len as u32) });
773
774        let mut ring = ring();
775        *ring.reborrow().into_inner() = [Desc::ZERO; RING_LEN];
776        ring[0].flags |= DESC_FIRST;
777        fill_descriptors(ring.reborrow(), &mut t, RING_LEN);
778        enable_idmac(ring.as_ptr() as u32);
779        r.pldmnd().write(|w| unsafe { w.bits(1) });
780
781        arm_transfer(true, auto_stop, Some(t));
782        r.idinten().write(|w| unsafe { w.bits(IDINTEN_ALL) });
783        r.intmask()
784            .write(|w| unsafe { w.bits(idle_intmask() | INTMASK_DATA) });
785
786        self.issue_data_command(slot, index, arg, write, auto_stop)?;
787        wait_result().await?;
788        if write {
789            wait_busy_async().await?;
790        }
791        disable_idmac();
792        let resp = read_response(ResponseLen::Short);
793        guard.defuse();
794        Ok(resp)
795    }
796
797    async fn read_async(
798        &mut self,
799        slot: SlotId,
800        index: u8,
801        arg: u32,
802        buf: &mut [u8],
803        block_size: u16,
804        auto_stop: bool,
805    ) -> Result<[u32; 4], MmcError> {
806        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
807        if let Some(split) = bounce::Bounce::split(buf) {
808            let transfer = self
809                .bounce
810                .read_dma_setup(buf, split)
811                .map_err(MmcError::from)?;
812
813            let resp = self
814                .transfer_async(slot, index, arg, false, transfer, block_size, auto_stop)
815                .await?;
816
817            self.bounce.read_finish(buf, split);
818            return Ok(resp);
819        }
820
821        let mut dma = DmaAlignedMut::new(buf)?;
822        let ptr = dma_ptr(dma.reborrow())?;
823        let total = dma.len();
824        let resp = self
825            .transfer_async(
826                slot,
827                index,
828                arg,
829                false,
830                Transfer::single(ptr, total),
831                block_size,
832                auto_stop,
833            )
834            .await?;
835        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
836        dma.invalidate();
837        Ok(resp)
838    }
839
840    async fn write_async(
841        &mut self,
842        slot: SlotId,
843        index: u8,
844        arg: u32,
845        buf: &[u8],
846        block_size: u16,
847        auto_stop: bool,
848    ) -> Result<[u32; 4], MmcError> {
849        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
850        if let Some(split) = bounce::Bounce::split(buf) {
851            let transfer = self
852                .bounce
853                .write_dma_setup(buf, split)
854                .map_err(MmcError::from)?;
855
856            return Ok(self
857                .transfer_async(slot, index, arg, true, transfer, block_size, auto_stop)
858                .await?);
859        }
860
861        let dma = DmaAlignedRef::new(buf)?;
862
863        // Flush the caller's buffer before the IDMAC reads it, else stale
864        // memory is written to the card. Reached only when `Bounce::split`
865        // returned `None`, so `buf` is region-aligned in address and length.
866        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
867        dma.writeback();
868
869        let total = dma.len();
870        let ptr = dma_ptr_ref(dma)?;
871        Ok(self
872            .transfer_async(
873                slot,
874                index,
875                arg,
876                true,
877                Transfer::single(ptr, total),
878                block_size,
879                auto_stop,
880            )
881            .await?)
882    }
883}
884
885// `rintsts` card-detect change bit.
886const EVT_CD: u32 = 1 << 0;
887// `rintsts` SDIO card-interrupt bits (one per slot).
888const EVT_IO_SLOT0: u32 = 1 << 16;
889const EVT_IO_SLOT1: u32 = 1 << 17;
890
891// `idsts` fatal DMA bits (fatal bus error / descriptor unavailable).
892const IDSTS_FBE: u32 = 1 << 2;
893const IDSTS_DU: u32 = 1 << 4;
894
895/// Interrupt mask kept armed while idle (card-detect only).
896const INTMASK_IDLE: u32 = EVT_CD;
897/// Command-phase interrupt mask.
898const INTMASK_CMD: u32 = EVT_CMD_DONE | EVT_RTO | EVT_RCRC | EVT_RESP_ERR | EVT_HLE;
899/// Data-phase interrupt mask (command bits plus data events).
900const INTMASK_DATA: u32 = INTMASK_CMD
901    | EVT_DATA_OVER
902    | EVT_DCRC
903    | EVT_DTO
904    | EVT_HTO
905    | EVT_SBE
906    | EVT_EBE
907    | EVT_FRUN
908    | EVT_ACD;
909
910// `idinten` bits: TX/RX done, fatal/unavailable, normal/abnormal summaries.
911const IDINTEN_ALL: u32 = (1 << 0) | (1 << 1) | (1 << 2) | (1 << 4) | (1 << 8) | (1 << 9);
912
913/// ISR/task transfer handshake (distinct from CIU access via `EngineSession`).
914struct TransferState {
915    transfer: Option<Transfer>,
916    result: Option<Result<(), Error>>,
917    expect_data: bool,
918    multiblock: bool,
919    over_seen: bool,
920    acd_seen: bool,
921    wait_busy: bool,
922    waker: WakerRegistration,
923}
924
925impl TransferState {
926    const IDLE: Self = TransferState {
927        transfer: None,
928        result: None,
929        expect_data: false,
930        multiblock: false,
931        over_seen: false,
932        acd_seen: false,
933        wait_busy: false,
934        waker: WakerRegistration::new(),
935    };
936}
937
938/// Persistent controller/slot settings consulted on slot selection.
939struct Settings {
940    module: Config,
941    slots: [SlotSettings; SLOT_COUNT],
942}
943
944impl Settings {
945    const INIT: Self = Settings {
946        module: Config::const_default(),
947        slots: [SlotSettings::INIT; SLOT_COUNT],
948    };
949
950    fn set_slot_bus(&mut self, slot: SlotId, width: BusWidth, hz: u32) -> Result<(), Error> {
951        if hz == 0 || hz > 40_000_000 {
952            return Err(Error::Unsupported);
953        }
954        let idx = slot.index() as usize;
955        self.slots[idx].hz = hz;
956        self.slots[idx].width = width;
957        self.slots[idx].dirty = true;
958        Ok(())
959    }
960}
961
962#[derive(Clone, Copy)]
963struct SlotSettings {
964    hz: u32,
965    width: BusWidth,
966    dirty: bool,
967    #[cfg(sdmmc_delay_phase_num_is_set)]
968    input_delay_phase: DelayPhase,
969}
970
971impl SlotSettings {
972    const INIT: Self = SlotSettings {
973        hz: 25_000_000,
974        width: BusWidth::Bit1,
975        dirty: true,
976        #[cfg(sdmmc_delay_phase_num_is_set)]
977        input_delay_phase: DelayPhase::_0,
978    };
979}
980
981static ENGINE: embassy_sync::mutex::Mutex<RawMutex, EngineSession> =
982    embassy_sync::mutex::Mutex::new(EngineSession::INIT);
983static SETTINGS: NonReentrantMutex<Settings> = NonReentrantMutex::new(Settings::INIT);
984static TRANSFER: NonReentrantMutex<TransferState> = NonReentrantMutex::new(TransferState::IDLE);
985
986fn with_engine_try<R>(
987    slot: SlotId,
988    f: impl FnOnce(&mut EngineSession) -> Result<R, Error>,
989) -> Result<R, BlockingError> {
990    let mut session = ENGINE.try_lock().map_err(|_| BlockingError::Busy)?;
991    session.select_and_apply(slot).map_err(BlockingError::Op)?;
992    f(&mut session).map_err(BlockingError::Op)
993}
994
995async fn lock_engine(slot: SlotId) -> Result<MutexGuard<'static, RawMutex, EngineSession>, Error> {
996    let mut guard = ENGINE.lock().await;
997    guard.select_and_apply(slot)?;
998    Ok(guard)
999}
1000
1001/// Matrix-routed pin guards owned by the slot for its whole lifetime.
1002///
1003/// Held here (rather than leaked) so re-running a `with_*` builder method
1004/// drops the previous routing. IO_MUX chips drive fixed pads and need none.
1005#[cfg(sdmmc_has_gpio_matrix)]
1006struct SlotPins {
1007    clk: PinGuard,
1008    cmd: PinGuard,
1009    data: [PinGuard; 4],
1010}
1011
1012#[cfg(sdmmc_has_gpio_matrix)]
1013impl SlotPins {
1014    const fn new() -> Self {
1015        Self {
1016            clk: PinGuard::new_unconnected(),
1017            cmd: PinGuard::new_unconnected(),
1018            data: [const { PinGuard::new_unconnected() }; 4],
1019        }
1020    }
1021}
1022
1023/// Mutable per-slot runtime state.
1024struct SlotState {
1025    io_waker: AtomicWaker,
1026    cd_waker: AtomicWaker,
1027    /// Edge latch: set by the ISR when a card interrupt fires, consumed
1028    /// (swapped to `false`) by the waiter. Decouples the edge from the await.
1029    io_pending: AtomicBool,
1030    #[cfg(sdmmc_has_gpio_matrix)]
1031    pins: UnsafeCell<SlotPins>,
1032}
1033
1034// `pins` is only touched while building a slot (never by the ISR); the slot
1035// value owns its `State`, mirroring the SPI driver.
1036#[cfg(sdmmc_has_gpio_matrix)]
1037unsafe impl Sync for SlotState {}
1038
1039impl SlotState {
1040    const fn new() -> Self {
1041        Self {
1042            io_waker: AtomicWaker::new(),
1043            cd_waker: AtomicWaker::new(),
1044            io_pending: AtomicBool::new(false),
1045            #[cfg(sdmmc_has_gpio_matrix)]
1046            pins: UnsafeCell::new(SlotPins::new()),
1047        }
1048    }
1049}
1050
1051static SLOT_STATE: [SlotState; SLOT_COUNT] = [const { SlotState::new() }; SLOT_COUNT];
1052
1053/// Mutable runtime state for a slot.
1054#[cfg(sdmmc_has_gpio_matrix)]
1055fn slot_state(id: SlotId) -> &'static SlotState {
1056    &SLOT_STATE[id.index() as usize]
1057}
1058
1059/// Exclusive access to a slot's pin guards (builder-time only).
1060#[cfg(sdmmc_has_gpio_matrix)]
1061fn slot_pins(id: SlotId) -> &'static mut SlotPins {
1062    unsafe { &mut *slot_state(id).pins.get() }
1063}
1064
1065/// Immutable per-slot routing: SDIO card-interrupt bit plus the input/output
1066/// signals the slot's pins connect to through the GPIO matrix.
1067///
1068/// Signals a slot does not route through the matrix (IO_MUX-routed bus
1069/// signals, or chips without a GPIO matrix at all) are `None`/empty, so one
1070/// table shape serves every chip. On IO_MUX-only chips none of the signal
1071/// fields are read, hence the conditional `allow(dead_code)`.
1072///
1073/// Populated from chip metadata by the `for_each_sdmmc!` invocation below.
1074struct SlotInfo {
1075    io_event: u32,
1076    #[cfg(sdmmc_has_gpio_matrix)]
1077    clk_out: Option<OutputSignal>,
1078    #[cfg(sdmmc_has_gpio_matrix)]
1079    cmd_in: Option<InputSignal>,
1080    #[cfg(sdmmc_has_gpio_matrix)]
1081    cmd_out: Option<OutputSignal>,
1082    #[cfg(sdmmc_has_gpio_matrix)]
1083    data_in: &'static [InputSignal],
1084    #[cfg(sdmmc_has_gpio_matrix)]
1085    data_out: &'static [OutputSignal],
1086    cd_in: Option<InputSignal>,
1087    wp_in: Option<InputSignal>,
1088}
1089
1090// Wrap an optional metadata signal name in `Some(..)`, or yield `None` when
1091// the slot does not route that signal through the GPIO matrix.
1092macro_rules! opt_in {
1093    () => {
1094        None
1095    };
1096    ($signal:ident) => {
1097        Some(InputSignal::$signal)
1098    };
1099}
1100
1101#[cfg(sdmmc_has_gpio_matrix)]
1102macro_rules! opt_out {
1103    () => {
1104        None
1105    };
1106    ($signal:ident) => {
1107        Some(OutputSignal::$signal)
1108    };
1109}
1110
1111// The SDIO card-interrupt bit is positional (`rintsts` bit `16 + slot`); the
1112// signal names come straight from chip metadata.
1113for_each_sdmmc! {
1114    (all $( (
1115        $slot:ident, $idx:literal, $iomux:literal,
1116        [$($clk:ident)?], [$($cmd_in:ident)?], [$($cmd_out:ident)?],
1117        [$($data_in:ident),*], [$($data_out:ident),*],
1118        [$($cd:ident)?], [$($wp:ident)?], [$($card_int:ident)?],
1119        [$($data_strobe:ident)?], [$($rst:ident)?]
1120    ) ),*) => {
1121        const SLOT_COUNT: usize = 0 $(+ { crate::ignore!($slot); 1 })*;
1122        static SLOT_INFO: [SlotInfo; SLOT_COUNT] = [ $(
1123            SlotInfo {
1124                io_event: 1u32 << (16 + $idx),
1125
1126                #[cfg(sdmmc_has_gpio_matrix)]
1127                clk_out: opt_out!($($clk)?),
1128                #[cfg(sdmmc_has_gpio_matrix)]
1129                cmd_in: opt_in!($($cmd_in)?),
1130                #[cfg(sdmmc_has_gpio_matrix)]
1131                cmd_out: opt_out!($($cmd_out)?),
1132                #[cfg(sdmmc_has_gpio_matrix)]
1133                data_in: &[ $(InputSignal::$data_in),* ],
1134                #[cfg(sdmmc_has_gpio_matrix)]
1135                data_out: &[ $(OutputSignal::$data_out),* ],
1136
1137                cd_in: opt_in!($($cd)?),
1138                wp_in: opt_in!($($wp)?),
1139            }
1140        ),* ];
1141
1142        paste::paste! {
1143            /// Selects one of the controller's card slots.
1144            #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
1145            #[cfg_attr(feature = "defmt", derive(defmt::Format))]
1146            pub enum SlotId {
1147                $(
1148                    #[doc = concat!("Slot ", stringify!($idx), ".")]
1149                    [<_ $idx>],
1150                )*
1151            }
1152
1153            impl SlotId {
1154                /// Zero-based slot index.
1155                fn index(self) -> u8 {
1156                    match self {
1157                        $(
1158                            SlotId::[<_ $idx >] => $idx,
1159                        )*
1160                    }
1161                }
1162            }
1163
1164            /// Maps a const slot index to its [`SlotId`].
1165            const fn slot_id(s: u8) -> SlotId {
1166                match s {
1167                    $($idx => SlotId::[<_ $idx>],)*
1168                    _ => ::core::unreachable!(),
1169                }
1170            }
1171        }
1172    };
1173}
1174
1175/// Static routing data for a slot.
1176fn slot_info(id: SlotId) -> &'static SlotInfo {
1177    &SLOT_INFO[id.index() as usize]
1178}
1179
1180/// Interrupt mask kept armed while idle: card-detect plus the SDIO card
1181/// interrupt of any slot that is listening. Preserves listening across
1182/// transfers (the transfer paths OR their bits onto this base).
1183fn idle_intmask() -> u32 {
1184    SDHOST::regs().intmask().read().bits() & (EVT_IO_SLOT0 | EVT_IO_SLOT1) | INTMASK_IDLE
1185}
1186
1187/// Arms `TRANSFER` for a new operation and clears stale status.
1188fn arm_transfer(expect_data: bool, multiblock: bool, transfer: Option<Transfer>) {
1189    TRANSFER.with(|ts| {
1190        *ts = TransferState {
1191            transfer,
1192            result: None,
1193            expect_data,
1194            multiblock,
1195            over_seen: false,
1196            acd_seen: false,
1197            wait_busy: false,
1198            waker: WakerRegistration::new(),
1199        };
1200    });
1201}
1202
1203/// SDMMC interrupt handler: refills the IDMAC ring and wakes the task.
1204#[handler]
1205fn on_interrupt() {
1206    let r = SDHOST::regs();
1207    let pending = r.mintsts().read().bits();
1208    let idsts = r.idsts().read().bits();
1209
1210    TRANSFER.with(|ts| {
1211        if ts.wait_busy {
1212            // For an R1b/no-data command the SBE bit doubles as the Busy
1213            // Clear Interrupt, fired when the card releases DAT0.
1214            if pending & EVT_SBE != 0 {
1215                ts.result = Some(Ok(()));
1216            }
1217        } else {
1218            // Refill descriptors the engine has released mid-transfer.
1219            if let Some(t) = ts.transfer.as_mut()
1220                && t.remaining() > 0
1221            {
1222                let mut ring = ring();
1223                let free = free_descriptors(ring.reborrow(), t.next_desc);
1224                if free > 0 {
1225                    fill_descriptors(ring.reborrow(), t, free);
1226                    r.pldmnd().write(|w| unsafe { w.bits(1) });
1227                }
1228            }
1229
1230            if ts.result.is_none() {
1231                let err = map_rintsts(pending)
1232                    .err()
1233                    .or(if idsts & (IDSTS_FBE | IDSTS_DU) != 0 {
1234                        Some(Error::DmaError)
1235                    } else {
1236                        None
1237                    });
1238                if let Some(e) = err {
1239                    ts.result = Some(Err(e));
1240                } else if ts.expect_data {
1241                    if pending & EVT_DATA_OVER != 0 {
1242                        ts.over_seen = true;
1243                    }
1244                    if pending & EVT_ACD != 0 {
1245                        ts.acd_seen = true;
1246                    }
1247                    if ts.over_seen && (!ts.multiblock || ts.acd_seen) {
1248                        ts.result = Some(Ok(()));
1249                    }
1250                } else if pending & EVT_CMD_DONE != 0 {
1251                    ts.result = Some(Ok(()));
1252                }
1253            }
1254        }
1255
1256        if ts.result.is_some() {
1257            ts.wait_busy = false;
1258            ts.transfer = None;
1259            r.intmask().write(|w| unsafe { w.bits(idle_intmask()) });
1260            r.idinten().write(|w| unsafe { w.bits(0) });
1261            ts.waker.wake();
1262        }
1263    });
1264
1265    // SDIO card interrupt (edge-triggered): latch it and wake. The write-1-clear
1266    // of `rintsts` below disarms the edge, so it won't refire until the card
1267    // signals again; no need to mask. The waiter consumes the latch on wake.
1268    if pending & EVT_IO_SLOT0 != 0 {
1269        SLOT_STATE[0].io_pending.store(true, Ordering::Release);
1270        SLOT_STATE[0].io_waker.wake();
1271    }
1272    if pending & EVT_IO_SLOT1 != 0 {
1273        SLOT_STATE[1].io_pending.store(true, Ordering::Release);
1274        SLOT_STATE[1].io_waker.wake();
1275    }
1276
1277    // Card-detect change: wake both slot listeners.
1278    if pending & EVT_CD != 0 {
1279        SLOT_STATE[0].cd_waker.wake();
1280        SLOT_STATE[1].cd_waker.wake();
1281    }
1282
1283    // Write-1-clear the bits handled this pass.
1284    r.rintsts().write(|w| unsafe { w.bits(pending) });
1285    r.idsts().write(|w| unsafe { w.bits(idsts) });
1286}
1287
1288/// SDMMC / SDIO host controller driver.
1289///
1290/// Owns the shared transfer engine and hands out per-slot handles.
1291pub struct SdHostController<'d> {
1292    _peri: SDHOST<'d>,
1293    _guard: PeripheralGuard,
1294    taken: [AtomicBool; SLOT_COUNT],
1295}
1296
1297impl<'d> SdHostController<'d> {
1298    /// Creates the controller, enabling its bus clock and configuring the
1299    /// shared (engine-wide) module clock from `config`.
1300    pub fn new(peri: SDHOST<'d>, config: Config) -> Result<Self, ConfigError> {
1301        config.validate()?;
1302        let guard = PeripheralGuard::new(Peripheral::SdioHost);
1303        chip_specific::chip_setup();
1304        let this = Self {
1305            _peri: peri,
1306            _guard: guard,
1307            taken: [const { AtomicBool::new(false) }; SLOT_COUNT],
1308        };
1309
1310        // Module clock first, then the DesignWare reset, then quiesce
1311        // interrupts. The module clock is engine-wide, so it is programmed once
1312        // here and the config is stashed for slots to derive their card
1313        // dividers from. The clock setup must precede `reset_engine` because
1314        // the module clock drives the FIFO reset.
1315        chip_specific::set_module_clock(config.clock_source, config.module_div);
1316        this.reset_engine();
1317
1318        SETTINGS.with(|s| s.module = config);
1319        let r = SDHOST::regs();
1320        r.tmout().write(|w| unsafe {
1321            w.response_timeout().bits(0xFF);
1322            w.data_timeout().bits(0xFF_FFFF)
1323        });
1324        r.rintsts().write(|w| unsafe { w.bits(0xFFFF_FFFF) });
1325        r.ctrl().modify(|_, w| w.int_enable().clear_bit());
1326
1327        Ok(this)
1328    }
1329
1330    /// Resets the controller, FIFO and DMA blocks, waiting for self-clear.
1331    fn reset_engine(&self) {
1332        let r = SDHOST::regs();
1333        r.ctrl().modify(|_, w| {
1334            w.controller_reset().set_bit();
1335            w.fifo_reset().set_bit();
1336            w.dma_reset().set_bit()
1337        });
1338
1339        // A reset timeout means the controller never left reset; there is no
1340        // matching `ConfigError` and the first card command would surface it
1341        // as a timeout regardless, so this is best-effort.
1342        let _ = poll_until_timeout(Duration::from_millis(100), || {
1343            let c = r.ctrl().read();
1344            !c.controller_reset().bit_is_set()
1345                && !c.fifo_reset().bit_is_set()
1346                && !c.dma_reset().bit_is_set()
1347        });
1348    }
1349
1350    /// Returns a builder for the given slot in blocking mode.
1351    ///
1352    /// Both slots can be taken (once each); the shared engine serializes their
1353    /// transactions. Requesting the same slot twice returns
1354    /// [`ConfigError::SlotInUse`]. Blocking engine ops return
1355    /// [`BlockingError::Busy`] on contention.
1356    ///
1357    /// The returned slot borrows the controller, so the controller cannot be
1358    /// dropped while any of its slots are alive.
1359    pub fn slot<const S: u8>(
1360        &self,
1361        config: SlotConfig,
1362    ) -> Result<Slot<'_, S, Blocking>, ConfigError> {
1363        const { ::core::assert!(S < 2, "SDMMC has only slots 0 and 1") };
1364        let idx = S as usize;
1365        if self.taken[idx].swap(true, Ordering::Relaxed) {
1366            return Err(ConfigError::SlotInUse);
1367        }
1368        #[cfg(sdmmc_delay_phase_num_is_set)]
1369        SETTINGS.with(|s| {
1370            s.slots[idx].input_delay_phase = config.input_delay_phase;
1371            s.slots[idx].dirty = true;
1372        });
1373        Ok(Slot {
1374            config,
1375            data_pins: 0,
1376            clk_connected: false,
1377            cmd_connected: false,
1378            cd_connected: false,
1379            wp_connected: false,
1380            _guard: PeripheralGuard::new(Peripheral::SdioHost),
1381            power: None,
1382            _pd: PhantomData,
1383        })
1384    }
1385}
1386
1387/// Card-clock output pin for slot `S`.
1388pub trait SlotClk<'d, const S: u8> {
1389    #[doc(hidden)]
1390    fn configure(self);
1391}
1392
1393/// Command (bidirectional) pin for slot `S`.
1394pub trait SlotCmd<'d, const S: u8> {
1395    #[doc(hidden)]
1396    fn configure(self);
1397}
1398
1399/// Data line `L` (bidirectional) for slot `S`.
1400pub trait SlotData<'d, const S: u8, const L: u8> {
1401    #[doc(hidden)]
1402    fn configure(self);
1403}
1404
1405// GPIO-matrix-routed slots (all of S3; slot 1 on P4): any pin can carry any of
1406// the slot's signals, routed through the interconnect matrix. The impls accept
1407// any GPIO and stash the routing guard in the slot's `State` for its lifetime.
1408//
1409// Generated per matrix slot (`iomux = false`) rather than blanket over the slot
1410// index: on P4 the IO_MUX slot's bus signals are implemented for fixed pins
1411// below, and a blanket `impl<const S>` would collide with those.
1412#[cfg(sdmmc_has_gpio_matrix)]
1413for_each_sdmmc! {
1414    (
1415        $slot:ident, $idx:literal, false,
1416        [$($clk:ident)?], [$($cmd_in:ident)?], [$($cmd_out:ident)?],
1417        [$($data_in:ident),*], [$($data_out:ident),*],
1418        [$($cd:ident)?], [$($wp:ident)?], [$($card_int:ident)?],
1419        [$($data_strobe:ident)?], [$($rst:ident)?]
1420    ) => {
1421        impl<'d, P: PeripheralOutput<'d>> SlotClk<'d, $idx> for P {
1422            fn configure(self) {
1423                let pin = self.into();
1424                pin.apply_output_config(&OutputConfig::default());
1425                pin.set_output_enable(true);
1426                slot_pins(slot_id($idx)).clk = interconnect::OutputSignal::connect_with_guard(
1427                    pin,
1428                    slot_info(slot_id($idx)).clk_out.unwrap(),
1429                );
1430            }
1431        }
1432
1433        impl<'d, P: PeripheralInput<'d> + PeripheralOutput<'d>> SlotCmd<'d, $idx> for P {
1434            fn configure(self) {
1435                slot_pins(slot_id($idx)).cmd = connect_bidir(
1436                    self.into(),
1437                    slot_info(slot_id($idx)).cmd_in.unwrap(),
1438                    slot_info(slot_id($idx)).cmd_out.unwrap(),
1439                );
1440            }
1441        }
1442
1443        impl<'d, const L: u8, P: PeripheralInput<'d> + PeripheralOutput<'d>>
1444            SlotData<'d, $idx, L> for P
1445        {
1446            fn configure(self) {
1447                slot_pins(slot_id($idx)).data[L as usize] = connect_bidir(
1448                    self.into(),
1449                    slot_info(slot_id($idx)).data_in[L as usize],
1450                    slot_info(slot_id($idx)).data_out[L as usize],
1451                );
1452            }
1453        }
1454    };
1455
1456    // IO_MUX-routed slots (P4 slot 0) get their bus impls from the fixed-pin
1457    // block below; nothing to generate here.
1458    (
1459        $slot:ident, $idx:literal, true,
1460        [$($clk:ident)?], [$($cmd_in:ident)?], [$($cmd_out:ident)?],
1461        [$($data_in:ident),*], [$($data_out:ident),*],
1462        [$($cd:ident)?], [$($wp:ident)?], [$($card_int:ident)?],
1463        [$($data_strobe:ident)?], [$($rst:ident)?]
1464    ) => {};
1465}
1466
1467// IO_MUX-routed slots (both slots on ESP32; slot 0 on P4): each bus signal
1468// lives on a fixed pad selected by an IO_MUX function. The traits are
1469// implemented only for the mandated `(gpio, af)` pairs, so a wrong pin is a
1470// compile error. ESP32 names them `HS1_*` (slot 0) / `HS2_*` (slot 1); P4
1471// names slot 0's pads `SD1_*`.
1472#[cfg(sdmmc_has_iomux)]
1473fn configure_iomux_pad(pin: u8, af: crate::gpio::AlternateFunction) {
1474    crate::gpio::io_mux_reg(pin).modify(|_, w| {
1475        unsafe { w.mcu_sel().bits(af as u8) };
1476        w.fun_ie().set_bit();
1477        w.fun_wpu().set_bit();
1478        // esp-idf bumps the SD pads to the strongest drive on every chip
1479        // except ESP32 (where the default of 2 is sufficient). Matches
1480        // `configure_pin_iomux`.
1481        #[cfg(not(esp32))]
1482        unsafe {
1483            w.fun_drv().bits(3)
1484        };
1485        w
1486    });
1487}
1488
1489#[cfg(sdmmc_has_iomux)]
1490macro_rules! impl_signal_trait {
1491    ($gpio:ident, $trait:ident, $af:ident, $s:literal) => {
1492        impl<'d> $trait<'d, $s> for crate::peripherals::$gpio<'d> {
1493            fn configure(self) {
1494                configure_iomux_pad(
1495                    crate::gpio::Pin::number(&self),
1496                    crate::gpio::AlternateFunction::$af,
1497                );
1498            }
1499        }
1500    };
1501
1502    ($gpio:ident, $trait:ident, $af:ident, $s:literal, $l:literal) => {
1503        impl<'d> $trait<'d, $s, $l> for crate::peripherals::$gpio<'d> {
1504            fn configure(self) {
1505                configure_iomux_pad(
1506                    crate::gpio::Pin::number(&self),
1507                    crate::gpio::AlternateFunction::$af,
1508                );
1509            }
1510        }
1511    };
1512}
1513
1514// Arms for functions absent on a given chip simply never match (the generated macro ignores
1515// unmatched functions). P4 wires only slot 0 (`SD1_*`) to fixed pads; slot 1 is matrix.
1516#[cfg(sdmmc_has_iomux)]
1517for_each_iomux_function! {
1518    (SD1_CLK, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotClk, $af, 0); };
1519    (SD1_CMD, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotCmd, $af, 0); };
1520    (SD1_DATA0, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 0, 0); };
1521    (SD1_DATA1, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 0, 1); };
1522    (SD1_DATA2, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 0, 2); };
1523    (SD1_DATA3, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 0, 3); };
1524    (SD1_DATA4, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 0, 4); };
1525    (SD1_DATA5, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 0, 5); };
1526    (SD1_DATA6, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 0, 6); };
1527    (SD1_DATA7, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 0, 7); };
1528
1529    (SD2_CLK, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotClk, $af, 1); };
1530    (SD2_CMD, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotCmd, $af, 1); };
1531    (SD2_DATA0, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 1, 0); };
1532    (SD2_DATA1, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 1, 1); };
1533    (SD2_DATA2, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 1, 2); };
1534    (SD2_DATA3, $gpio:ident, $af:ident) => { impl_signal_trait!($gpio, SlotData, $af, 1, 3); };
1535}
1536
1537/// A configured card slot, generic over the slot index and driver mode.
1538pub struct Slot<'d, const S: u8, Dm: DriverMode> {
1539    config: SlotConfig,
1540    data_pins: u8,
1541    clk_connected: bool,
1542    cmd_connected: bool,
1543    cd_connected: bool,
1544    wp_connected: bool,
1545    _guard: PeripheralGuard,
1546    power: Option<interconnect::OutputSignal<'d>>,
1547    _pd: PhantomData<(&'d mut (), Dm)>,
1548}
1549
1550impl<'d, const S: u8, Dm: DriverMode> Slot<'d, S, Dm> {
1551    /// Connects the card clock output.
1552    pub fn with_clk(mut self, clk: impl SlotClk<'d, S>) -> Self {
1553        clk.configure();
1554        self.clk_connected = true;
1555        self
1556    }
1557
1558    /// Connects the bidirectional command line.
1559    pub fn with_cmd(mut self, cmd: impl SlotCmd<'d, S>) -> Self {
1560        cmd.configure();
1561        self.cmd_connected = true;
1562        self
1563    }
1564
1565    /// Connects data line 0 (required for any transfer).
1566    pub fn with_data0(mut self, d0: impl SlotData<'d, S, 0>) -> Self {
1567        d0.configure();
1568        self.note_data_pin(1);
1569        self
1570    }
1571
1572    /// Connects data line 1.
1573    pub fn with_data1(mut self, d1: impl SlotData<'d, S, 1>) -> Self {
1574        d1.configure();
1575        self.note_data_pin(2);
1576        self
1577    }
1578
1579    /// Connects data line 2.
1580    pub fn with_data2(mut self, d2: impl SlotData<'d, S, 2>) -> Self {
1581        d2.configure();
1582        self.note_data_pin(3);
1583        self
1584    }
1585
1586    /// Connects data line 3 (completes the 4-bit bus).
1587    pub fn with_data3(mut self, d3: impl SlotData<'d, S, 3>) -> Self {
1588        d3.configure();
1589        self.note_data_pin(4);
1590        self
1591    }
1592
1593    /// Connects data line 4.
1594    pub fn with_data4(mut self, d4: impl SlotData<'d, S, 4>) -> Self {
1595        d4.configure();
1596        self.note_data_pin(5);
1597        self
1598    }
1599
1600    /// Connects data line 5.
1601    pub fn with_data5(mut self, d5: impl SlotData<'d, S, 5>) -> Self {
1602        d5.configure();
1603        self.note_data_pin(6);
1604        self
1605    }
1606
1607    /// Connects data line 6.
1608    pub fn with_data6(mut self, d6: impl SlotData<'d, S, 6>) -> Self {
1609        d6.configure();
1610        self.note_data_pin(7);
1611        self
1612    }
1613
1614    /// Connects data line 7 (completes the 8-bit bus).
1615    pub fn with_data7(mut self, d7: impl SlotData<'d, S, 7>) -> Self {
1616        d7.configure();
1617        self.note_data_pin(8);
1618        self
1619    }
1620
1621    /// Connects the card-detect input.
1622    pub fn with_card_detect(mut self, cd: impl PeripheralInput<'d>) -> Self {
1623        let pin = cd.into();
1624        pin.set_input_enable(true);
1625        slot_info(slot_id(S)).cd_in.unwrap().connect_to(&pin);
1626        self.cd_connected = true;
1627        self
1628    }
1629
1630    /// Connects the write-protect input.
1631    pub fn with_write_protect(mut self, wp: impl PeripheralInput<'d>) -> Self {
1632        let pin = wp.into();
1633        pin.set_input_enable(true);
1634        slot_info(slot_id(S)).wp_in.unwrap().connect_to(&pin);
1635        self.wp_connected = true;
1636        self
1637    }
1638
1639    /// Connects a GPIO used to switch card power. Driven high here.
1640    pub fn with_power_enable(mut self, power: impl PeripheralOutput<'d>) -> Self {
1641        let pin = power.into();
1642        pin.set_output_high(true);
1643        pin.apply_output_config(&OutputConfig::default());
1644        pin.set_output_enable(true);
1645        self.power = Some(pin);
1646        self
1647    }
1648
1649    /// Returns whether a card is detected. If no card-detect pin is wired,
1650    /// assumes the card is present.
1651    pub fn is_card_present(&self) -> bool {
1652        if !self.cd_connected {
1653            return true;
1654        }
1655        (SDHOST::regs().cdetect().read().card_detect_n().bits() & (1 << S)) == 0
1656    }
1657
1658    /// Returns whether the card reports write protection. Returns `false`
1659    /// if no write-protect pin is wired. Polarity follows
1660    /// [`SlotConfig::with_wp_active_high`].
1661    pub fn is_write_protected(&self) -> bool {
1662        if !self.wp_connected {
1663            return false;
1664        }
1665        let level = (SDHOST::regs().wrtprt().read().write_protect().bits() & (1 << S)) != 0;
1666        level == self.config.wp_active_high
1667    }
1668
1669    /// Caches bus width and card clock; HW is programmed on the next engine op.
1670    pub fn set_bus_low_level(&mut self, width: BusWidth, hz: u32) -> Result<(), Error> {
1671        SETTINGS.with(|s| s.set_slot_bus(slot_id(S), width, hz))
1672    }
1673
1674    /// Checks that the mandatory pins for a transfer were connected.
1675    fn validate_pins(&self) -> Result<(), ConfigError> {
1676        if !self.clk_connected || !self.cmd_connected {
1677            return Err(ConfigError::MissingClkOrCmd);
1678        }
1679        if self.data_pins < 1 {
1680            return Err(ConfigError::NoData0);
1681        }
1682        Ok(())
1683    }
1684
1685    /// Issues the 80-clock SD init sequence (no command index).
1686    pub fn send_init_sequence(&mut self) -> Result<(), BlockingError> {
1687        with_engine_try(slot_id(S), |session| session.send_init_sequence(slot_id(S)))
1688    }
1689
1690    /// Issues a no-data command and returns its raw response words.
1691    pub fn command_blocking(
1692        &mut self,
1693        index: u8,
1694        arg: u32,
1695        resp_len: ResponseLen,
1696        check_crc: bool,
1697        flags: CommandFlags,
1698    ) -> Result<[u32; 4], BlockingError> {
1699        if !self.is_card_present() {
1700            return Err(BlockingError::Op(Error::NoCard));
1701        }
1702        let slot = slot_id(S);
1703        with_engine_try(slot, |session| {
1704            session.send_command_blocking(slot, index, arg, resp_len, check_crc, flags)
1705        })
1706    }
1707
1708    /// Reads `block_count` blocks into a DMA-capable buffer (CMD17/CMD18).
1709    pub fn read_blocks_blocking(
1710        &mut self,
1711        cmd_index: u8,
1712        arg: u32,
1713        mut buf: DmaAlignedMut<'_, [u8]>,
1714        block_size: u16,
1715        block_count: u32,
1716    ) -> Result<[u32; 4], BlockingError> {
1717        let slot = slot_id(S);
1718        with_engine_try(slot, |session| {
1719            let total = buf.len();
1720            let ptr = dma_ptr(buf.reborrow())?;
1721            let resp = session.transfer_blocking(
1722                slot,
1723                cmd_index,
1724                arg,
1725                false,
1726                Transfer::single(ptr, total),
1727                block_size,
1728                block_count,
1729            )?;
1730            #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
1731            buf.invalidate();
1732            Ok(resp)
1733        })
1734    }
1735
1736    /// Writes `block_count` blocks from a DMA-capable buffer (CMD24/CMD25).
1737    pub fn write_blocks_blocking(
1738        &mut self,
1739        cmd_index: u8,
1740        arg: u32,
1741        mut buf: DmaAlignedMut<'_, [u8]>,
1742        block_size: u16,
1743        block_count: u32,
1744    ) -> Result<[u32; 4], BlockingError> {
1745        let slot = slot_id(S);
1746        with_engine_try(slot, |session| {
1747            #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
1748            buf.writeback();
1749            let total = buf.len();
1750            let ptr = dma_ptr(buf.reborrow())?;
1751            session.transfer_blocking(
1752                slot,
1753                cmd_index,
1754                arg,
1755                true,
1756                Transfer::single(ptr, total),
1757                block_size,
1758                block_count,
1759            )
1760        })
1761    }
1762
1763    fn note_data_pin(&mut self, count: u8) {
1764        self.data_pins = self.data_pins.max(count);
1765    }
1766}
1767
1768impl<'d, const S: u8> Slot<'d, S, Blocking> {
1769    /// Reconfigures the slot to operate in [`Async`] mode.
1770    ///
1771    /// Binds the `SDHOST` interrupt handler and enables interrupt delivery.
1772    pub fn into_async(self) -> Slot<'d, S, Async> {
1773        let r = SDHOST::regs();
1774        r.rintsts().write(|w| unsafe { w.bits(0xFFFF_FFFF) });
1775        r.idsts().write(|w| unsafe { w.bits(0xFFFF_FFFF) });
1776        r.intmask().write(|w| unsafe { w.bits(idle_intmask()) });
1777        r.idinten().write(|w| unsafe { w.bits(0) });
1778        r.ctrl().modify(|_, w| w.int_enable().set_bit());
1779        crate::interrupt::bind_handler(Interrupt::SDIO_HOST, on_interrupt);
1780
1781        Slot {
1782            config: self.config,
1783            data_pins: self.data_pins,
1784            clk_connected: self.clk_connected,
1785            cmd_connected: self.cmd_connected,
1786            _guard: self._guard,
1787            power: self.power,
1788            cd_connected: self.cd_connected,
1789            wp_connected: self.wp_connected,
1790            _pd: PhantomData,
1791        }
1792    }
1793}
1794
1795impl<'d, const S: u8> Slot<'d, S, Async> {
1796    /// Reconfigures the slot back to [`Blocking`] mode.
1797    pub fn into_blocking(self) -> Slot<'d, S, Blocking> {
1798        let r = SDHOST::regs();
1799        r.ctrl().modify(|_, w| w.int_enable().clear_bit());
1800        r.intmask().write(|w| unsafe { w.bits(0) });
1801        r.idinten().write(|w| unsafe { w.bits(0) });
1802        crate::interrupt::disable(crate::system::Cpu::current(), Interrupt::SDIO_HOST);
1803
1804        Slot {
1805            config: self.config,
1806            data_pins: self.data_pins,
1807            clk_connected: self.clk_connected,
1808            cmd_connected: self.cmd_connected,
1809            _guard: self._guard,
1810            power: self.power,
1811            cd_connected: self.cd_connected,
1812            wp_connected: self.wp_connected,
1813            _pd: PhantomData,
1814        }
1815    }
1816
1817    /// Waits for the SDIO card interrupt (card pulls DAT1 low).
1818    #[must_use = "futures do nothing unless you `.await` or poll them"]
1819    pub fn wait_for_sdio_interrupt(&mut self) -> impl Future<Output = ()> {
1820        let slot_id = slot_id(S);
1821        let slot = slot_id.index() as usize;
1822        let bit = slot_info(slot_id).io_event;
1823
1824        WaitForInterruptFuture { slot, bit }
1825    }
1826
1827    /// Issues a control command, mapping protocol types to the engine core.
1828    async fn cmd_async<'a, C: sdio::ControlCommand + 'a>(
1829        &mut self,
1830        session: &mut EngineSession,
1831        cmd: C,
1832    ) -> Result<C::Resp<'a>, MmcError> {
1833        let slot = slot_id(S);
1834        let resp_len = match <C::Resp<'a> as sdio::Response>::LEN {
1835            sdio::ResponseLen::Zero => ResponseLen::None,
1836            sdio::ResponseLen::R48 => ResponseLen::Short,
1837            sdio::ResponseLen::R136 => ResponseLen::Long,
1838        };
1839        let flags = CommandFlags {
1840            wait_complete: !is_stop_or_abort(C::INDEX),
1841            stop_abort: is_stop_or_abort(C::INDEX),
1842            busy: <C::Resp<'a> as sdio::Response>::BUSY,
1843        };
1844        let crc = <C::Resp<'a> as sdio::Response>::CRC;
1845        let words = session
1846            .send_command_async(slot, C::INDEX, cmd.arg(), resp_len, crc, flags)
1847            .await?;
1848        Ok(<C::Resp<'a> as sdio::Response>::from_words(&words))
1849    }
1850}
1851
1852impl<'d, const S: u8> sdio::MmcBus for Slot<'d, S, Async> {
1853    async fn wait_for_event(&mut self) -> Result<(), MmcError> {
1854        self.wait_for_sdio_interrupt().await;
1855        Ok(())
1856    }
1857
1858    async fn send_command<'a, C>(&mut self, cmd: C) -> Result<C::Resp<'a>, MmcError>
1859    where
1860        C: sdio::ControlCommand + 'a,
1861    {
1862        let mut session = lock_engine(slot_id(S)).await?;
1863        self.cmd_async(&mut session, cmd).await
1864    }
1865
1866    async fn read_blocks<'a, C>(
1867        &mut self,
1868        mut cmd: C,
1869        auto_stop: bool,
1870    ) -> Result<C::Resp<'a>, MmcError>
1871    where
1872        C: sdio::BlockReadCommand + 'a,
1873    {
1874        let mut session = lock_engine(slot_id(S)).await?;
1875        let slot = slot_id(S);
1876        let (bs, arg) = (cmd.block_size().len() as u16, cmd.arg());
1877        let words = session
1878            .read_async(slot, C::INDEX, arg, cmd.buf(), bs, auto_stop)
1879            .await?;
1880        Ok(<C::Resp<'a> as sdio::Response>::from_words(&words))
1881    }
1882
1883    async fn write_blocks<'a, C>(
1884        &mut self,
1885        cmd: C,
1886        auto_stop: bool,
1887    ) -> Result<C::Resp<'a>, MmcError>
1888    where
1889        C: sdio::BlockWriteCommand + 'a,
1890    {
1891        let mut session = lock_engine(slot_id(S)).await?;
1892        let slot = slot_id(S);
1893        let (bs, arg) = (cmd.block_size().len() as u16, cmd.arg());
1894        let words = session
1895            .write_async(slot, C::INDEX, arg, cmd.buf(), bs, auto_stop)
1896            .await?;
1897        Ok(<C::Resp<'a> as sdio::Response>::from_words(&words))
1898    }
1899
1900    async fn read_bytes<'a, C>(&mut self, mut cmd: C) -> Result<C::Resp<'a>, MmcError>
1901    where
1902        C: sdio::ByteReadCommand + 'a,
1903    {
1904        let mut session = lock_engine(slot_id(S)).await?;
1905        let slot = slot_id(S);
1906        let (n, arg) = (cmd.byte_count(), cmd.arg());
1907        let words = session
1908            .read_async(slot, C::INDEX, arg, cmd.buf(), n as u16, false)
1909            .await?;
1910        Ok(<C::Resp<'a> as sdio::Response>::from_words(&words))
1911    }
1912
1913    async fn write_bytes<'a, C>(&mut self, cmd: C) -> Result<C::Resp<'a>, MmcError>
1914    where
1915        C: sdio::ByteWriteCommand + 'a,
1916    {
1917        let mut session = lock_engine(slot_id(S)).await?;
1918        let slot = slot_id(S);
1919        let (n, arg) = (cmd.byte_count(), cmd.arg());
1920        let words = session
1921            .write_async(slot, C::INDEX, arg, cmd.buf(), n as u16, false)
1922            .await?;
1923        Ok(<C::Resp<'a> as sdio::Response>::from_words(&words))
1924    }
1925
1926    async fn init_idle(&mut self, hz: u32) -> Result<(), MmcError> {
1927        let mut session = ENGINE.lock().await;
1928        self.validate_pins().map_err(|_| MmcError::Other)?;
1929        self.set_bus_low_level(BusWidth::Bit1, hz)?;
1930        session.select_and_apply(slot_id(S))?;
1931        session.send_init_sequence(slot_id(S))?;
1932        Ok(())
1933    }
1934
1935    fn set_bus(&mut self, width: sdio::BusWidth, hz: u32) -> Result<(), MmcError> {
1936        let w = match width {
1937            sdio::BusWidth::W1 => BusWidth::Bit1,
1938            sdio::BusWidth::W4 => BusWidth::Bit4,
1939            sdio::BusWidth::W8 => BusWidth::Bit8,
1940        };
1941        if matches!(w, BusWidth::Bit4) && self.data_pins < 4 {
1942            return Err(MmcError::Unsupported);
1943        }
1944        if matches!(w, BusWidth::Bit8) && self.data_pins < 8 {
1945            return Err(MmcError::Unsupported);
1946        }
1947        if hz > 40_000_000 {
1948            return Err(MmcError::Unsupported);
1949        }
1950        self.set_bus_low_level(w, hz)?;
1951        Ok(())
1952    }
1953
1954    fn supports_mmc(&self) -> bool {
1955        // Native parallel SD/MMC host (not SPI mode).
1956        true
1957    }
1958
1959    fn supports_auto_stop(&self) -> bool {
1960        true
1961    }
1962
1963    fn supports_bus_width(&self) -> sdio::BusWidth {
1964        if self.data_pins >= 8 {
1965            sdio::BusWidth::W8
1966        } else if self.data_pins >= 4 {
1967            sdio::BusWidth::W4
1968        } else {
1969            sdio::BusWidth::W1
1970        }
1971    }
1972
1973    fn supports_frequency(&self) -> u32 {
1974        40_000_000
1975    }
1976}
1977
1978/// Maps the engine's [`ResponseLen`] from the crate's typed response.
1979/// CMD12 (and SDIO abort) are stop/abort commands.
1980fn is_stop_or_abort(index: u8) -> bool {
1981    index == 12
1982}
1983
1984/// Whether the controller should auto-issue CMD12 (STOP_TRANSMISSION) after the
1985/// data phase.
1986///
1987/// Auto-stop is only valid for the open-ended SD/MMC memory multi-block
1988/// transfers (CMD18 `READ_MULTIPLE_BLOCK` / CMD25 `WRITE_MULTIPLE_BLOCK`).
1989/// SDIO CMD53 (`IO_RW_EXTENDED`) carries its own block count in the command and
1990/// must NOT be followed by CMD12: the card would not respond to it, surfacing as
1991/// a spurious `ResponseTimeout` at the end of the data phase.
1992fn needs_auto_stop(index: u8, block_count: u32) -> bool {
1993    block_count > 1 && matches!(index, 18 | 25)
1994}
1995
1996#[cfg(sdmmc_has_gpio_matrix)]
1997fn connect_bidir(
1998    pin: interconnect::OutputSignal<'_>,
1999    input: InputSignal,
2000    output: OutputSignal,
2001) -> PinGuard {
2002    pin.set_output_high(true);
2003    pin.apply_output_config(&OutputConfig::default().with_pull(Pull::Up));
2004    pin.set_output_enable(true);
2005    pin.set_input_enable(true);
2006    input.connect_to(&pin);
2007    interconnect::OutputSignal::connect_with_guard(pin, output)
2008}
2009
2010/// Spins up to `POLL_LIMIT` times until `ready` holds, else times out.
2011fn poll_until(mut ready: impl FnMut() -> bool) -> Result<(), Error> {
2012    for _ in 0..POLL_LIMIT {
2013        if ready() {
2014            return Ok(());
2015        }
2016    }
2017    Err(Error::Timeout)
2018}
2019
2020fn poll_until_timeout(timeout: Duration, mut ready: impl FnMut() -> bool) -> Result<(), Error> {
2021    let start = Instant::now();
2022    while !ready() {
2023        if start.elapsed() > timeout {
2024            return Err(Error::Timeout);
2025        }
2026    }
2027    Ok(())
2028}
2029
2030/// Spins until the CIU accepts the command (`start_cmd` self-clears).
2031fn wait_command_accepted() -> Result<(), Error> {
2032    let r = SDHOST::regs();
2033    for _ in 0..POLL_LIMIT {
2034        if !r.cmd().read().start_cmd().bit_is_set() {
2035            return Ok(());
2036        }
2037        // Hardware-locked error: clear and report.
2038        const HW_LOCKED: u32 = 1 << 12;
2039        if (r.rintsts().read().bits() & HW_LOCKED) != 0 {
2040            r.rintsts().write(|w| unsafe { w.bits(HW_LOCKED) });
2041            return Err(Error::Timeout);
2042        }
2043    }
2044    Err(Error::Timeout)
2045}
2046
2047/// Masks interrupts, tears down the IDMAC and clears transfer state.
2048fn abort_transfer() {
2049    let r = SDHOST::regs();
2050    r.intmask().write(|w| unsafe { w.bits(idle_intmask()) });
2051    r.idinten().write(|w| unsafe { w.bits(0) });
2052    disable_idmac();
2053    let _ = reset_transfer();
2054    TRANSFER.with(|ts| *ts = TransferState::IDLE);
2055}
2056
2057/// Awaits the terminal result the interrupt handler records.
2058#[must_use = "futures do nothing unless you `.await` or poll them"]
2059fn wait_result() -> impl Future<Output = Result<(), Error>> {
2060    poll_fn(|cx| {
2061        TRANSFER.with(|ts| match ts.result.take() {
2062            Some(res) => Poll::Ready(res),
2063            None => {
2064                ts.waker.register(cx.waker());
2065                Poll::Pending
2066            }
2067        })
2068    })
2069}
2070
2071/// Waits for the card to release DAT0 after a write via the Busy Clear
2072/// Interrupt.
2073///
2074/// The controller only raises the BCI (which shares the SBE status bit) for
2075/// data-write commands, and only when generation is enabled in `cardthrctl`;
2076/// the bit is left enabled solely for the duration of the wait so it cannot
2077/// be mistaken for a start-bit error during a multi-block transfer.
2078async fn wait_busy_async() -> Result<(), Error> {
2079    let r = SDHOST::regs();
2080
2081    // Fast path: the card may already be ready.
2082    if !r.status().read().data_busy().bit_is_set() {
2083        return Ok(());
2084    }
2085
2086    // Enable Busy Clear Interrupt generation, then arm and unmask it.
2087    r.cardthrctl().modify(|_, w| w.cardclrinten().set_bit());
2088    TRANSFER.with(|ts| {
2089        *ts = TransferState {
2090            wait_busy: true,
2091            ..TransferState::IDLE
2092        };
2093    });
2094    r.rintsts().write(|w| unsafe { w.bits(EVT_SBE) });
2095    r.intmask()
2096        .write(|w| unsafe { w.bits(idle_intmask() | EVT_SBE) });
2097
2098    // Close the arm race: if busy cleared between the check above and the
2099    // unmask, the rising edge is already gone, so bail out instead of
2100    // waiting for an interrupt that will never fire.
2101    let res = if !r.status().read().data_busy().bit_is_set() {
2102        TRANSFER.with(|ts| *ts = TransferState::IDLE);
2103        Ok(())
2104    } else {
2105        wait_result().await
2106    };
2107
2108    // Restore: stop generating the BCI and re-mask the shared SBE bit.
2109    r.cardthrctl().modify(|_, w| w.cardclrinten().clear_bit());
2110    r.intmask().write(|w| unsafe { w.bits(idle_intmask()) });
2111    res
2112}
2113
2114/// Polls DAT0 while the card signals busy (R1b).
2115///
2116/// Used after no-data commands (e.g. `CMD7`, `MMC_SWITCH`): the controller
2117/// does not generate a Busy Clear Interrupt for those, so polling is the
2118/// only option, mirroring ESP-IDF's `wait_for_busy_cleared`.
2119async fn wait_busy_poll() -> Result<(), Error> {
2120    let deadline = Instant::now() + BUSY_TIMEOUT;
2121    while SDHOST::regs().status().read().data_busy().bit_is_set() {
2122        let now = Instant::now();
2123        if now > deadline {
2124            return Err(Error::Timeout);
2125        }
2126        wait_until(now + BUSY_POLL_INTERVAL).await;
2127    }
2128    Ok(())
2129}
2130
2131/// Reads response registers into spec word order (`words[3]` is the MSW).
2132fn read_response(resp_len: ResponseLen) -> [u32; 4] {
2133    let r = SDHOST::regs();
2134    match resp_len {
2135        ResponseLen::None => [0; 4],
2136        ResponseLen::Short => [r.resp0().read().bits(), 0, 0, 0],
2137        ResponseLen::Long => [
2138            r.resp0().read().bits(),
2139            r.resp1().read().bits(),
2140            r.resp2().read().bits(),
2141            r.resp3().read().bits(),
2142        ],
2143    }
2144}
2145
2146/// Maps `rintsts` error bits to an [`Error`]; errors take priority.
2147fn map_rintsts(sts: u32) -> Result<(), Error> {
2148    if sts & EVT_HLE != 0 {
2149        return Err(Error::HardwareLocked);
2150    }
2151    if sts & EVT_RTO != 0 {
2152        return Err(Error::ResponseTimeout);
2153    }
2154    if sts & EVT_RCRC != 0 {
2155        return Err(Error::ResponseCrc);
2156    }
2157    if sts & EVT_RESP_ERR != 0 {
2158        return Err(Error::ResponseError);
2159    }
2160    if sts & (EVT_DTO | EVT_HTO) != 0 {
2161        return Err(Error::DataTimeout);
2162    }
2163    if sts & (EVT_DCRC | EVT_EBE) != 0 {
2164        return Err(Error::DataCrc);
2165    }
2166    if sts & EVT_SBE != 0 {
2167        return Err(Error::StartBitError);
2168    }
2169    if sts & EVT_FRUN != 0 {
2170        return Err(Error::FifoOverrun);
2171    }
2172    Ok(())
2173}
2174
2175/// Polls DAT0 until the card releases the busy signal.
2176fn wait_busy_cleared() -> Result<(), Error> {
2177    poll_until(|| !SDHOST::regs().status().read().data_busy().bit_is_set())
2178}
2179
2180/// Validates a buffer address for the SDMMC IDMAC and returns its DMA pointer.
2181///
2182/// The IDMAC reaches PSRAM only on chips with `sdmmc_psram_dma`.
2183fn dma_ptr(buf: DmaAlignedMut<'_, [u8]>) -> Result<u32, Error> {
2184    dma_ptr_from_raw(buf.as_ptr())
2185}
2186
2187/// Validates a buffer address for the SDMMC IDMAC and returns its DMA pointer.
2188///
2189/// The IDMAC reaches PSRAM only on chips with `sdmmc_psram_dma`.
2190fn dma_ptr_ref(buf: DmaAlignedRef<'_, [u8]>) -> Result<u32, Error> {
2191    dma_ptr_from_raw(buf.as_ptr())
2192}
2193
2194fn dma_ptr_from_raw(addr: *const u8) -> Result<u32, Error> {
2195    // Not in some weird region like flash or RTC memory.
2196    if crate::soc::is_valid_ram_address(addr as usize) {
2197        return Ok(addr as u32);
2198    }
2199    #[cfg(all(soc_has_psram, sdmmc_psram_dma))]
2200    if crate::soc::is_valid_psram_address(addr as usize) {
2201        return Ok(addr as u32);
2202    }
2203
2204    Err(Error::BufferNotDmaCapable)
2205}
2206
2207/// Waits for the command response then the data phase, refilling the ring.
2208fn run_data_phase(
2209    t: &mut Transfer,
2210    mut ring: DmaAlignedMut<'_, [Desc; RING_LEN]>,
2211    write: bool,
2212    auto_stop: bool,
2213) -> Result<(), Error> {
2214    let r = SDHOST::regs();
2215    let consume = EVT_CMD_DONE | EVT_RTO | EVT_RCRC | EVT_RESP_ERR | EVT_HLE;
2216
2217    // Command response phase.
2218    let done = EVT_CMD_DONE | EVT_RTO | EVT_RCRC | EVT_RESP_ERR;
2219    let mut sts = 0;
2220    poll_until(|| {
2221        sts = r.rintsts().read().bits();
2222        sts & done != 0
2223    })?;
2224    map_rintsts(sts)?;
2225    r.rintsts().write(|w| unsafe { w.bits(consume) });
2226
2227    // Data phase: wait for completion, refilling descriptors as the engine
2228    // frees them. No CPU-side iteration cap: a stalled card or host-side
2229    // FIFO starvation is terminated by the controller's data timeout
2230    // (DRTO/HTO), and a DMA fault by IDMAC FBE/DU, so the loop can only spin
2231    // while the transfer is genuinely making progress.
2232    let data_err = EVT_DCRC | EVT_DTO | EVT_HTO | EVT_SBE | EVT_EBE | EVT_FRUN;
2233    loop {
2234        let sts = r.rintsts().read().bits();
2235        if sts & data_err != 0 {
2236            map_rintsts(sts)?;
2237        }
2238        let id_sts = r.idsts().read();
2239        if id_sts.fbe().bit_is_set() || id_sts.du().bit_is_set() {
2240            return Err(Error::DmaError);
2241        }
2242        if t.remaining() > 0 {
2243            let free = free_descriptors(ring.reborrow(), t.next_desc);
2244            if free > 0 {
2245                fill_descriptors(ring.reborrow(), t, free);
2246                r.pldmnd().write(|w| unsafe { w.bits(1) });
2247            }
2248        }
2249        if sts & EVT_DATA_OVER != 0 {
2250            break;
2251        }
2252    }
2253
2254    // Open-ended memory multi-block transfers append an auto-stop (CMD12);
2255    // wait for its completion. This follows DATA_OVER promptly, so a bounded
2256    // wait is fine, but a missing completion must be reported rather than
2257    // silently ignored. SDIO CMD53 sends no CMD12, so there is nothing to wait
2258    // for.
2259    if auto_stop {
2260        poll_until(|| r.rintsts().read().bits() & EVT_ACD != 0)?;
2261    }
2262    if write {
2263        wait_busy_cleared()?;
2264    }
2265    Ok(())
2266}
2267
2268/// Counts descriptors the engine has released, starting at `next`.
2269fn free_descriptors(ring: DmaAlignedMut<'_, [Desc; RING_LEN]>, next: usize) -> usize {
2270    let mut count = 0;
2271    for i in 0..RING_LEN {
2272        let d = &ring[(next + i) % RING_LEN];
2273        if d.flags & DESC_OWN != 0 {
2274            break;
2275        }
2276        count += 1;
2277        if d.next == 0 {
2278            break;
2279        }
2280    }
2281    count
2282}
2283
2284/// Fills up to `count` descriptors from the remaining transfer (shared
2285/// blocking/async refill; mirrors `sd_host_fill_dma_descriptors`).
2286fn fill_descriptors(mut ring: DmaAlignedMut<'_, [Desc; RING_LEN]>, t: &mut Transfer, count: usize) {
2287    for _ in 0..count {
2288        // Skip exhausted (or empty) segments to find the next bytes to link.
2289        while t.seg < t.segs.len() && t.segs[t.seg].1 == 0 {
2290            t.seg += 1;
2291        }
2292        if t.seg >= t.segs.len() {
2293            break;
2294        }
2295
2296        let (ptr, rem) = t.segs[t.seg];
2297        let i = t.next_desc;
2298        let size = rem.min(DMA_MAX_BUF_LEN);
2299        // The transfer ends here only if this chunk drains the current segment
2300        // and no later segment still has data to link.
2301        let exhausts_seg = size == rem;
2302        let later_data = t.segs[t.seg + 1..].iter().any(|(_, len)| *len > 0);
2303        let last = exhausts_seg && !later_data;
2304        let next_ptr = if last {
2305            0
2306        } else {
2307            &ring[(i + 1) % RING_LEN] as *const Desc as u32
2308        };
2309        let first = ring[i].flags & DESC_FIRST;
2310        let d = &mut ring[i];
2311        d.flags = DESC_OWN | DESC_CHAINED | first | if last { DESC_LAST } else { 0 };
2312        d.sizes = ((size + 3) & !3) as u32;
2313        d.buf1 = ptr;
2314        d.next = next_ptr;
2315        t.segs[t.seg].0 = ptr + size as u32;
2316        t.segs[t.seg].1 = rem - size;
2317        t.next_desc = (i + 1) % RING_LEN;
2318    }
2319
2320    #[cfg(soc_internal_memory_cached)]
2321    ring.writeback();
2322}
2323
2324fn reset_transfer() -> Result<(), Error> {
2325    let r = SDHOST::regs();
2326    r.ctrl().modify(|_, w| w.fifo_reset().set_bit());
2327    let res = poll_until(|| !r.ctrl().read().fifo_reset().bit_is_set());
2328
2329    r.rintsts()
2330        .write(|w| unsafe { w.bits(!(EVT_IO_SLOT0 | EVT_IO_SLOT1)) });
2331    r.idsts().write(|w| unsafe { w.bits(0xFFFF_FFFF) });
2332
2333    res
2334}
2335
2336/// Enables the IDMAC engine for a transfer and programs the descriptor base.
2337///
2338/// `BMOD.SWR` resets the IDMAC's internal registers (including `DBADDR`) on
2339/// this IP, so the descriptor base must be written *after* the reset,
2340/// matching the ordering ESP-IDF uses in `sdmmc_host_dma_prepare`.
2341fn enable_idmac(dbaddr: u32) {
2342    let r = SDHOST::regs();
2343    r.ctrl()
2344        .modify(|rd, w| unsafe { w.bits(rd.bits() | CTRL_DMA_ENABLE | CTRL_USE_INTERNAL_DMA) });
2345    r.bmod().modify(|_, w| w.swr().set_bit());
2346    r.idinten().write(|w| unsafe { w.bits(0) });
2347    r.dbaddr().write(|w| unsafe { w.bits(dbaddr) });
2348    r.bmod().modify(|_, w| {
2349        w.de().set_bit();
2350        w.fb().set_bit()
2351    });
2352}
2353
2354/// Disables the IDMAC engine after a transfer.
2355fn disable_idmac() {
2356    let r = SDHOST::regs();
2357    r.ctrl()
2358        .modify(|rd, w| unsafe { w.bits(rd.bits() & !CTRL_USE_INTERNAL_DMA) });
2359    r.bmod().modify(|_, w| {
2360        w.de().clear_bit();
2361        w.fb().clear_bit()
2362    });
2363    r.ctrl().modify(|_, w| w.dma_reset().set_bit());
2364}
2365
2366/// Module clock in Hz for a given source and divider.
2367fn module_hz(source: ClockSource, div: u8) -> u32 {
2368    let base = match source {
2369        #[cfg(esp32s31)]
2370        ClockSource::Mpll => crate::clock::ll::mpll_clk_frequency(),
2371        #[cfg(not(esp32s31))]
2372        ClockSource::Pll160m => 160_000_000,
2373        //#[cfg(esp32p4)]
2374        // ClockSource::Apll => unimplemented!(),
2375        #[cfg(not(esp32p4))]
2376        ClockSource::Xtal => 40_000_000,
2377    };
2378    base / (div as u32)
2379}
2380
2381/// Computes the per-card divider for a target frequency.
2382///
2383/// `card_clk = module / (2 * div)`; `div == 0` bypasses the divider.
2384fn freq_to_card_div(module_hz: u32, target_hz: u32) -> u8 {
2385    if target_hz == 0 || module_hz <= target_hz {
2386        return 0;
2387    }
2388    let div = module_hz.div_ceil(2 * target_hz);
2389    div.clamp(1, 255) as u8
2390}
2391
2392#[must_use = "futures do nothing unless you `.await` or poll them"]
2393struct WaitForInterruptFuture {
2394    slot: usize,
2395    bit: u32,
2396}
2397
2398impl Future for WaitForInterruptFuture {
2399    type Output = ();
2400    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
2401        // Register before consuming so an edge racing the check wakes us.
2402        SLOT_STATE[self.slot].io_waker.register(cx.waker());
2403
2404        SDHOST::regs()
2405            .intmask()
2406            .modify(|rd, w| unsafe { w.bits(rd.bits() | self.bit) });
2407
2408        if SLOT_STATE[self.slot]
2409            .io_pending
2410            .swap(false, Ordering::AcqRel)
2411        {
2412            Poll::Ready(())
2413        } else {
2414            Poll::Pending
2415        }
2416    }
2417}
2418
2419impl Drop for WaitForInterruptFuture {
2420    fn drop(&mut self) {
2421        SDHOST::regs()
2422            .intmask()
2423            .modify(|rd, w| unsafe { w.bits(rd.bits() & !self.bit) });
2424    }
2425}