//! The SDMMC host controller, driven as an **SDIO host**.
//!
//! There is no SD card on this board. Slot 1 of the P4's SDMMC controller goes to an ESP32-C6
//! running ESP-Hosted coprocessor firmware, which presents itself as a 4-bit SDIO device: CLK 18,
//! CMD 19, D0-D3 = 14/15/16/17. So this file implements CMD0/CMD5/CMD3/CMD7 and then CMD52/CMD53,
//! and nothing above them. SD memory cards, SPI mode, CSD/CID decoding and block devices are
//! deliberately absent - they are a different problem that happens to share a peripheral.
//!
//! The controller is a Synopsys DesignWare mobile-storage host. Three of its properties decide the
//! shape of everything below.
//!
//! **The card clock is not the register clock.** CLKDIV, CLKSRC and CLKENA are written on the bus
//! side and do not reach the card-interface unit until a *clock update command* is issued: a write
//! to the CMD register with `update_clk_reg` and `start_command` set, which sends nothing to the
//! card (`sdmmc_reg.h:440-456`, and ESP-IDF's `sd_host_slot_clock_update_command`,
//! `sd_host_sdmmc.c:896-912`). A driver that programmes a divider and moves on has changed
//! nothing. Three such commands are needed to change frequency safely - clock off, reprogramme,
//! clock on - and that is what `setBusClock` does.
//!
//! **The command register is a single word, and `start_command` is bit 31 of it.** Every attribute
//! of a command - index, whether a response is expected, whether its CRC is checked, whether data
//! follows and in which direction - is a field of the same word, and writing that word with bit 31
//! set launches the command. So the interesting part of "send CMD52" is an encoding, not a
//! sequence, and `commandWord` is a pure function of the request. It is host-tested, and the
//! oracle compares the words it produces against words built through ESP-IDF's own
//! `sdmmc_hw_cmd_t` bitfields.
//!
//! **Data moves by internal DMA over descriptors in memory, and the P4 caches that memory.**
//! `soc_caps.h:185` sets SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE, so L2MEM - where every static in this
//! image lives - is reached by the CPU through the L1 data cache while the IDMAC reaches it
//! directly. See the "Cache" section below for the resolution; it is the one place in this file
//! where the right answer is not visible in any register header.
//!
//! Nothing here has been run on hardware by the author of this file. What is claimed is that the
//! register arithmetic and the command encodings match ESP-IDF's at the cited lines, that
//! `src/oracle/sdmmc_cases.zig` compares the two on the die, and that the configuration `init`
//! leaves behind reproduces a dump taken from a working ESP-IDF image on this board.

const std = @import("std");
const regs = @import("regs");
const mmio = @import("mmio");
const gpio = @import("gpio.zig");
const clkrst = @import("clkrst.zig");
const intr = @import("intr.zig");

const Reg = mmio.Reg;
const Field = mmio.Field;

pub const Error = error{ Timeout, CrcError, ResponseError, NotSupported, Busy };

// ------------------------------------------------------------------------------- registers
//
// One instance, at DR_REG_SDHOST_BASE = DR_REG_SDMMC_BASE = 0x50083000 (`reg_base.h:44`, `:204`,
// and `esp32p4.peripherals.ld:41` agrees). The macros are spelled SDHOST_*, the peripheral is
// spelled SDMMC, and both names are ESP-IDF's.

const ctrl = Reg.at(regs.SDHOST_CTRL_REG);
const clkdiv = Reg.at(regs.SDHOST_CLKDIV_REG);
const clksrc = Reg.at(regs.SDHOST_CLKSRC_REG);
const clkena = Reg.at(regs.SDHOST_CLKENA_REG);
const tmout = Reg.at(regs.SDHOST_TMOUT_REG);
const ctype = Reg.at(regs.SDHOST_CTYPE_REG);
const blksiz = Reg.at(regs.SDHOST_BLKSIZ_REG);
const bytcnt = Reg.at(regs.SDHOST_BYTCNT_REG);
const intmask = Reg.at(regs.SDHOST_INTMASK_REG);
const cmdarg = Reg.at(regs.SDHOST_CMDARG_REG);
const cmd = Reg.at(regs.SDHOST_CMD_REG);
const resp0 = Reg.at(regs.SDHOST_RESP0_REG);
const rintsts = Reg.at(regs.SDHOST_RINTSTS_REG);
/// The *masked* status: RINTSTS gated by INTMASK, and the only word the controller's interrupt
/// output looks at. ESP-IDF's `sdmmc_ll_get_intr_status` reads this one and not RINTSTS
/// (`sdmmc_ll.h:841-844`), which is exactly why INTMASK decides what reaches the CLIC while
/// RINTSTS stays readable for the polling path.
const mintsts = Reg.at(regs.SDHOST_MINTSTS_REG);
const status = Reg.at(regs.SDHOST_STATUS_REG);
const fifoth = Reg.at(regs.SDHOST_FIFOTH_REG);
const bmod = Reg.at(regs.SDHOST_BMOD_REG);
const pldmnd = Reg.at(regs.SDHOST_PLDMND_REG);
const dbaddr = Reg.at(regs.SDHOST_DBADDR_REG);
const idsts = Reg.at(regs.SDHOST_IDSTS_REG);
const idinten = Reg.at(regs.SDHOST_IDINTEN_REG);

// CTRL fields. Two of them - `dma_enable` at bit 5 and `use_internal_dma` at bit 25 - have no
// `_S`/`_V` macro pair in `sdmmc_reg.h` at all: that header documents CTRL as bits 0,1,2,4,6..11
// and stops. They are real, they are in the measured working dump (`ctrl=0x02000030`), and
// `sdmmc_struct.h:76` and `:135` name them at exactly those positions. This is the same situation
// as the IO MUX pull bits in `hal/gpio.zig`, and the same remedy: `Field.bit` with the struct
// header cited, because the struct header is ESP-IDF's definition of the layout even where the
// macro header is incomplete.
const controller_reset = Field.of(regs.SDHOST_CONTROLLER_RESET_S, regs.SDHOST_CONTROLLER_RESET_V);
const fifo_reset = Field.of(regs.SDHOST_FIFO_RESET_S, regs.SDHOST_FIFO_RESET_V);
const dma_reset = Field.of(regs.SDHOST_DMA_RESET_S, regs.SDHOST_DMA_RESET_V);
const int_enable = Field.of(regs.SDHOST_INT_ENABLE_S, regs.SDHOST_INT_ENABLE_V);
/// `sdmmc_struct.h:76` - `uint32_t dma_enable:1;` immediately after `int_enable:1` at bit 4.
const dma_enable = Field.bit(5);
/// `sdmmc_struct.h:135` - after `reserved2:4`, `card_voltage_a:4`, `card_voltage_b:4` and
/// `enable_od_pullup:1`, i.e. bit 25. `sdmmc_ll_enable_dma` (`sdmmc_ll.h:812-818`) is the only
/// writer, and the working dump's `ctrl=0x02000030` has exactly this bit plus 4 and 5.
const use_internal_dma = Field.bit(25);

const clk_divider0 = Field.of(regs.SDHOST_CLK_DIVIDER0_S, regs.SDHOST_CLK_DIVIDER0_V);
const clk_divider1 = Field.of(regs.SDHOST_CLK_DIVIDER1_S, regs.SDHOST_CLK_DIVIDER1_V);
// CLKSRC is documented as one 4-bit field, two bits per card ("bit[1:0] are assigned for card 0,
// bit[3:2] are assigned for card 1", `sdmmc_reg.h:166-179`). `sdmmc_struct.h:191-192` splits it
// into `card0:2` and `card1:2`, which is the shape a driver wants; there are no macros for the
// halves, so the two sub-fields are spelled out with that citation.
const clksrc_card0 = Field.of(0, 0x3);
const clksrc_card1 = Field.of(2, 0x3);
const cclk_enable = Field.of(regs.SDHOST_CCLK_ENABLE_S, regs.SDHOST_CCLK_ENABLE_V);
const lp_enable = Field.of(regs.SDHOST_LP_ENABLE_S, regs.SDHOST_LP_ENABLE_V);
const response_timeout = Field.of(regs.SDHOST_RESPONSE_TIMEOUT_S, regs.SDHOST_RESPONSE_TIMEOUT_V);
const data_timeout = Field.of(regs.SDHOST_DATA_TIMEOUT_S, regs.SDHOST_DATA_TIMEOUT_V);
const card_width4 = Field.of(regs.SDHOST_CARD_WIDTH4_S, regs.SDHOST_CARD_WIDTH4_V);
const card_width8 = Field.of(regs.SDHOST_CARD_WIDTH8_S, regs.SDHOST_CARD_WIDTH8_V);
const block_size = Field.of(regs.SDHOST_BLOCK_SIZE_S, regs.SDHOST_BLOCK_SIZE_V);
const byte_count = Field.of(regs.SDHOST_BYTE_COUNT_S, regs.SDHOST_BYTE_COUNT_V);
const int_mask = Field.of(regs.SDHOST_INT_MASK_S, regs.SDHOST_INT_MASK_V);
const sdio_int_mask = Field.of(regs.SDHOST_SDIO_INT_MASK_S, regs.SDHOST_SDIO_INT_MASK_V);
const data_busy = Field.of(regs.SDHOST_DATA_BUSY_S, regs.SDHOST_DATA_BUSY_V);
const tx_wmark = Field.of(regs.SDHOST_TX_WMARK_S, regs.SDHOST_TX_WMARK_V);
const rx_wmark = Field.of(regs.SDHOST_RX_WMARK_S, regs.SDHOST_RX_WMARK_V);
const dma_msize = Field.of(regs.SDHOST_DMA_MULTIPLE_TRANSACTION_SIZE_S, regs.SDHOST_DMA_MULTIPLE_TRANSACTION_SIZE_V);
const bmod_swr = Field.of(regs.SDHOST_BMOD_SWR_S, regs.SDHOST_BMOD_SWR_V);
const bmod_fb = Field.of(regs.SDHOST_BMOD_FB_S, regs.SDHOST_BMOD_FB_V);
const bmod_de = Field.of(regs.SDHOST_BMOD_DE_S, regs.SDHOST_BMOD_DE_V);
const idinten_ti = Field.of(regs.SDHOST_IDINTEN_TI_S, regs.SDHOST_IDINTEN_TI_V);
const idinten_ri = Field.of(regs.SDHOST_IDINTEN_RI_S, regs.SDHOST_IDINTEN_RI_V);
const idinten_ni = Field.of(regs.SDHOST_IDINTEN_NI_S, regs.SDHOST_IDINTEN_NI_V);

// The host-side clock generator, which is *not* in the SDMMC block: the P4 moved it into
// HP_SYS_CLKRST, and it is the first of two divider stages (this one, then CLKDIV inside the
// controller). `sdmmc_ll.h:227-228` for the source mux and gate, `:244-258` for the divider,
// `:305-315` for the sampling/driving phase clocks.
const peri_clk_ctrl01 = Reg.at(regs.HP_SYS_CLKRST_PERI_CLK_CTRL01_REG);
const peri_clk_ctrl02 = Reg.at(regs.HP_SYS_CLKRST_PERI_CLK_CTRL02_REG);

const sdio_hs_mode = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_HS_MODE_S, regs.HP_SYS_CLKRST_REG_SDIO_HS_MODE_V);
const sdio_ls_clk_src_sel = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_SRC_SEL_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_SRC_SEL_V);
const sdio_ls_clk_en = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EN_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EN_V);
const sdio_ls_clk_edge_cfg_update = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EDGE_CFG_UPDATE_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EDGE_CFG_UPDATE_V);
const sdio_ls_clk_edge_l = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EDGE_L_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EDGE_L_V);
const sdio_ls_clk_edge_h = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EDGE_H_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EDGE_H_V);
const sdio_ls_clk_edge_n = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EDGE_N_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_CLK_EDGE_N_V);
const sdio_ls_slf_clk_edge_sel = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_SLF_CLK_EDGE_SEL_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_SLF_CLK_EDGE_SEL_V);
const sdio_ls_drv_clk_edge_sel = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_DRV_CLK_EDGE_SEL_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_DRV_CLK_EDGE_SEL_V);
const sdio_ls_sam_clk_edge_sel = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_SAM_CLK_EDGE_SEL_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_SAM_CLK_EDGE_SEL_V);
const sdio_ls_slf_clk_en = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_SLF_CLK_EN_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_SLF_CLK_EN_V);
const sdio_ls_drv_clk_en = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_DRV_CLK_EN_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_DRV_CLK_EN_V);
const sdio_ls_sam_clk_en = Field.of(regs.HP_SYS_CLKRST_REG_SDIO_LS_SAM_CLK_EN_S, regs.HP_SYS_CLKRST_REG_SDIO_LS_SAM_CLK_EN_V);

// --------------------------------------------------------------------------------- interrupts
//
// RINTSTS / INTMASK share one 16-bit layout plus a 2-bit per-card SDIO field at [17:16].
// `sdmmc_ll.h:35-53` names every bit; the numbers below are those, not a re-derivation.

pub const Event = struct {
    pub const cd: u32 = 1 << 0; // card detect
    pub const re: u32 = 1 << 1; // response error
    pub const cmd_done: u32 = 1 << 2;
    pub const dto: u32 = 1 << 3; // data transfer over
    pub const txdr: u32 = 1 << 4;
    pub const rxdr: u32 = 1 << 5;
    pub const rcrc: u32 = 1 << 6; // response CRC error
    pub const dcrc: u32 = 1 << 7; // data CRC error
    pub const rto: u32 = 1 << 8; // response timeout
    pub const drto: u32 = 1 << 9; // data read timeout
    pub const hto: u32 = 1 << 10; // data starvation by host timeout
    pub const frun: u32 = 1 << 11; // FIFO under/overrun
    pub const hle: u32 = 1 << 12; // hardware locked write error
    pub const sbe: u32 = 1 << 13; // RX start-bit error
    pub const acd: u32 = 1 << 14; // auto command done
    pub const ebe: u32 = 1 << 15; // end-bit error
    pub const io_slot0: u32 = 1 << 16;
    pub const io_slot1: u32 = 1 << 17;

    /// What `sdmmc_ll.h:64-69` (SDMMC_LL_EVENT_DEFAULT) enables at init. Kept exactly as ESP-IDF
    /// spells it, because the oracle compares against it; what this driver actually unmasks is
    /// `armed`, below.
    pub const default: u32 = cd | re | cmd_done | dto | rcrc | dcrc | rto | drto | hto | hle | sbe | ebe;

    /// `default` without card detect, and the only mask `configureInterrupts` ever writes.
    ///
    /// Bit 0 has to go, and this is not a preference. There is no card-detect pin on this board:
    /// `configurePins` ties the signal to a matrix constant 0 ("card present"), and the
    /// transition it makes while doing so *latches* RINTSTS.cd. RINTSTS is a sticky
    /// write-1-to-clear register and nothing in the command path clears bit 0 - `sendCommand`
    /// deliberately writes `default & ~cd` so as not to disturb asynchronous events. So with cd
    /// unmasked, the controller's single output line into the CLIC is asserted from bring-up
    /// onwards and never deasserts, and anyone who enables that CLIC line takes an interrupt
    /// storm that no handler can end. Found by RxPath on CLIC line 21; the fix belongs here
    /// rather than in the handler, because a level output that nothing can lower is this file's
    /// bug.
    ///
    /// The two SDIO card-interrupt bits are absent from both masks: `setSlaveInterruptEnabled`
    /// turns the one for this slot on when somebody is prepared to service it.
    pub const armed: u32 = default & ~cd;

    /// Anything in here means the command failed. `sdmmc_ll.h:71-77` calls the superset
    /// SDMMC_LL_SD_EVENT_MASK; this is the error half of it.
    pub const command_errors: u32 = re | rcrc | rto | hle;
    pub const data_errors: u32 = dcrc | drto | hto | frun | sbe | ebe;
};

/// The IDMAC's five reportable events - TI, RI, FBE, DU, CES - as one mask. `sdmmc_ll.h:83`
/// SDMMC_LL_EVENT_DMA_MASK.
const idsts_event_mask: u32 = 0x1f;

/// The CLIC source this controller raises, for a caller that wants to be woken rather than to
/// poll. Registering a handler is `hal.intr`'s job and not this file's: see the note on
/// `slaveInterruptPending`.
pub const interrupt_source = intr.Source.sdio_host;

// -------------------------------------------------------------------------------------- cache
//
// The IDMAC reads its descriptors and its data buffer straight out of L2MEM. The CPU reaches the
// same L2MEM through the L1 data cache (`soc_caps.h:185`, SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE), and
// that cache is write-back: `esp_cache_msync(..., DIR_C2M)` exists precisely because a store the
// CPU has made may still be sitting in a dirty line when the DMA engine reads memory.
//
// ESP-IDF offers two ways out and uses both. `sd_trans_sdmmc.c:135-139` writes descriptors through
// the normal address and calls `esp_cache_msync` after every one. `gdma_link.c:100-118` does it
// the other way: one write-back-and-invalidate when the region is created, and from then on every
// CPU access goes through the non-cacheable alias at `addr + 0x40000000`
// (`hal/cache_ll.h:27` CACHE_LL_L2MEM_NON_CACHE_ADDR, `soc/ext_mem_defs.h:68`).
//
// **This file takes the second route.** It is the cheaper one - no cache call in the transfer
// path - and it is the only one that stays correct without a cache HAL this project does not have.
// The one-time write-back-and-invalidate is still required, and skipping it is a real bug rather
// than a theoretical one: `_start` clears .bss with ordinary stores (`src/main.zig:85-92`), so
// every word of the DMA region below starts life as a *dirty* cache line full of zeros. Nothing
// says when those lines are evicted; if one is written back after a descriptor has been prepared
// through the alias, the descriptor becomes zero and the IDMAC stalls on an unowned descriptor.
// `gdma_link.c:107-112` does exactly this call for exactly this reason.
//
// The two ROM entry points are addressed directly rather than declared `extern`, because the
// generated linker script provides only `ets_printf` and `ets_delay_us`. The addresses are
// ESP-IDF's, from `components/esp_rom/esp32p4/ld/esp32p4.rom.ld:186` and `:190` - the hw_ver1
// file, which is the one that matches this die. (If they move into the linker script beside the
// other two, these two lines become `extern fn` and nothing else changes.)

/// `soc/ext_mem_defs.h:68` SOC_NON_CACHEABLE_OFFSET.
pub const non_cacheable_offset: u32 = 0x4000_0000;

/// `cache_ll_l1_dcache_get_line_size` reports this on the P4, and `sdmmc_struct.h:36-38` states it
/// in prose: "On P4, L1 Cache alignment is 64B".
pub const cache_line: u32 = 64;

/// `rom/cache.h:230` - CACHE_MAP_L1_DCACHE is BIT(4).
const cache_map_l1_dcache: u32 = 1 << 4;

const romCacheWriteBackAddr: *const fn (map: u32, addr: u32, size: u32) callconv(.c) c_int =
    @ptrFromInt(0x4fc0_03f4);
const romCacheInvalidateAddr: *const fn (map: u32, addr: u32, size: u32) callconv(.c) c_int =
    @ptrFromInt(0x4fc0_03e4);

// ------------------------------------------------------------------------------- DMA descriptor

/// One IDMAC descriptor, exactly as the hardware reads it: `sdmmc_struct.h:13-41`.
///
/// ESP-IDF's `sdmmc_desc_t` is 64 bytes, not 16, and its own comment says why and when not to:
/// "These `reserved[12]` are for cache alignment... For those who want to access the DMA
/// descriptor in a non-cacheable way, you can consider remove these `reserved[12]` bytes"
/// (`sdmmc_struct.h:35-39`). That is this file, so the padding is gone and the descriptor is the
/// 16 bytes the IDMAC actually fetches.
pub const Descriptor = extern struct {
    flags: u32,
    /// [12:0] buffer1_size, [25:13] buffer2_size.
    sizes: u32,
    buffer1: u32,
    /// Also `buffer2_ptr`; which one it is depends on `second_address_chained`.
    next: u32,

    pub const disable_int_on_completion: u32 = 1 << 1;
    pub const last_descriptor: u32 = 1 << 2;
    pub const first_descriptor: u32 = 1 << 3;
    pub const second_address_chained: u32 = 1 << 4;
    pub const end_of_ring: u32 = 1 << 5;
    pub const card_error_summary: u32 = 1 << 30;
    pub const owned_by_idmac: u32 = 1 << 31;

    /// `sdmmc_struct.h:43` SDMMC_DMA_MAX_BUF_LEN. `buffer1_size` is 13 bits wide, so 8191 would
    /// fit; ESP-IDF splits at 4096 and so does the bound below.
    pub const max_buffer_len: u32 = 4096;
};

/// Bytes of L2MEM this driver owns, and the whole of its dynamic memory: there is no allocator
/// here and no allocation anywhere in the transfer path.
///
/// 2 KiB of payload is chosen against what sits above: ESP-Hosted's SDIO transport moves at most
/// one 1600-byte frame plus its 12-byte header per CMD53, and the largest single command this
/// driver can express in block mode is 4 blocks of 512. Anything larger is split across commands
/// by `transferChunked`, which is correct for both addressing modes, so the number is a
/// speed/footprint trade and not a limit.
pub const bounce_len: u32 = 2048;

/// Descriptor and bounce buffer in one cache-line-aligned region, so the one-time maintenance call
/// is one call over one range whose base and length are both multiples of 64.
const DmaRegion = extern struct {
    desc: Descriptor,
    _pad: [cache_line - @sizeOf(Descriptor)]u8,
    buf: [bounce_len]u8,
};

comptime {
    std.debug.assert(@sizeOf(Descriptor) == 16);
    std.debug.assert(@sizeOf(DmaRegion) % cache_line == 0);
    // One descriptor is enough only while the bounce buffer fits in one. If `bounce_len` ever
    // grows past 4096 this has to become a ring, and this line is what will say so.
    std.debug.assert(bounce_len <= Descriptor.max_buffer_len);
}

/// 2112 bytes: 16 of descriptor, 48 of padding to a cache line, 2048 of payload.
var dma: DmaRegion align(cache_line) = std.mem.zeroes(DmaRegion);

/// Addresses are `usize` rather than `u32` all the way to the register write. On this target the
/// two are the same type; on the host, where the arithmetic in these helpers is unit-tested,
/// `@intCast` of a real 64-bit address would panic before the test could check anything.
inline fn cachedAddr(p: *const anyopaque) usize {
    return @intFromPtr(p);
}

/// The address the *CPU* must use for anything in the DMA region. The hardware gets the cached
/// address - that is not an inconsistency, it is what ESP-IDF does: `gdma_link.c:268-273` hands
/// `list->items` to the peripheral and `:159` writes through `list->items_nc`. The alias exists to
/// change how the CPU's loads and stores are treated, and a bus master is not the CPU.
inline fn uncachedAddr(p: *const anyopaque) usize {
    return cachedAddr(p) +% @as(usize, non_cacheable_offset);
}

/// An address as the 32-bit register field the hardware reads it through.
inline fn busAddr(p: *const anyopaque) u32 {
    return @intCast(cachedAddr(p));
}

inline fn descNc() *volatile Descriptor {
    return @ptrFromInt(uncachedAddr(&dma.desc));
}

inline fn bufNc() [*]volatile u8 {
    return @ptrFromInt(uncachedAddr(&dma.buf));
}

/// Write back and invalidate the DMA region once, so that no dirty line from `_start`'s .bss clear
/// can later land on top of what the alias writes. After this, the cached alias of this region is
/// never touched again by anything in this file.
fn syncDmaRegionOnce() void {
    const base = busAddr(&dma);
    const len: u32 = @sizeOf(DmaRegion);
    _ = romCacheWriteBackAddr(cache_map_l1_dcache, base, len);
    _ = romCacheInvalidateAddr(cache_map_l1_dcache, base, len);
}

// -------------------------------------------------------------------------------------- timing
//
// Every wait in this file is bounded, and bounded in time rather than in loop iterations: a spin
// count is a different number on every optimize level, and this board has no debugger, so a wait
// that never returns is indistinguishable from a crash.
//
// The timebase is the RISC-V `cycle` CSR, the unprivileged shadow of `mcycle`, which is what
// ESP-IDF itself reads on this part (`rv_utils.h`, because SOC_CPU_HAS_CSR_PC is not defined for
// the P4) and what `src/soc.zig:116-131` already uses. It is deliberately *not* `hal.systimer`:
// systimer's `init` pulses the peripheral's reset, which would make the timebase jump under any
// other user, and `systimer.read` returns null when nothing has brought it up - neither is a
// property a bus driver should impose on its caller.
//
// The CPU clock is whatever the bootloader left, measured at 90 MHz on this board and rated to
// 400. Deadlines are computed at the 400 MHz *ceiling*, so on real silicon every timeout below is
// between 1x and 4.4x longer than its nominal microseconds. That is the safe direction: a timeout
// that fires early would turn a slow card into a spurious failure, and a timeout 4x long still
// terminates.
const assumed_cpu_hz_max: u32 = 400_000_000;

inline fn cycleLow() u32 {
    return asm volatile ("csrr %[r], 0xC00"
        : [r] "=r" (-> u32),
    );
}

/// A bounded wait. 32 bits of cycle counter wrap after 10.7 s at the assumed ceiling, which is an
/// order of magnitude past the longest deadline here, and the wrapping subtraction is correct
/// across the wrap anyway.
const Deadline = struct {
    start: u32,
    budget: u32,

    inline fn init(us: u32) Deadline {
        return .{ .start = cycleLow(), .budget = us *% (assumed_cpu_hz_max / 1_000_000) };
    }

    inline fn expired(self: Deadline) bool {
        return (cycleLow() -% self.start) >= self.budget;
    }
};

/// `sd_host_private.h:62` SD_HOST_SDMMC_RESET_TIMEOUT_US.
const reset_timeout_us: u32 = 5_000_000;
/// `sd_host_private.h:61` SD_HOST_SDMMC_START_CMD_TIMEOUT_US - how long the CIU may take to accept
/// a command word, which is a bus-side handshake and nothing to do with the card.
const start_cmd_timeout_us: u32 = 1_000_000;
/// How long to wait for the card's response after the command has been accepted. The controller
/// has its own response timeout (TMOUT.response_timeout, 255 card clocks) and raises RTO, so this
/// only has to cover the case where the controller itself never reports anything.
const command_done_timeout_us: u32 = 200_000;
/// Data phase. TMOUT.data_timeout is programmed to 100 ms of card clocks, matching
/// `sd_host_sdmmc.c:531-533`; this outer bound is twice that.
const data_done_timeout_us: u32 = 200_000;
/// How long the card may hold DAT0 low before a new data command.
const busy_timeout_us: u32 = 500_000;

// ------------------------------------------------------------------------------------- geometry

pub const Width = enum { one, four };

/// Slot 1's pads on this board, and the GPIO-matrix signal each carries.
///
/// Slot 0 has a direct IO MUX function and slot 1 does not
/// (`sdmmc_ll.h:88` SDMMC_LL_SLOT_SUPPORT_GPIO_MATRIX(1) is 1, and `sdmmc_periph.c:37-49` has
/// -1 for every slot-1 IO MUX pin), so every slot-1 signal is routed through the matrix. The
/// indices are `gpio_sig_map.h:8-18`, reached here through `regs` rather than written out: the
/// same discipline `hal/gpio.zig` applies to SIG_GPIO_OUT_IDX, for the same reason.
pub const Pins = struct {
    clk: u8,
    cmd: u8,
    d0: u8,
    d1: u8,
    d2: u8,
    d3: u8,
};

/// The ESP32-C6 coprocessor's wiring on this board. CLK 18, CMD 19, D0-D3 = 14/15/16/17.
pub const c6_pins: Pins = .{ .clk = 18, .cmd = 19, .d0 = 14, .d1 = 15, .d2 = 16, .d3 = 17 };

const sig = struct {
    const cclk: u32 = @intCast(regs.SD_CARD_CCLK_2_PAD_OUT_IDX);
    const ccmd: u32 = @intCast(regs.SD_CARD_CCMD_2_PAD_OUT_IDX);
    const cdata0: u32 = @intCast(regs.SD_CARD_CDATA0_2_PAD_OUT_IDX);
    const cdata1: u32 = @intCast(regs.SD_CARD_CDATA1_2_PAD_OUT_IDX);
    const cdata2: u32 = @intCast(regs.SD_CARD_CDATA2_2_PAD_OUT_IDX);
    const cdata3: u32 = @intCast(regs.SD_CARD_CDATA3_2_PAD_OUT_IDX);
    const card_detect: u32 = @intCast(regs.SD_CARD_DETECT_N_2_PAD_IN_IDX);
    const card_int: u32 = @intCast(regs.SD_CARD_INT_N_2_PAD_IN_IDX);

    comptime {
        // The `_2` in these names is slot 1: `sdmmc_periph.c:52-76` fills
        // `sdmmc_slot_gpio_sig[1]` from exactly these macros. Slot 0's set is named `_1` and would
        // route the wrong controller port to the C6's pads, silently.
        std.debug.assert(cclk == 0 and ccmd == 1 and cdata0 == 2);
        std.debug.assert(cdata1 == 3 and cdata2 == 4 and cdata3 == 5);

        // The card interrupt is sensed on D1's *input* index, and `configurePins` hands `matrixIn`
        // the *output* one - correct only because the P4's two signal tables agree on this signal.
        // `gpio_sig_map.h:13-14` gives cdata1 the number 3 in both directions, and ESP-IDF relies
        // on the same coincidence: `configure_pin_gpio_matrix` (`sd_host_sdmmc.c:1091-1105`) passes
        // one `gpio_matrix_sig` to both `esp_rom_gpio_connect_in_signal` and `..._out_signal`.
        // Asserted rather than assumed, because a mismatch here would route data correctly and
        // sense interrupts from the wrong pad - which is invisible until something waits.
        std.debug.assert(cdata1 == @as(u32, @intCast(regs.SD_CARD_CDATA1_2_PAD_IN_IDX)));
    }
};

// -------------------------------------------------------------------------------------- state

const State = struct {
    slot: u1 = 1,
    width: Width = .four,
    /// The frequency `cardInit` switches to once the card is addressed and in 4-bit mode.
    target_khz: u32 = 40_000,
    pins: Pins = c6_pins,
    /// Relative card address from CMD3, needed as the argument of CMD7.
    rca: u16 = 0,
    initialised: bool = false,
};

var state: State = .{};

/// The card's relative address, as returned by CMD3. Zero until `cardInit` has run.
pub fn rca() u16 {
    return state.rca;
}

inline fn slotBit() u32 {
    return @as(u32, 1) << state.slot;
}

// ------------------------------------------------------------------------------ command words
//
// One word, one function, no hardware. This is the part of the driver most worth testing on the
// host, and the part the oracle can compare against ESP-IDF's own bitfield struct without going
// anywhere near the card.

/// Compose one field's contribution to a register word. `mmio.Reg.write` does this against a
/// register; here the destination is a value, because the command word is built, checked and only
/// then stored.
inline fn bits(comptime f: Field, v: u32) u32 {
    return (v & f.unshiftedMask()) << f.shift;
}

const cmd_index = Field.of(regs.SDHOST_CMD_INDEX_S, regs.SDHOST_CMD_INDEX_V);
const response_expect = Field.of(regs.SDHOST_RESPONSE_EXPECT_S, regs.SDHOST_RESPONSE_EXPECT_V);
const response_length = Field.of(regs.SDHOST_RESPONSE_LENGTH_S, regs.SDHOST_RESPONSE_LENGTH_V);
const check_response_crc = Field.of(regs.SDHOST_CHECK_RESPONSE_CRC_S, regs.SDHOST_CHECK_RESPONSE_CRC_V);
const data_expected = Field.of(regs.SDHOST_DATA_EXPECTED_S, regs.SDHOST_DATA_EXPECTED_V);
const read_write = Field.of(regs.SDHOST_READ_WRITE_S, regs.SDHOST_READ_WRITE_V);
const transfer_mode = Field.of(regs.SDHOST_TRANSFER_MODE_S, regs.SDHOST_TRANSFER_MODE_V);
const send_auto_stop = Field.of(regs.SDHOST_SEND_AUTO_STOP_S, regs.SDHOST_SEND_AUTO_STOP_V);
const wait_prvdata_complete = Field.of(regs.SDHOST_WAIT_PRVDATA_COMPLETE_S, regs.SDHOST_WAIT_PRVDATA_COMPLETE_V);
const stop_abort_cmd = Field.of(regs.SDHOST_STOP_ABORT_CMD_S, regs.SDHOST_STOP_ABORT_CMD_V);
const send_initialization = Field.of(regs.SDHOST_SEND_INITIALIZATION_S, regs.SDHOST_SEND_INITIALIZATION_V);
const card_number = Field.of(regs.SDHOST_CARD_NUMBER_S, regs.SDHOST_CARD_NUMBER_V);
const update_clock_registers_only = Field.of(regs.SDHOST_UPDATE_CLOCK_REGISTERS_ONLY_S, regs.SDHOST_UPDATE_CLOCK_REGISTERS_ONLY_V);
/// `sdmmc_reg.h:486-494` spells this `USE_HOLE_REG`; `sdmmc_struct.h:473` spells it
/// `use_hold_reg`, which is what it is - the hold register that synchronises CMD and DATA to
/// cclk_out. Same bit 29, and ESP-IDF sets it on every command (`sd_host_sdmmc.c:859-860`).
const use_hold_reg = Field.of(regs.SDHOST_USE_HOLE_REG_S, regs.SDHOST_USE_HOLE_REG_V);
const start_cmd = Field.of(regs.SDHOST_START_CMD_S, regs.SDHOST_START_CMD_V);

pub const Response = enum { none, short, long };
pub const Direction = enum { read, write };

/// Everything that distinguishes one command from another, in the terms the register uses.
pub const Command = struct {
    index: u6,
    response: Response = .none,
    /// Whether the controller checks the response's CRC7. Off for R3 and R4, which do not carry a
    /// valid one - `sd_protocol_types.h:140-141` define both without SCF_RSP_CRC, and
    /// `make_hw_cmd` (`sd_trans_sdmmc.c:214-216`) keys `check_response_crc` off exactly that flag.
    check_crc: bool = false,
    data: ?Direction = null,
    /// 80 clocks of 1 before the command. Required once after power-on, and set only for CMD0,
    /// which is where ESP-IDF sets it (`sd_trans_sdmmc.c:197-206`).
    send_init: bool = false,
    /// Wait for a previous data transfer to finish before sending. Set on everything except CMD0,
    /// CMD12 and CMD11, again following `make_hw_cmd`.
    wait_prvdata: bool = true,
    auto_stop: bool = false,
    stop_abort: bool = false,
    /// Not a command at all: push CLKDIV/CLKSRC/CLKENA into the card clock domain.
    update_clock: bool = false,
    slot: u1 = 0,
};

/// The 32-bit word that, written to SDHOST_CMD_REG, issues `c`.
///
/// This is `make_hw_cmd` (`sd_trans_sdmmc.c:190-229`) plus the three fields
/// `sd_host_slot_start_command` adds afterwards - `use_hold_reg`, `card_num` and `start_command`
/// (`sd_host_sdmmc.c:859-881`) - because those three are not optional and splitting them across
/// two functions is how one of them gets forgotten.
pub fn commandWord(c: Command) u32 {
    var w: u32 = 0;
    w |= bits(cmd_index, c.index);
    if (c.response != .none) w |= bits(response_expect, 1);
    if (c.response == .long) w |= bits(response_length, 1);
    if (c.check_crc) w |= bits(check_response_crc, 1);
    if (c.data) |dir| {
        w |= bits(data_expected, 1);
        if (dir == .write) w |= bits(read_write, 1);
    }
    if (c.auto_stop) w |= bits(send_auto_stop, 1);
    if (c.wait_prvdata) w |= bits(wait_prvdata_complete, 1);
    if (c.stop_abort) w |= bits(stop_abort_cmd, 1);
    if (c.send_init) w |= bits(send_initialization, 1);
    if (c.update_clock) w |= bits(update_clock_registers_only, 1);
    w |= bits(card_number, c.slot);
    // Block transfers only; `transfer_mode` selects stream mode, which no SDIO command uses.
    w |= bits(transfer_mode, 0);
    w |= bits(use_hold_reg, 1);
    w |= bits(start_cmd, 1);
    return w;
}

// ------------------------------------------------------------------------------ SDIO protocol
//
// Command indices and argument layouts, from `sd_protocol_defs.h`. Written out as constants rather
// than reached through `regs` because they are the SD specification, not this chip: the register
// headers know nothing about them.

/// `sd_protocol_defs.h:35`, `:40`, `:61`, `:78-80`.
const cmd_go_idle_state: u6 = 0;
const cmd_send_relative_addr: u6 = 3;
const cmd_io_send_op_cond: u6 = 5;
const cmd_select_card: u6 = 7;
const cmd_io_rw_direct: u6 = 52;
const cmd_io_rw_extended: u6 = 53;

/// CMD52's argument: `sd_protocol_defs.h:484-492`.
pub fn cmd52Arg(write: bool, func: u3, addr: u17, raw_flag: bool, data: u8) u32 {
    var a: u32 = 0;
    if (write) a |= @as(u32, 1) << 31;
    a |= @as(u32, func) << 28;
    if (raw_flag) a |= @as(u32, 1) << 27;
    a |= @as(u32, addr) << 9;
    a |= data;
    return a;
}

/// CMD53's argument: `sd_protocol_defs.h:496-506`.
///
/// `count` is blocks in block mode and bytes in byte mode, and it is 9 bits: 0 means 512 in byte
/// mode ("See 5.3.1 SDIO simplified spec", `sdmmc_io.c:351-355`) and infinite in block mode, which
/// this driver never asks for.
pub fn cmd53Arg(write: bool, func: u3, addr: u17, block_mode: bool, incrementing: bool, count: u9) u32 {
    var a: u32 = 0;
    if (write) a |= @as(u32, 1) << 31;
    a |= @as(u32, func) << 28;
    if (block_mode) a |= @as(u32, 1) << 27;
    if (incrementing) a |= @as(u32, 1) << 26;
    a |= @as(u32, addr) << 9;
    a |= count;
    return a;
}

/// The block size this driver programmes into BLKSIZ and into the card's CCCR/FBR.
/// `sdmmc_common.h:195` SDMMC_IO_BLOCK_SIZE, and ESP-Hosted writes the same 512 into FN0 and FN1
/// (`port_esp_hosted_host_sdio.c:211-217`).
pub const io_block_size: u32 = 512;

/// CCCR register offsets, `sd_protocol_defs.h:509-530`.
pub const cccr = struct {
    pub const revision: u17 = 0x00;
    pub const fn_enable: u17 = 0x02;
    pub const fn_ready: u17 = 0x03;
    pub const int_enable: u17 = 0x04;
    pub const int_pending: u17 = 0x05;
    pub const ctl: u17 = 0x06;
    pub const bus_width: u17 = 0x07;
    pub const card_cap: u17 = 0x08;
    pub const cis_ptr: u17 = 0x09;
    pub const blksize_l: u17 = 0x10;
    pub const blksize_h: u17 = 0x11;

    pub const ctl_reset: u8 = 1 << 3;
    pub const bus_width_1: u8 = 0;
    pub const bus_width_4: u8 = 2;
    /// Low-speed card; and "4-bit low speed", which says a low-speed card supports 4 bits anyway.
    pub const card_cap_lsc: u8 = 1 << 6;
    pub const card_cap_4bls: u8 = 1 << 7;
};

/// `sd_protocol_defs.h:533` SD_IO_FBR_START - function n's register block starts here.
const fbr_start: u17 = 0x100;

/// R4's fields, `sd_protocol_defs.h:478-481`.
const r4_mem_ready: u32 = 1 << 31;
const r4_mem_present: u32 = 1 << 27;

/// The voltage window the host offers in CMD5's second pass: bits 23:15, i.e. 2.8-3.6 V.
/// `sd_protocol_defs.h:109` SD_OCR_VOL_MASK, which is the whole of what `get_host_ocr` returns -
/// "For now tell that the host has 2.8-3.6V voltage range" (`sdmmc_common.h:174-180`).
const host_ocr: u32 = 0x00ff_8000;

// ------------------------------------------------------------------------------- command issue

/// Write one command word and wait for the CIU to take it. No card traffic is implied: a clock
/// update command goes through here too.
///
/// Both waits are the ones `sd_host_slot_start_command` performs (`sd_host_sdmmc.c:862-892`),
/// bounded the same way. The first is not redundant with the second: writing any command register
/// while `start_command` is still set is a hardware locked write error, and HLE is reported
/// asynchronously in RINTSTS where it is easy to attribute to the wrong command.
fn startCommand(word: u32, arg: u32) Error!void {
    var d = Deadline.init(start_cmd_timeout_us);
    while (cmd.get(start_cmd) != 0) {
        if (d.expired()) return error.Busy;
    }
    cmdarg.writeRaw(arg);
    cmd.writeRaw(word);
    d = Deadline.init(start_cmd_timeout_us);
    while (cmd.get(start_cmd) != 0) {
        if (d.expired()) return error.Timeout;
    }
}

/// Push CLKDIV, CLKSRC and CLKENA into the card clock domain.
fn clockUpdate() Error!void {
    try startCommand(commandWord(.{
        .index = 0,
        .update_clock = true,
        .wait_prvdata = true,
        .slot = state.slot,
    }), 0);
}

/// Turn a RINTSTS snapshot into the failure it describes.
///
/// Order matters only in that the first match wins, and it is chosen so the most specific cause is
/// reported: a CRC error and a timeout together is a CRC error, because the timeout is downstream
/// of it.
fn decodeErrors(sts: u32) Error!void {
    if (sts & (Event.rcrc | Event.dcrc) != 0) return error.CrcError;
    if (sts & (Event.rto | Event.drto | Event.hto) != 0) return error.Timeout;
    if (sts & (Event.re | Event.hle | Event.ebe | Event.sbe | Event.frun) != 0) return error.ResponseError;
}

/// Wait for one or more RINTSTS bits, failing on any error bit or on the deadline.
///
/// RINTSTS is write-1-to-clear, so this reads with `raw()` and clears with `writeRaw(mask)` -
/// never `modify`, which would clear every bit it read back and lose the events this function is
/// not waiting for.
fn waitEvents(want: u32, errors: u32, us: u32) Error!u32 {
    const d = Deadline.init(us);
    while (true) {
        const sts = rintsts.raw();
        if (sts & errors != 0) {
            rintsts.writeRaw(sts & (want | errors));
            try decodeErrors(sts & errors);
            // Every bit any caller passes in `errors` is covered above; a new one arriving here
            // is a bug in this file, and reporting it beats an `unreachable` on a board with no
            // debugger.
            return error.ResponseError;
        }
        if (sts & want == want) {
            rintsts.writeRaw(want);
            return sts;
        }
        if (d.expired()) return error.Timeout;
    }
}

/// A command with no data phase: issue it, wait for command-done, return R1/R5's first word.
fn sendCommand(c: Command, arg: u32) Error!u32 {
    // Everything this command is about to overwrite. This slot's SDIO card interrupt is
    // deliberately left alone - the C6 raises it asynchronously and clearing it here would drop a
    // wakeup the layer above is waiting for - and `clearNonSlaveInterrupts` is exactly that set.
    //
    // It used to be `Event.default & ~Event.cd`, which is a *subset* of the event bits and left
    // four of them latched for ever: txdr(4), rxdr(5), frun(11) and acd(14). Two consequences, one
    // cosmetic and one not. Cosmetic: every RINTSTS a diagnostic prints carries a stale 0x10 from
    // the first transfer onwards, which is noise in exactly the register that has to be read
    // carefully. Not cosmetic: **frun is a member of `Event.data_errors`**, so one FIFO
    // under/overrun - ever - would latch a bit that nothing clears and fail every subsequent
    // `waitEvents(Event.dto, Event.data_errors, ...)` for the rest of the run. The data path works
    // today only because frun has never fired.
    clearNonSlaveInterrupts();
    var cc = c;
    cc.slot = state.slot;
    try startCommand(commandWord(cc), arg);
    _ = try waitEvents(Event.cmd_done, Event.command_errors, command_done_timeout_us);
    return resp0.raw();
}

/// R5's status byte, the one CMD52 and CMD53 return. `sd_protocol_defs.h:493` takes the data byte;
/// the flags above it say whether the card accepted the command at all.
const r5_com_crc_error: u32 = 1 << 15;
const r5_illegal_command: u32 = 1 << 14;
const r5_error: u32 = 1 << 11;
const r5_function_number: u32 = 1 << 9;
const r5_out_of_range: u32 = 1 << 8;
const r5_bad: u32 = r5_com_crc_error | r5_illegal_command | r5_error | r5_function_number | r5_out_of_range;

fn checkR5(r: u32) Error!u8 {
    if (r & r5_com_crc_error != 0) return error.CrcError;
    if (r & r5_bad != 0) return error.ResponseError;
    return @truncate(r);
}

// ------------------------------------------------------------------------------- bring-up

/// Controller, FIFO and DMA reset, then wait for all three to self-clear.
///
/// All three bits are self-clearing, and `sdmmc_ll.h:486`, `:510` and `:534` each say so with a
/// different delay ("two AHB clock cycles", "after reset done"). ESP-IDF sets all three and polls
/// all three together (`sd_host_sdmmc.c:917-950`), which is what makes one bounded wait correct
/// for the set.
pub fn resetController() Error!void {
    ctrl.modify(.{ controller_reset.is(1), fifo_reset.is(1), dma_reset.is(1) });
    const d = Deadline.init(reset_timeout_us);
    while (true) {
        const v = ctrl.raw();
        if (v & (controller_reset.mask() | fifo_reset.mask() | dma_reset.mask()) == 0) return;
        if (d.expired()) return error.Timeout;
    }
}

/// The interrupt configuration `sd_host_sdmmc.c:120-124` establishes - clear everything, mask
/// everything, then unmask the completion and error events and turn the global enable on - with
/// one deliberate deviation: card detect stays masked *and* gets cleared. See `Event.armed` for
/// why that bit is load-bearing on a board with no card-detect pin.
///
/// `int_enable` gates the controller's single line into the CLIC. It is on even though this driver
/// polls, because RINTSTS is set regardless and the layer above may register a handler for the
/// SDIO card interrupt; leaving it off would mean `setSlaveInterruptEnabled(true)` silently did
/// nothing.
pub fn configureInterrupts() void {
    rintsts.writeRaw(0xffff_ffff);
    intmask.writeRaw(0);
    ctrl.modify(.{int_enable.is(0)});
    intmask.writeRaw(Event.armed);
    // Belt and braces: `armed` keeps the controller from reporting a latched cd, and this makes
    // sure there is no latched cd to report if anything ever unmasks it again.
    rintsts.writeRaw(Event.cd);
    ctrl.modify(.{int_enable.is(1)});
}

/// `sdmmc_ll_init_dma`, `sdmmc_ll.h:796-804`: enable the DMA path, clear the bus-mode register,
/// pulse the IDMAC's own software reset, and unmask its three completion interrupts.
pub fn initDma() void {
    ctrl.modify(.{dma_enable.is(1)});
    bmod.writeRaw(0);
    bmod.modify(.{bmod_swr.is(1)});
    idinten.modify(.{ idinten_ni.is(1), idinten_ri.is(1), idinten_ti.is(1) });
}

/// Leave the controller's interrupt output silent, and both status registers clean.
///
/// `configureInterrupts` and `initDma` above are ESP-IDF's sequences, and ESP-IDF is
/// interrupt-driven: its transfers wait on a queue its ISR fills, so it needs command-done, the
/// error bits and the IDMAC's completions in the masks. **This driver polls**, so every one of
/// those is noise on a line whose only handler understands one cause. Worse than noise: two of
/// them hold the line asserted forever.
///
///  * **INTMASK** gates RINTSTS into MINTSTS. Zero here costs nothing - `waitEvents` reads
///    RINTSTS, and "Bits are logged regardless of interrupt mask status"
///    (`sdmmc_struct.h:589-591`).
///  * **IDINTEN** gates the IDMAC's own events, and it does *not* go through INTMASK. `initDma`
///    enables NI/RI/TI because `sdmmc_ll_init_dma` does, and IDF can afford that because its ISR
///    clears IDSTS on every interrupt (`sd_host_sdmmc.c:801-802`). `dataTransfer` clears IDSTS
///    *before* a transfer and nothing clears it after, so RI and its sticky summary NIS stay set
///    from the first CMD53 onwards - a permanently asserted interrupt line that no INTMASK write
///    can lower.
///
/// `CTRL.int_enable` stays on: with both masks at zero the line cannot assert anyway, and leaving
/// the global enable alone keeps `armSlaveInterrupt` down to the stores that matter.
pub fn muteInterrupts() void {
    intmask.writeRaw(0);
    idinten.writeRaw(0);
    rintsts.writeRaw(0xffff_ffff);
    idsts.writeRaw(idsts_event_mask);
}

/// FIFO watermarks and DMA burst size.
///
/// ESP-IDF never writes this register on any target - there is no `sdmmc_ll` function for it and
/// no assignment anywhere in `components/` - so the value in the measured working dump,
/// `fifoth=0x01FF0000`, is the hardware's reset state: rx watermark 511, tx watermark 0, burst
/// size code 0 (one transfer). This function writes that value explicitly rather than inheriting
/// it, because a controller reset is not the only thing that can have touched the register and
/// "the same as reset" is a claim worth making in code.
///
/// It is also a performance knob left deliberately untouched: DesignWare recommends half the FIFO
/// depth for both watermarks and a burst size matching the AXI port, and tx watermark 0 means a
/// DMA request only when the FIFO is completely empty. Turning that knob without a board to
/// measure on would be guessing, and the guess would be against a configuration known to work at
/// 40 MHz.
pub fn setFifoThreshold(rx: u32, tx: u32, msize: u32) void {
    fifoth.write(.{ rx_wmark.is(rx), tx_wmark.is(tx), dma_msize.is(msize) });
}

/// The reset-value watermarks, which are the ones the working dump shows.
pub const default_rx_watermark: u32 = 511;
pub const default_tx_watermark: u32 = 0;
pub const default_dma_msize: u32 = 0;

/// Bus width, host side. The card side is a CCCR write and is done in `cardInit`; the two must
/// change in that order, or the next command goes out on a bus the card is not listening to.
pub fn setBusWidth(w: Width) void {
    const m = slotBit();
    const c8 = ctype.get(card_width8) & ~m;
    const c4 = switch (w) {
        .one => ctype.get(card_width4) & ~m,
        .four => ctype.get(card_width4) | m,
    };
    ctype.modify(.{ card_width4.is(c4), card_width8.is(c8) });
}

pub fn setBlockSize(bytes: u32) void {
    blksiz.modify(.{block_size.is(bytes)});
}

/// The two-stage divider, resolved. Stage one is `host_div` in HP_SYS_CLKRST, stage two is the
/// controller's own CLKDIV, and the card clock is `160 MHz / host_div / (2 * card_div)` with
/// `card_div == 0` meaning bypass.
///
/// The table is `sd_host_slot_get_clk_dividers` (`sd_host_sdmmc.c:998-1062`), restricted to the
/// PLL160M source: this board's C6 is a 3.3 V SDIO device, so the 200 MHz SDIO PLL and the UHS-I
/// speeds it exists for are out of reach and out of scope.
pub const Dividers = struct { host: u32, card: u32 };

pub fn dividersFor(khz: u32) Dividers {
    const src_hz: u32 = 160_000_000;
    if (khz >= 40_000) return .{ .host = 4, .card = 0 }; // 160/4 = 40 MHz
    if (khz == 20_000) return .{ .host = 8, .card = 0 }; // 160/8 = 20 MHz
    if (khz == 400) return .{ .host = 10, .card = 20 }; // 160/10/(20*2) = 400 kHz
    var host = src_hz / (khz * 1000);
    var card: u32 = 0;
    if (host > 15) {
        host = 2;
        card = (src_hz / 2) / (2 * khz * 1000);
        if (((src_hz / 2) % (2 * khz * 1000)) > 0) card += 1;
    } else if (src_hz % (khz * 1000) > 0) {
        host += 1;
    }
    return .{ .host = host, .card = card };
}

/// Stage one: the clock generator in HP_SYS_CLKRST. `sdmmc_ll_set_clock_div`,
/// `sdmmc_ll.h:244-258`.
///
/// The `edge_cfg_update` bit is write-to-trigger and must be pulsed - set then cleared - after the
/// three edge fields, or the new division is programmed and never latched.
pub fn setHostClockDiv(div: u32) void {
    if (div > 1) {
        peri_clk_ctrl02.modify(.{
            sdio_ls_clk_edge_h.is(div / 2 - 1),
            sdio_ls_clk_edge_n.is(div - 1),
            sdio_ls_clk_edge_l.is(div - 1),
        });
        peri_clk_ctrl02.modify(.{sdio_ls_clk_edge_cfg_update.is(1)});
        peri_clk_ctrl02.modify(.{sdio_ls_clk_edge_cfg_update.is(0)});
    } else {
        peri_clk_ctrl01.modify(.{sdio_hs_mode.is(1)});
        peri_clk_ctrl02.modify(.{
            sdio_ls_clk_edge_h.is(0),
            sdio_ls_clk_edge_n.is(0),
            sdio_ls_clk_edge_l.is(0),
        });
    }
}

/// PLL160M, the only source this driver uses. `sdmmc_ll_select_clk_source`, `sdmmc_ll.h:212-229`:
/// source value 0 is PLL160M and 1 is the 200 MHz SDIO PLL.
pub fn selectPll160m() void {
    peri_clk_ctrl01.modify(.{ sdio_ls_clk_src_sel.is(0), sdio_ls_clk_en.is(1) });
}

/// The driving, sampling and self clocks the pad logic runs on. `sdmmc_ll_init_phase_delay`,
/// `sdmmc_ll.h:303-315`. Without this the three gates stay off and the bus does not move, which is
/// the kind of failure that looks like a wiring fault.
pub fn initPhaseDelay() void {
    peri_clk_ctrl02.modify(.{
        sdio_ls_drv_clk_en.is(1),
        sdio_ls_sam_clk_en.is(1),
        sdio_ls_slf_clk_en.is(1),
        sdio_ls_drv_clk_edge_sel.is(1),
        sdio_ls_sam_clk_edge_sel.is(0),
        sdio_ls_slf_clk_edge_sel.is(0),
    });
    peri_clk_ctrl02.modify(.{sdio_ls_clk_edge_cfg_update.is(1)});
    peri_clk_ctrl02.modify(.{sdio_ls_clk_edge_cfg_update.is(0)});
}

/// Stage one, whole: divider, source, phase clocks, and the settle the hardware needs afterwards.
/// `sd_host_set_clk_div`, `sd_host_sdmmc.c:974-990`, including its closing
/// `esp_rom_delay_us(10)` - "Wait for the clock to propagate".
///
/// This has to happen before the controller reset, not after. `controller_reset` is documented to
/// self-clear "after two AHB and two sdhost_cclk_in clock cycles" (`sdmmc_reg.h:18-20`), so with
/// no card clock reaching the block the bit never clears and the reset wait runs to its full
/// timeout. ESP-IDF's order says the same thing without saying it: `sd_host_set_clk_div` at
/// `sd_host_sdmmc.c:109`, `sd_host_reset` at `:112`.
pub fn setHostClock(div: u32) void {
    setHostClockDiv(div);
    selectPll160m();
    initPhaseDelay();
    spinMicros(10);
}

/// Stage two: the controller's per-slot divider and the divider-to-slot mux.
/// `sdmmc_ll_set_card_clock_div`, `sdmmc_ll.h:431-442`. Slot 1 uses divider 1, slot 0 uses divider
/// 0 - so the mux value equals the slot number, which is why one line covers both.
pub fn setCardClockDiv(div: u32) void {
    if (state.slot == 0) {
        clksrc.modify(.{clksrc_card0.is(0)});
        clkdiv.modify(.{clk_divider0.is(div)});
    } else {
        clksrc.modify(.{clksrc_card1.is(1)});
        clkdiv.modify(.{clk_divider1.is(div)});
    }
}

/// The card clock's on/off switch, one bit per slot. Takes effect only after a clock update
/// command. `sdmmc_ll_enable_card_clock`, `sdmmc_ll.h:415-422`.
pub fn setCardClockEnabled(on: bool) void {
    const cur = clkena.get(cclk_enable);
    clkena.modify(.{cclk_enable.is(if (on) cur | slotBit() else cur & ~slotBit())});
}

/// Stop the card clock while the card is idle. `sdmmc_ll_enable_card_clock_low_power`,
/// `sdmmc_ll.h:474-481`. **Off** for SDIO: the card raises its interrupt on D1 and cannot do so
/// with the clock stopped, which is why ESP-IDF clears the same bit for any slot with
/// `cclk_always_on` (`sd_host_sdmmc.c:272-285`) and why the measured working dump reads
/// `clkena=0x00000002` rather than `0x00020002`.
pub fn setCardClockLowPower(on: bool) void {
    const cur = clkena.get(lp_enable);
    clkena.modify(.{lp_enable.is(if (on) cur | slotBit() else cur & ~slotBit())});
}

/// Bytes in the next data transfer. `sdmmc_ll_set_data_transfer_len`, `sdmmc_ll.h:651-654`.
pub fn setDataTransferLen(len: u32) void {
    bytcnt.modify(.{byte_count.is(len)});
}

/// Data-read and response timeouts, both in card output clocks.
/// `sdmmc_ll_set_data_timeout` / `sdmmc_ll_set_response_timeout`, `sdmmc_ll.h:564-582`.
pub fn setTimeouts(data_cycles: u32, response_cycles: u32) void {
    tmout.write(.{
        data_timeout.is(if (data_cycles > 0xff_ffff) 0xff_ffff else data_cycles),
        response_timeout.is(response_cycles),
    });
}

/// Turn the internal DMA path on or off: both CTRL bits and both BMOD bits, together.
/// `sdmmc_ll_enable_dma`, `sdmmc_ll.h:812-818`.
pub fn setDmaEnabled(on: bool) void {
    const v: u32 = @intFromBool(on);
    ctrl.modify(.{ dma_enable.is(v), use_internal_dma.is(v) });
    bmod.modify(.{ bmod_de.is(v), bmod_fb.is(v) });
}

/// Where the IDMAC fetches its first descriptor. `sdmmc_ll_set_desc_addr`, `sdmmc_ll.h:673-676`.
/// The address is the *cached* one; see the "Cache" section above for why that is right.
pub fn setDescriptorAddr(a: u32) void {
    dbaddr.writeRaw(a);
}

/// Change the card clock, safely: stop it, reprogramme both stages, start it again, with a clock
/// update command after each step. `sd_host_slot_set_card_clk`, `sd_host_sdmmc.c:487-537`.
///
/// Low-power mode is left **off**, which is the one place this deviates from a plain SD host and
/// matches the measured dump (`clkena=0x00000002`: clock enabled for slot 1, `lp_enable` clear).
/// `clkena.lp_enable` stops cclk while the card is idle; an SDIO card signals its interrupt on D1
/// and needs the clock running to do it, which is why ESP-IDF turns the same bit off for any slot
/// with `cclk_always_on` (`sd_host_sdmmc.c:272-285`).
pub fn setBusClock(khz: u32) Error!void {
    const d = dividersFor(khz);

    setCardClockEnabled(false);
    try clockUpdate();

    setCardClockDiv(d.card);
    setHostClock(d.host);
    try clockUpdate();

    setCardClockEnabled(true);
    setCardClockLowPower(false);
    try clockUpdate();

    // 100 ms of card clocks for data, and the maximum 255 card clocks for a response - "always set
    // response timeout to highest value, it's small enough anyway" (`sd_host_sdmmc.c:534-535`).
    setTimeouts(100 * khz, 255);
}

/// Route slot 1's six signals to the C6's pads.
///
/// Pull-ups: **the board provides them externally and this enables the internal ones anyway**, on
/// all six pads, because that is what the working configuration does. It is not obvious from
/// ESP-Hosted's side - it leaves `SDMMC_SLOT_FLAG_INTERNAL_PULLUP` clear
/// (`SDMMC_SLOT_CONFIG_DEFAULT`, `sdmmc_default_configs.h:98`: `.flags = 0`) - but every pad still
/// gets one, because `configure_pin_gpio_matrix` opens with `gpio_reset_pin`
/// (`sd_host_sdmmc.c:1096`) and that function enables the pull-up unconditionally: "for powersave
/// reasons, the GPIO should not be floating, select pullup" (`gpio.c:469-472`). The 40 MHz link
/// that produced the register dump therefore had both the module's external pull-ups and these.
/// Matching a measured configuration beats reasoning about which resistor is redundant.
///
/// D1 has a second job: it is the SDIO interrupt line, and the controller derives that interrupt
/// from the same routed data signal - `sd_host_slot_sdmmc_io_int_enable` (`sd_host_sdmmc.c:381-388`)
/// is *only* `configure_pin(d1, sdmmc_slot_gpio_sig[slot].d1, GPIO_MODE_INPUT_OUTPUT)`, the same
/// two matrix writes and the same `fun_ie` the loop below already does, and it touches no
/// controller register at all. Both halves are load-bearing and neither is visible in a working
/// data path: with `fun_ie` clear, or with the *input* side of the matrix left pointing elsewhere,
/// D1 still drives and every transfer still completes while the controller samples a constant and
/// never latches a card interrupt. A link that carries traffic and never reports an event is
/// exactly what that failure looks like, which is why D1 is routed both ways even in 1-bit mode
/// and why `interruptDiagnostics` prints both bits.
///
/// D3 is *not* routed to the controller yet. It is driven high as a plain GPIO output until the
/// bus is switched to 4 bits, which is how a host tells an SDIO card to use SD mode rather than
/// SPI mode; `sd_host_sdmmc.c:1282-1294` does the same and `cardInit` reconnects it at
/// `sd_host_sdmmc.c:575-583`'s point in the sequence.
pub fn configurePins(pins: Pins) void {
    // CLK is output-only.
    gpio.matrixOut(pins.clk, sig.cclk);
    gpio.setInputEnable(pins.clk, false);
    gpio.setPull(pins.clk, .up);

    const bidir = [_]struct { pin: u8, signal: u32 }{
        .{ .pin = pins.cmd, .signal = sig.ccmd },
        .{ .pin = pins.d0, .signal = sig.cdata0 },
        .{ .pin = pins.d1, .signal = sig.cdata1 },
        .{ .pin = pins.d2, .signal = sig.cdata2 },
    };
    for (bidir) |b| {
        gpio.matrixOut(b.pin, b.signal);
        gpio.matrixIn(b.pin, b.signal);
        gpio.setInputEnable(b.pin, true);
        gpio.setPull(b.pin, .up);
    }

    // D3 high, as a GPIO, until the bus width changes.
    gpio.configureOutput(pins.d3, .{ .readback = true });
    gpio.setPull(pins.d3, .up);
    gpio.setHigh(pins.d3);

    // Card detect and the card's own interrupt-request pin are not wired to anything on this
    // board, so both are tied off in the matrix exactly as ESP-IDF ties them when no pin is
    // configured: card-detect to a constant 0 ("card present", `sd_host_sdmmc.c:1315-1319`) and
    // card-int-n to a constant 1, i.e. inactive (`:1304-1306`). Leaving them unrouted is not the
    // same thing: GPIO_FUNCn_IN_SEL_CFG resets with `sig_in_sel` clear, which bypasses the matrix
    // and takes the signal from whatever direct pad function exists - and slot 1 has none.
    // Write protect is left alone; nothing in this driver reads WRTPRT.
    gpio.matrixIn(gpio.matrix_const_zero, sig.card_detect);
    gpio.matrixIn(gpio.matrix_const_one, sig.card_int);
}

/// Reconnect D3 to the controller, once the card is in 4-bit mode.
fn attachD3() void {
    gpio.matrixOut(state.pins.d3, sig.cdata3);
    gpio.matrixIn(state.pins.d3, sig.cdata3);
    gpio.setInputEnable(state.pins.d3, true);
    gpio.setPull(state.pins.d3, .up);
}

/// Everything from the clock gate to a controller that will accept a command, with the bus at the
/// 400 kHz probing frequency and 1 bit wide - which is where an SDIO card has to be met.
///
/// `cardInit` is what raises it to `khz` and to `width`, after the card has been addressed.
pub fn init(opts: struct {
    slot: u1 = 1,
    width: Width = .four,
    khz: u32 = 40_000,
    pins: Pins = c6_pins,
}) Error!void {
    state = .{
        .slot = opts.slot,
        .width = opts.width,
        .target_khz = opts.khz,
        .pins = opts.pins,
    };

    // The C6 hangs off slot 1 and slot 0's pads are the P4's own flash on most boards; refusing
    // here is cheaper than debugging a bricked boot.
    if (opts.slot != 1) return error.NotSupported;

    // 1. Bus clock and reset. Unlike most of this chip, SDMMC's bus clock is gated *off* at
    //    power-on (HP_SYS_CLKRST SOC_CLK_CTRL1 REG_SDMMC_SYS_CLK_EN, default 0), so this is a
    //    prerequisite and not a formality - without it the register block reads stale nonsense.
    //    Its reset bit is not in HP_SYS_CLKRST at all but in LP_AON_CLKRST; see hal/clkrst.zig.
    clkrst.init(.sdmmc);

    // 2. The host clock generator, *before* the controller reset and not after. `sd_host_reset`
    //    polls three self-clearing bits, and `controller_reset` clears only "after two AHB and
    //    two sdhost_cclk_in clock cycles" (`sdmmc_reg.h:18-20`) - with no card clock reaching the
    //    block that poll runs to its full timeout. ESP-IDF's controller init has the same order:
    //    `sd_host_set_clk_div(ctlr, SDMMC_CLK_SRC_DEFAULT, 2)` at `sd_host_sdmmc.c:109`, then
    //    `sd_host_reset` at `:112`. Divider 2 is IDF's provisional value, replaced at step 6.
    setHostClock(2);

    // 3. Controller, FIFO and DMA out of reset.
    try resetController();

    // 4. Interrupts and DMA, before any command can produce one. The first two reproduce ESP-IDF
    //    for the differential; `muteInterrupts` then takes back everything this driver polls for
    //    instead of being interrupted by, leaving the line into the CLIC silent until a waiter
    //    arms it.
    configureInterrupts();
    initDma();
    muteInterrupts();

    // 5. Pads. After the clock gate so the controller's outputs are real, before the card clock so
    //    the first cycle the C6 sees is a clean one.
    configurePins(state.pins);

    // 6. Bus clock at probing speed, 1 bit wide. An SDIO card has to be met at 400 kHz in 1-bit
    //    mode; `cardInit` raises both once the card has been addressed.
    try setBusClock(400);
    setBusWidth(.one);

    // 7. Transfer geometry.
    setBlockSize(io_block_size);
    setFifoThreshold(default_rx_watermark, default_tx_watermark, default_dma_msize);
    setDescriptorAddr(busAddr(&dma.desc));

    // 8. The one cache operation in this driver's life. See the "Cache" section above.
    syncDmaRegionOnce();

    state.initialised = true;

    // The one claim in this sequence with no differential case behind it, said out loud once, at
    // the moment it is true. `configureInterrupts` and `initDma` are compared against ESP-IDF on
    // the die; `muteInterrupts` cannot be - it is a deliberate deviation from IDF's ISR-driven
    // design, and a reference implementation of our own decision would prove nothing. This line is
    // the substitute, and it is worth a print because both zeros are load-bearing: a non-zero
    // idinten here is an interrupt line that no INTMASK write can ever lower.
    note("MARK SDMMC_INIT intmask=0x%08x idinten=0x%08x expect 0x00000000 and 0x00000000\r\n", .{
        intmask.raw(), idinten.raw(),
    });
}

// ------------------------------------------------------------------------------ card bring-up

/// CMD0, CMD5, CMD3, CMD7, then the CCCR writes that make function 1 usable: the sequence that
/// takes the C6 from "powered" to "answers CMD52".
///
/// The command half follows `sdmmc_card_init` (`sdmmc_init.c:78-133`) restricted to the SDIO path:
/// `sdmmc_io_reset`, CMD0, `sdmmc_init_io` (CMD5 twice), `sdmmc_init_rca` (CMD3),
/// `sdmmc_init_select_card` (CMD7). The CCCR half is ESP-Hosted's `hosted_sdio_card_fn_init`
/// (`port_esp_hosted_host_sdio.c:143-220`) - enable function 1, wait for it to report ready,
/// unmask its interrupt, switch to 4 bits, set both block sizes to 512 - because that is what this
/// particular device needs and IDF's generic SDIO init does not do.
///
/// The CMD52 that resets the card is allowed to fail. A device that is already out of reset
/// answers it; one that is not may time out, and `sdmmc_io_reset` (`sdmmc_io.c:66-83`) accepts
/// exactly that.
pub fn cardInit() Error!void {
    if (!state.initialised) return error.NotSupported;

    // CCCR CTL bit 3: I/O reset. Best-effort, as above.
    cmd52Write(0, cccr.ctl, cccr.ctl_reset) catch {};

    // CMD0 with the 80-clock init sequence and no response.
    _ = try sendCommand(.{
        .index = cmd_go_idle_state,
        .response = .none,
        .send_init = true,
        .wait_prvdata = false,
    }, 0);
    // SDMMC_GO_IDLE_DELAY_MS (`sdmmc_common.h:34`), which `sdmmc_send_cmd_go_idle_state` waits
    // out before returning (`sdmmc_cmd.c:114-116`). CMD0 has no response, so there is nothing to
    // wait *for*: this is the card's own settling time and skipping it makes the next command a
    // coin toss.
    spinMicros(20_000);

    // CMD5 with a zero argument asks "are you an IO card, and what voltages do you take"; R4 has
    // no CRC, hence `check_crc = false` (`sd_protocol_types.h:141`).
    const probe = try sendCommand(.{
        .index = cmd_io_send_op_cond,
        .response = .short,
        .check_crc = false,
    }, 0);
    const functions = (probe >> 28) & 0x7;
    if (functions == 0) return error.NotSupported; // answered CMD5, but has no IO function

    // CMD5 again with the voltage window, until the card reports ready. 100 attempts is
    // `sdmmc_io.c:240`; the 10 ms between them is SDMMC_IO_SEND_OP_COND_DELAY_MS
    // (`sdmmc_common.h:35`), spent here as a bounded spin rather than a scheduler delay.
    const ocr = host_ocr & probe;
    var ready = false;
    var tries: u32 = 0;
    while (tries < 100) : (tries += 1) {
        const r = try sendCommand(.{
            .index = cmd_io_send_op_cond,
            .response = .short,
            .check_crc = false,
        }, ocr);
        if (r & r4_mem_ready != 0) {
            ready = true;
            break;
        }
        spinMicros(10_000);
    }
    if (!ready) return error.Timeout;

    // CMD3: the card picks its own relative address and returns it in R6[31:16].
    const r6 = try sendCommand(.{
        .index = cmd_send_relative_addr,
        .response = .short,
        .check_crc = true,
    }, 0);
    state.rca = @truncate(r6 >> 16);

    // CMD7 with that address moves the card from stand-by to transfer state. Every CMD52 and
    // CMD53 after this is addressed to it implicitly.
    _ = try sendCommand(.{
        .index = cmd_select_card,
        .response = .short,
        .check_crc = true,
    }, @as(u32, state.rca) << 16);

    // ---- CCCR: function 1 on.
    const ioe = try cmd52Read(0, cccr.fn_enable);
    try cmd52Write(0, cccr.fn_enable, ioe | 0x02);

    // Wait for IOR bit 1. ESP-Hosted polls with a 10 ms gap and gives up after SDIO_INIT_MAX_RETRY
    // (`port_esp_hosted_host_sdio.c:177-192`).
    var fn_ready = false;
    tries = 0;
    while (tries < 100) : (tries += 1) {
        if ((try cmd52Read(0, cccr.fn_ready)) & 0x02 != 0) {
            fn_ready = true;
            break;
        }
        spinMicros(10_000);
    }
    if (!fn_ready) return error.Timeout;

    // Master interrupt enable plus function 1's, so the C6 can raise D1.
    const ie = try cmd52Read(0, cccr.int_enable);
    try cmd52Write(0, cccr.int_enable, ie | 0x01 | 0x02);

    // ---- Bus width: card first, then host, then D3 joins the bus.
    if (state.width == .four) {
        const cap = try cmd52Read(0, cccr.card_cap);
        // "Not a low-speed card" or "a low-speed card that supports 4 bits" - `sdmmc_io.c:182-183`.
        if ((cap & cccr.card_cap_lsc) == 0 or (cap & cccr.card_cap_4bls) != 0) {
            try cmd52Write(0, cccr.bus_width, cccr.bus_width_4);
            setBusWidth(.four);
            attachD3();
        } else {
            state.width = .one;
        }
    }

    // ---- Block size 512 for function 0 and function 1, host side and card side.
    try setCardBlockSize(0, io_block_size);
    try setCardBlockSize(1, io_block_size);
    setBlockSize(io_block_size);

    // ---- Finally the target frequency, now that the card is addressed and the bus is wide.
    try setBusClock(state.target_khz);
}

/// The 16-bit block size lives in two consecutive byte registers, low half first
/// (`port_esp_hosted_host_sdio.c:123-141`). Function n's copy is at `0x100 * n + 0x10`.
fn setCardBlockSize(func: u3, bytes: u16) Error!void {
    const base: u17 = fbr_start * @as(u17, func);
    try cmd52Write(0, base + cccr.blksize_l, @truncate(bytes));
    try cmd52Write(0, base + cccr.blksize_h, @truncate(bytes >> 8));
}

/// A bounded busy-wait, for the two places the SDIO specification asks for a delay between
/// retries. Same conservative frequency assumption as `Deadline`, in the same safe direction: on
/// this 90 MHz die a 10 ms request takes about 44 ms.
fn spinMicros(us: u32) void {
    const d = Deadline.init(us);
    while (!d.expired()) {}
}

// ------------------------------------------------------------------------------------- CMD52

/// Read one byte from the card's register space.
///
/// This is the whole minimal milestone: after `init` and `cardInit`, `cmd52Read(0, 0x00)` reads
/// CCCR offset 0 and the byte that comes back is the C6 answering.
pub fn cmd52Read(func: u3, addr: u17) Error!u8 {
    const r = try sendCommand(.{
        .index = cmd_io_rw_direct,
        .response = .short,
        .check_crc = true,
    }, cmd52Arg(false, func, addr, false, 0));
    return checkR5(r);
}

/// Write one byte. The RAW flag is not set, matching `sdmmc_io_rw_direct` with SD_ARG_CMD52_WRITE
/// alone (`sdmmc_io.c:187`); `sdmmc_io_write_byte` adds SD_ARG_CMD52_EXCHANGE when it wants the
/// previous value back, which no caller here does.
pub fn cmd52Write(func: u3, addr: u17, value: u8) Error!void {
    const r = try sendCommand(.{
        .index = cmd_io_rw_direct,
        .response = .short,
        .check_crc = true,
    }, cmd52Arg(true, func, addr, false, value));
    _ = try checkR5(r);
}

// ------------------------------------------------------------------------------------- CMD53

/// How one CMD53 is split. Two rules decide it, and both come from ESP-IDF rather than from the
/// SDIO specification, because both are properties of this controller:
///
///  * **Block mode when the length is a whole number of 512-byte blocks**, byte mode otherwise.
///    In byte mode the count field is bytes and 0 encodes 512 ("See 5.3.1 SDIO simplified spec",
///    `sdmmc_io.c:351-355`), so one byte-mode command reaches 512 bytes and no further.
///  * **A byte-mode length of 4 or more must be a multiple of 4.** `sd_trans_sdmmc.c:526-532`
///    rejects anything else outright, and `sdmmc_io_read_bytes` works around it by splitting:
///    "host quirk: SDIO transfer with length not divisible by 4 bytes has to be split into two
///    transfers: one with aligned length, the other one for the remaining 1-3 bytes"
///    (`sdmmc_io.c:400-419`). So 6 bytes is two commands, 4 then 2, and 3 bytes is one.
///
/// A caller that wants the split to be explicit - ESP-Hosted's block path does, because its
/// addresses increment across the split - can hand over one whole-block chunk at a time and get
/// exactly one block-mode command per call. A caller that does not can hand over any length.
const Chunk = struct {
    block_mode: bool,
    /// Bytes in this command.
    len: u32,
    /// The CMD53 count field: blocks in block mode, bytes in byte mode with 0 meaning 512.
    count: u9,
};

fn nextChunk(remaining: u32) Chunk {
    if (remaining >= io_block_size and remaining % io_block_size == 0) {
        const max_blocks = bounce_len / io_block_size;
        var blocks = remaining / io_block_size;
        if (blocks > max_blocks) blocks = max_blocks;
        return .{
            .block_mode = true,
            .len = blocks * io_block_size,
            .count = @intCast(blocks),
        };
    }
    var len = remaining;
    if (len > io_block_size) len = io_block_size;
    // The 4-byte rule. Below 4 bytes the whole request goes in one command; at or above it, the
    // aligned part goes first and the 1-3 byte tail becomes the next chunk.
    if (len >= 4 and len % 4 != 0) len &= ~@as(u32, 3);
    return .{
        .block_mode = false,
        .len = len,
        .count = if (len == io_block_size) 0 else @intCast(len),
    };
}

pub fn cmd53Read(func: u3, addr: u17, buf: []u8, incrementing: bool) Error!void {
    var offset: u32 = 0;
    var a: u32 = addr;
    while (offset < buf.len) {
        const c = nextChunk(@intCast(buf.len - offset));
        const arg = cmd53Arg(false, func, @truncate(a), c.block_mode, incrementing, c.count);
        try dataTransfer(.read, arg, c.len, if (c.block_mode) io_block_size else c.len);
        const dst = buf[offset..][0..c.len];
        const src = bufNc();
        for (dst, 0..) |*b, i| b.* = src[i];
        offset += c.len;
        if (incrementing) a += c.len;
    }
}

pub fn cmd53Write(func: u3, addr: u17, data: []const u8, incrementing: bool) Error!void {
    var offset: u32 = 0;
    var a: u32 = addr;
    while (offset < data.len) {
        const c = nextChunk(@intCast(data.len - offset));
        const src = data[offset..][0..c.len];
        const dst = bufNc();
        for (src, 0..) |b, i| dst[i] = b;
        // The IDMAC moves whole words, so a length that is not a multiple of 4 is rounded up
        // (`sd_trans_sdmmc.c:127`). Zero the pad rather than send whatever the last transfer left.
        var pad = c.len;
        while (pad % 4 != 0) : (pad += 1) dst[pad] = 0;
        const arg = cmd53Arg(true, func, @truncate(a), c.block_mode, incrementing, c.count);
        try dataTransfer(.write, arg, c.len, if (c.block_mode) io_block_size else c.len);
        offset += c.len;
        if (incrementing) a += c.len;
    }
}

/// One CMD53 with its data phase, through the IDMAC and the bounce buffer.
///
/// Order is ESP-IDF's (`sd_trans_sdmmc.c:524-568`): descriptor and transfer registers first, then
/// the command word, then wait for command-done and data-transfer-over in that order. Preparing
/// the DMA after starting the command would be a race against a card that answers immediately.
fn dataTransfer(dir: Direction, arg: u32, len: u32, blk: u32) Error!void {
    std.debug.assert(len <= bounce_len);

    // The card must not still be holding DAT0 low from a previous write.
    const busy = Deadline.init(busy_timeout_us);
    while (status.get(data_busy) != 0) {
        if (busy.expired()) return error.Busy;
    }

    // As in `sendCommand`: the whole event set except this slot's card interrupt. `frun` is in
    // `Event.data_errors` and nothing else ever clears it.
    clearNonSlaveInterrupts();
    idsts.writeRaw(idsts_event_mask);

    const padded = (len + 3) & ~@as(u32, 3);
    const d = descNc();
    d.buffer1 = busAddr(&dma.buf);
    d.next = 0;
    d.sizes = padded; // buffer1_size is [12:0]; buffer2 is unused
    d.flags = Descriptor.owned_by_idmac | Descriptor.first_descriptor |
        Descriptor.last_descriptor | Descriptor.second_address_chained;

    setDataTransferLen(len);
    setBlockSize(blk);
    setDescriptorAddr(busAddr(&dma.desc));

    // `sdmmc_ll_enable_dma`, `sdmmc_ll.h:812-818`, then the poll demand that tells the IDMAC to
    // re-read a descriptor it may have parked on.
    setDmaEnabled(true);
    pldmnd.writeRaw(1);

    try startCommand(commandWord(.{
        .index = cmd_io_rw_extended,
        .response = .short,
        .check_crc = true,
        .data = dir,
        .slot = state.slot,
    }), arg);

    _ = try waitEvents(Event.cmd_done, Event.command_errors, command_done_timeout_us);
    _ = try checkR5(resp0.raw());
    _ = try waitEvents(Event.dto, Event.data_errors, data_done_timeout_us);
}

// -------------------------------------------------------------------- SDIO card interrupt (D1)

/// Has the card asserted its interrupt line?
///
/// Non-blocking, no side effect, straight out of RINTSTS bit 16+slot (`sdmmc_reg.h:621-631`). It
/// does **not** clear the bit; `clearSlaveInterrupt` does, deliberately, once a caller has decided
/// to act on it.
///
/// Two different trigger behaviours meet at this bit and it is worth keeping them apart, because
/// conflating them sends you tuning the wrong knob:
///
///   * **Card -> controller is an edge.** ESP-IDF: "SDIO interrupts are negedge sensitive ones:
///     the status bit is only set when first interrupt triggered" (`sd_host_sdmmc.c:396-402`).
///     That is why a waiter must check D1's level once before sleeping - an edge that arrived
///     while it was awake is not re-delivered.
///   * **Controller -> CLIC is a level.** RINTSTS is a sticky write-1-to-clear latch, so the
///     controller's output line stays asserted until software clears the bit that raised it. The
///     CLIC line therefore wants `.level`, and an edge trigger there would only hide a handler
///     that fails to deassert rather than fix it.
///
/// This is the polling half. The interrupt half is a CLIC line and belongs to whoever owns the
/// scheduler: route `interrupt_source` with `hal.intr`, and in the handler mask the bit
/// (`setSlaveInterruptEnabled(false)`) before waking anybody. ESP-IDF does exactly that
/// (`sd_host_sdmmc.c:826-830`) and explains why at `:396-402`: "SDIO interrupts are negedge
/// sensitive ones: the status bit is only set when first interrupt triggered", so a handler that
/// leaves the bit unmasked and unhandled re-enters forever, and a waiter that sleeps without first
/// checking D1's level loses an edge that arrived while it was awake.
pub fn slaveInterruptPending() bool {
    return rintsts.raw() & (Event.io_slot0 << state.slot) != 0;
}

/// The raw masked-interrupt status word. Diagnostics only: a hang waiting on the card interrupt is
/// otherwise indistinguishable from a card that never asserted, and this is the register that tells
/// them apart.
pub fn interruptStatusRaw() u32 {
    return rintsts.raw();
}

pub fn clearSlaveInterrupt() void {
    rintsts.writeRaw(Event.io_slot0 << state.slot);
}

/// INTMASK as written. The other half of "why is this line asserted": the controller's output is
/// RINTSTS AND INTMASK, and a diagnostic that prints only RINTSTS shows half the conjunction.
///
/// **Not evidence about an arm.** INTMASK is an ordinary read/write register, so this returns
/// whatever the last store left - and on the interrupt path the last store is usually the *disarm*.
/// A caller that wants to know whether unmasking took effect must read the register back inside the
/// same masked region as the store; that is `armSlaveInterrupt`, and it exists because this
/// function was read as if it answered that question and it never could.
pub fn interruptMaskRaw() u32 {
    return intmask.raw();
}

/// IDSTS - the IDMAC's own status word, which reaches the controller's interrupt output through
/// IDINTEN and *not* through INTMASK.
///
/// The second independent reason the line can be asserted, and therefore the first thing to read
/// when a handler entry cannot be explained by RINTSTS. `muteInterrupts` leaves IDINTEN at zero so
/// this cannot raise the line in this driver; a foreign handler entry with bits set here means
/// something put IDINTEN back.
pub fn dmaStatusRaw() u32 {
    return idsts.raw();
}

/// Clear every latched event *except* this slot's SDIO card interrupt.
///
/// For an interrupt handler that has to lower the controller's output line without racing the
/// card: the card interrupt is the one event the handler is being woken for, and clearing it here
/// would drop the wakeup. Everything else - a stale command-done, a latched card-detect, an error
/// from a transfer that has already been reported - is safe to drop on the floor, and leaving any
/// of it latched while unmasked keeps the CLIC line high.
pub fn clearNonSlaveInterrupts() void {
    rintsts.writeRaw(0x0003_ffff & ~(Event.io_slot0 << state.slot));
}

/// Unmask this slot's SDIO card interrupt, i.e. let it - and after `muteInterrupts`, *only* it -
/// reach the CLIC. RINTSTS records the event either way, so polling works without this.
///
/// This is the whole of the masking half of arming a waiter: `muteInterrupts` has already left
/// every other bit of INTMASK and all of IDINTEN at zero, so `true` here makes this slot's card
/// interrupt the single reason the controller's output can assert - which is what a
/// level-triggered CLIC line with a one-cause handler requires.
///
/// The *order* around it is the part that is easy to get wrong, and it belongs to whoever owns the
/// scheduler rather than here. `sd_host_slot_sdmmc_io_int_wait` (`sd_host_sdmmc.c:404-426`) is the
/// reference, and it is four steps:
///
///  1. `setSlaveInterruptEnabled(false)` - mask, so nothing arrives while the state is in flux.
///  2. `clearSlaveInterrupt()` - drop the latched edge, so a stale one is not delivered as news.
///  3. `slaveInterruptAsserted()` - **if true, act now and do not sleep.** The capture is a
///     negedge, so with D1 already low step 2 has just thrown away the only edge there will be.
///  4. `setSlaveInterruptEnabled(true)` - unmask, and not before. Nothing can be lost between 2
///     and 4: D1 is a level, and unmasking a bit RINTSTS has already latched asserts the line at
///     once.
///
/// A handler on that line must mask again as its **unconditional first act**, on every path
/// including the one where the cause turns out not to be its own. The line is a level and it does
/// not lower itself.
pub fn setSlaveInterruptEnabled(on: bool) void {
    // Masked, and that is not decoration. `sdioDispatch` performs *this same* read-modify-write on
    // *this same* two-bit field, from an interrupt handler, as its unconditional first act. A task
    // interrupted between the load and the store puts back the bit the handler had just cleared -
    // re-arming a level-triggered line with nobody left waiting on it, which is precisely how the
    // storm gets its second chance. Two CSR instructions, and `clkrst.Guard` composes: called from
    // inside a handler, where MIE is already clear, it leaves MIE clear.
    //
    // The register writes are unchanged, so the `sdio_interrupt` differential case still compares
    // the same resulting word against `sdmmc_ll_enable_sdio_interrupt`'s.
    const guard = intr.mask();
    defer guard.release();
    const m = slotBit();
    const cur = intmask.get(sdio_int_mask);
    intmask.modify(.{sdio_int_mask.is(if (on) cur | m else cur & ~m)});
}

/// What the controller reported the instant after this slot's card interrupt was unmasked.
pub const Armed = struct {
    /// The bit the store was trying to set, i.e. `slaveInterruptMask()`.
    want: u32,
    /// INTMASK, read back inside the same masked region as the store.
    intmask: u32,
    /// MINTSTS - `RINTSTS & INTMASK`, and the only word the controller's output follows. Zero here
    /// with `stuck()` true is the normal way to enter a sleep: the mask took and nothing is latched
    /// yet.
    mintsts: u32,
    /// RINTSTS, for the case where the edge landed between the unmask and the read-back.
    rintsts: u32,

    /// Did the unmask take effect?
    pub inline fn stuck(self: Armed) bool {
        return self.intmask & self.want != 0;
    }
};

/// Unmask this slot's card interrupt and read the result back, both inside one masked region.
///
/// This exists because the opposite conclusion was drawn from diagnostics that could not support
/// it. Every arming window on this board printed `intmask=0x00000000` and that was read as "the
/// unmask does not stick" - but `MARK PORT_SDIO_LAPSE` prints *after* the disarm, which had just
/// written that zero deliberately, and `interruptDiagnostics` runs on the application task, which
/// is never inside an arming window. Neither reading could ever have shown anything else, whatever
/// the hardware did.
///
/// So the claim gets an instrument instead of an argument. Nothing runs between the store and the
/// three loads: no task, because the runtime is cooperative, and no handler, because MIE is clear.
/// A `stuck()` of false here is a fact about this register on this die; `stuck()` true retires the
/// hypothesis.
pub fn armSlaveInterrupt() Armed {
    const guard = intr.mask();
    defer guard.release();
    const m = slotBit();
    intmask.modify(.{sdio_int_mask.is(intmask.get(sdio_int_mask) | m)});
    return .{
        .want = slaveInterruptMask(),
        .intmask = intmask.raw(),
        .mintsts = mintsts.raw(),
        .rintsts = rintsts.raw(),
    };
}

/// This slot's bit in RINTSTS/INTMASK/MINTSTS - the only interrupt cause a waiter here understands.
pub fn slaveInterruptMask() u32 {
    return Event.io_slot0 << state.slot;
}

/// Is the card asserting its interrupt *right now*?
///
/// Read from D1's pad rather than from RINTSTS, because the two answer different questions: the
/// register says "a negedge was latched and not yet cleared", the pad says "the card is holding the
/// line low". Only the second is safe to test before sleeping, and it is what ESP-IDF tests -
/// `gpio_get_level(slot_ctx->io_config.d1_io) == 0` at `sd_host_sdmmc.c:413-415`.
///
/// Requires D1's input buffer and matrix input to be configured, which `configurePins` does.
pub fn slaveInterruptAsserted() bool {
    return gpio.getLevel(state.pins.d1) == 0;
}

/// The masked status word - what the controller's interrupt output is actually looking at.
///
/// Non-zero here and a silent CLIC means the delivery path above the controller is broken (source
/// routing, line enable, priority, threshold, mstatus.MIE). Zero here while `interruptStatusRaw`
/// is non-zero means the event is latched but masked, which is the normal resting state of this
/// driver.
pub fn interruptStatusMasked() u32 {
    return mintsts.raw();
}

// ------------------------------------------------------------------------------- diagnostics

/// `ets_printf` from the mask ROM, the same declaration `src/net/port.zig:75` makes and for the
/// same reason: this file's only module imports are `regs`, `mmio` and its sibling HALs, and the
/// symbol comes from the generated linker script rather than from any of them.
extern fn ets_printf(fmt: [*:0]const u8, ...) c_int;

fn note(comptime fmt: [*:0]const u8, args: anytype) void {
    _ = @call(.auto, ets_printf, .{fmt} ++ args);
}

inline fn yesno(b: bool) u32 {
    return @intFromBool(b);
}

/// Print the whole card-interrupt delivery chain, in the order a signal traverses it, so that one
/// flash says which link is broken. Reads registers only: no loop, no wait, no side effect on any
/// of the state it reports.
///
/// The chain has four links and each line below covers one:
///
///  * `SDIO_DIAG_PAD` - the card's end. `asserted=1` means D1 is low, i.e. the C6 is requesting
///    service at this instant. `ie=0` or `in_src` not equal to D1's pad number means the
///    controller cannot see D1 at all, and no amount of unmasking will help.
///  * `SDIO_DIAG_TIEOFF` - the two matrix inputs with no pin on this board. `card_int_n` must read
///    63 (constant one, inactive) and `card_detect_n` 62 (constant zero, card present), both with
///    `from_matrix=1`. A `card_int_n` stuck at a constant *zero* is an interrupt that is asserted
///    before software ever runs, so the first negedge happens before anyone is watching and no
///    second one ever comes.
///  * `SDIO_DIAG_CTLR` - the controller's end. `latched` is RINTSTS's bit for this slot,
///    `unmasked` is INTMASK's, and `mintsts` is the conjunction the interrupt output follows.
///    `idsts`/`idinten` are the other, independent reason this output can be asserted.
///
///    **`unmasked=0` here is the resting state and is not a finding.** This function is called
///    from an application task; the card interrupt is unmasked only inside an arming window, on
///    the transport's own task, and is masked again by the handler or the disarm before that task
///    yields. So an application can never observe the mask up, whatever the hardware does, and
///    reading a zero here as "the unmask does not stick" is what cost this path a week. The
///    register read that can answer that question is `armSlaveInterrupt`.
///  * `SDIO_DIAG_CLIC` - delivery. An unrouted source, a clear `enabled`, a priority at or below
///    `thresh`, or `mie=0` each mean the line exists and cannot arrive.
pub fn interruptDiagnostics() void {
    const m = slaveInterruptMask();
    const rsts = rintsts.raw();
    const imask = intmask.raw();
    const d1 = state.pins.d1;
    const d1_in = gpio.matrixInSource(sig.cdata1);
    const ci = gpio.matrixInSource(sig.card_int);
    const cdet = gpio.matrixInSource(sig.card_detect);

    note("MARK SDIO_DIAG_PAD d1=gpio%u level=%u asserted=%u ie=%u in_src=%u from_matrix=%u inv=%u expect in_src=%u\r\n", .{
        @as(u32, d1),
        @as(u32, gpio.getLevel(d1)),
        yesno(slaveInterruptAsserted()),
        yesno(gpio.isInputEnabled(d1)),
        @as(u32, d1_in.pin),
        yesno(d1_in.from_matrix),
        yesno(d1_in.inverted),
        @as(u32, d1),
    });
    note("MARK SDIO_DIAG_TIEOFF card_int_n=%u/%u card_detect_n=%u/%u expect 63/1 and 62/1\r\n", .{
        @as(u32, ci.pin),   yesno(ci.from_matrix),
        @as(u32, cdet.pin), yesno(cdet.from_matrix),
    });
    note("MARK SDIO_DIAG_CTLR slot=%u bit=0x%05x latched=%u unmasked=%u rintsts=0x%08x intmask=0x%08x mintsts=0x%08x\r\n", .{
        @as(u32, state.slot),
        m,
        yesno(rsts & m != 0),
        yesno(imask & m != 0),
        rsts,
        imask,
        interruptStatusMasked(),
    });
    note("MARK SDIO_DIAG_CTRL ctrl=0x%08x int_enable=%u idsts=0x%08x idinten=0x%08x status=0x%08x clkena=0x%08x\r\n", .{
        ctrl.raw(),
        ctrl.get(int_enable),
        idsts.raw(),
        idinten.raw(),
        status.raw(),
        clkena.raw(),
    });

    const src: u32 = @intFromEnum(interrupt_source);
    if (intr.routedLine(interrupt_source)) |line| {
        note("MARK SDIO_DIAG_CLIC source=%u line=%u enabled=%u pending=%u trigger=%u prio=%u thresh=%u mie=%u\r\n", .{
            src,
            @as(u32, line),
            yesno(intr.isEnabled(line)),
            yesno(intr.isPending(line)),
            @as(u32, @intFromEnum(intr.getTrigger(line))),
            @as(u32, intr.getPriority(line)),
            @as(u32, intr.getThreshold()),
            yesno(intr.globalEnabled()),
        });
    } else {
        note("MARK SDIO_DIAG_CLIC source=%u UNROUTED - no CLIC line can deliver this interrupt\r\n", .{src});
    }
}

// --------------------------------------------------------------------------------- host tests
//
// Everything below runs on the host under `zig build test`. It covers the two things in this file
// that are pure functions of their arguments - the command word and the CMD52/CMD53 argument
// layouts - plus the divider table and the chunking rule. The register sequences are not testable
// here; that is what src/oracle/sdmmc_cases.zig is for.

const testing = std.testing;

test "CMD52 read is the word ESP-IDF builds" {
    // make_hw_cmd for {opcode 52, SCF_CMD_AC | SCF_RSP_R5}: response_expect (R5 is PRESENT),
    // check_response_crc (R5 has CRC), wait_complete (not CMD0/12/11), no data. Then
    // sd_host_slot_start_command adds use_hold_reg, card_num and start_command.
    const w = commandWord(.{ .index = 52, .response = .short, .check_crc = true, .slot = 1 });
    try testing.expectEqual(@as(u32, 0xA001_2174), w);
}

test "CMD52 on slot 0 differs from slot 1 only in card_num" {
    const s0 = commandWord(.{ .index = 52, .response = .short, .check_crc = true, .slot = 0 });
    const s1 = commandWord(.{ .index = 52, .response = .short, .check_crc = true, .slot = 1 });
    try testing.expectEqual(@as(u32, 0xA000_2174), s0);
    try testing.expectEqual(@as(u32, 1 << 16), s0 ^ s1);
}

test "CMD53 sets data_expected, and rw only when writing" {
    const rd = commandWord(.{ .index = 53, .response = .short, .check_crc = true, .data = .read, .slot = 1 });
    const wr = commandWord(.{ .index = 53, .response = .short, .check_crc = true, .data = .write, .slot = 1 });
    try testing.expectEqual(@as(u32, 0xA001_2375), rd);
    try testing.expectEqual(@as(u32, 0xA001_2775), wr);
    try testing.expectEqual(@as(u32, 1 << 10), rd ^ wr);
}

test "CMD0 sends the init sequence and expects nothing back" {
    // The only command make_hw_cmd gives send_init and denies wait_complete.
    const w = commandWord(.{ .index = 0, .send_init = true, .wait_prvdata = false, .slot = 1 });
    try testing.expectEqual(@as(u32, 0xA001_8000), w);
    try testing.expectEqual(@as(u32, 0), w & (1 << 6)); // no response expected
}

test "CMD5's response CRC is not checked" {
    // R4 is SCF_RSP_PRESENT alone (sd_protocol_types.h:141) - the OCR response carries no valid
    // CRC7, and checking it would fail every card.
    const w = commandWord(.{ .index = 5, .response = .short, .check_crc = false, .slot = 1 });
    try testing.expectEqual(@as(u32, 0xA001_2045), w);
    try testing.expectEqual(@as(u32, 0), w & (1 << 8));
}

test "CMD3 and CMD7 do check it" {
    try testing.expectEqual(
        @as(u32, 0xA001_2143),
        commandWord(.{ .index = 3, .response = .short, .check_crc = true, .slot = 1 }),
    );
    try testing.expectEqual(
        @as(u32, 0xA001_2147),
        commandWord(.{ .index = 7, .response = .short, .check_crc = true, .slot = 1 }),
    );
}

test "the clock update command sends nothing to the card" {
    const w = commandWord(.{ .index = 0, .update_clock = true, .slot = 1 });
    try testing.expectEqual(@as(u32, 0xA021_2000), w);
    try testing.expectEqual(@as(u32, 1 << 21), w & (1 << 21));
    try testing.expectEqual(@as(u32, 0), w & (1 << 6));
}

test "a long response sets response_length as well as response_expect" {
    const w = commandWord(.{ .index = 2, .response = .long, .check_crc = true, .slot = 1 });
    try testing.expectEqual(@as(u32, 1 << 7), w & (1 << 7));
    try testing.expectEqual(@as(u32, 1 << 6), w & (1 << 6));
}

test "every command word starts the command and uses the hold register" {
    for ([_]Command{
        .{ .index = 52, .response = .short, .check_crc = true },
        .{ .index = 53, .response = .short, .check_crc = true, .data = .read },
        .{ .index = 0, .send_init = true, .wait_prvdata = false },
    }) |c| {
        const w = commandWord(c);
        try testing.expect(w & (1 << 31) != 0);
        try testing.expect(w & (1 << 29) != 0);
    }
}

test "CMD52 argument layout" {
    // Read CCCR 0x00 on function 0: everything zero.
    try testing.expectEqual(@as(u32, 0), cmd52Arg(false, 0, 0x00, false, 0));
    // Write 0x02 to CCCR 0x02 (I/O enable) on function 0.
    try testing.expectEqual(@as(u32, 0x8000_0402), cmd52Arg(true, 0, 0x02, false, 0x02));
    // Function 1, address 0x1F800, data 0xAB, with the read-after-write flag.
    const a = cmd52Arg(true, 1, 0x1F800, true, 0xAB);
    try testing.expectEqual(@as(u32, 1), a >> 31);
    try testing.expectEqual(@as(u32, 1), (a >> 28) & 0x7);
    try testing.expectEqual(@as(u32, 1), (a >> 27) & 1);
    try testing.expectEqual(@as(u32, 0x1F800), (a >> 9) & 0x1FFFF);
    try testing.expectEqual(@as(u32, 0xAB), a & 0xFF);
}

test "CMD53 argument layout, both modes" {
    // Block mode, function 1, address 0, incrementing, one block.
    const blk = cmd53Arg(false, 1, 0, true, true, 1);
    try testing.expectEqual(@as(u32, 0x1C00_0001), blk);
    // Byte mode, function 1, fixed address, 12 bytes - the ESP-Hosted length read.
    const byt = cmd53Arg(false, 1, 0x058, false, false, 12);
    try testing.expectEqual(@as(u32, 0x1000_B00C), byt);
    // Writing sets bit 31 and nothing else.
    try testing.expectEqual(
        @as(u32, 1) << 31,
        cmd53Arg(true, 1, 0x058, false, false, 12) ^ byt,
    );
}

test "byte mode encodes 512 as a count of zero" {
    // SDIO simplified spec 5.3.1, as applied at sdmmc_io.c:351-355. The chunker never produces
    // this case - a 512-byte request is a whole block and goes block mode - so the encoder is
    // checked directly. ESP-Hosted can still reach it: a 512-byte read at a fixed address.
    try testing.expectEqual(@as(u32, 0), cmd53Arg(false, 1, 0, false, true, 0) & 0x1ff);
    const c = nextChunk(512);
    try testing.expect(c.block_mode);
    try testing.expectEqual(@as(u32, 512), c.len);
    try testing.expectEqual(@as(u9, 1), c.count);
}

test "chunking splits on block boundaries and clamps to the bounce buffer" {
    // Whole blocks, within the buffer: one block-mode command.
    try testing.expectEqual(@as(u32, 1024), nextChunk(1024).len);
    try testing.expect(nextChunk(1024).block_mode);
    // More blocks than fit: clamped to bounce_len, still block mode, still whole blocks.
    const big = nextChunk(8192);
    try testing.expect(big.block_mode);
    try testing.expectEqual(bounce_len, big.len);
    try testing.expectEqual(@as(u9, bounce_len / 512), big.count);
    // Not a block multiple: byte mode, count in bytes.
    const odd = nextChunk(12);
    try testing.expect(!odd.block_mode);
    try testing.expectEqual(@as(u32, 12), odd.len);
    try testing.expectEqual(@as(u9, 12), odd.count);
    // Longer than one byte-mode command can carry: clamped to 512.
    const long = nextChunk(1000);
    try testing.expect(!long.block_mode);
    try testing.expectEqual(@as(u32, 512), long.len);
}

test "the controller's 4-byte rule turns a 6-byte transfer into 4 then 2" {
    // sd_trans_sdmmc.c:526-532 rejects a length that is >= 4 and not a multiple of 4 outright.
    const first = nextChunk(6);
    try testing.expect(!first.block_mode);
    try testing.expectEqual(@as(u32, 4), first.len);
    const second = nextChunk(6 - first.len);
    try testing.expectEqual(@as(u32, 2), second.len);
    // Under four bytes the whole thing goes in one command; that is the case the rule exempts.
    try testing.expectEqual(@as(u32, 3), nextChunk(3).len);
    try testing.expectEqual(@as(u32, 1), nextChunk(1).len);
    // And every chunk a loop produces is either aligned or a final short tail.
    var remaining: u32 = 1023;
    var commands: u32 = 0;
    while (remaining > 0) {
        const c = nextChunk(remaining);
        try testing.expect(c.len > 0);
        try testing.expect(c.len < 4 or c.len % 4 == 0);
        remaining -= c.len;
        commands += 1;
        try testing.expect(commands < 8); // 512 + 508 + 3, not an unbounded walk
    }
}

test "divider table reproduces ESP-IDF's three named frequencies" {
    try testing.expectEqual(Dividers{ .host = 10, .card = 20 }, dividersFor(400));
    try testing.expectEqual(Dividers{ .host = 8, .card = 0 }, dividersFor(20_000));
    try testing.expectEqual(Dividers{ .host = 4, .card = 0 }, dividersFor(40_000));
}

test "divider table lands on or below the requested frequency" {
    for ([_]u32{ 400, 1_000, 5_000, 10_000, 20_000, 25_000, 40_000 }) |khz| {
        const d = dividersFor(khz);
        const div: u64 = @as(u64, d.host) * (if (d.card == 0) @as(u64, 1) else @as(u64, d.card) * 2);
        const actual_khz = 160_000 / div;
        try testing.expect(actual_khz <= khz);
    }
}

test "the DMA region is one aligned block of exactly the documented size" {
    try testing.expectEqual(@as(usize, 16), @sizeOf(Descriptor));
    try testing.expectEqual(@as(usize, 64 + bounce_len), @sizeOf(DmaRegion));
    try testing.expectEqual(@as(usize, 0), @offsetOf(DmaRegion, "desc"));
    try testing.expectEqual(@as(usize, 64), @offsetOf(DmaRegion, "buf"));
    // Both halves of what the one-shot cache maintenance call needs: a base on a cache line and a
    // length that is a whole number of them. The alignment is on the variable, not on the type -
    // `@alignOf(DmaRegion)` is 4 - so it has to be checked on the object.
    try testing.expectEqual(@as(usize, 0), @intFromPtr(&dma) % cache_line);
    try testing.expectEqual(@as(usize, 0), @sizeOf(DmaRegion) % cache_line);
}

test "the non-cacheable alias is a fixed offset and nothing more" {
    var cell: u32 = 0;
    const a = cachedAddr(&cell);
    try testing.expectEqual(a +% @as(usize, 0x4000_0000), uncachedAddr(&cell));
    // And it is the offset ESP-IDF uses, not one this file invented.
    try testing.expectEqual(@as(u32, 0x4000_0000), non_cacheable_offset);
}

test "descriptor flags are the bits sdmmc_struct.h names" {
    try testing.expectEqual(@as(u32, 1 << 2), Descriptor.last_descriptor);
    try testing.expectEqual(@as(u32, 1 << 3), Descriptor.first_descriptor);
    try testing.expectEqual(@as(u32, 1 << 4), Descriptor.second_address_chained);
    try testing.expectEqual(@as(u32, 1 << 31), Descriptor.owned_by_idmac);
    // The word a single-descriptor transfer writes.
    const flags = Descriptor.owned_by_idmac | Descriptor.first_descriptor |
        Descriptor.last_descriptor | Descriptor.second_address_chained;
    try testing.expectEqual(@as(u32, 0x8000_001C), flags);
}

test "the default interrupt mask is ESP-IDF's SDMMC_LL_EVENT_DEFAULT" {
    // sdmmc_ll.h:64-69, expanded: CD|RESP_ERR|CMD_DONE|DATA_OVER|RCRC|DCRC|RTO|DTO|HTO|HLE|SBE|EBE
    try testing.expectEqual(@as(u32, 0xB7CF), Event.default);
    // and it deliberately excludes the two per-FIFO-word requests and both SDIO card interrupts.
    try testing.expectEqual(@as(u32, 0), Event.default & (Event.txdr | Event.rxdr));
    try testing.expectEqual(@as(u32, 0), Event.default & (Event.io_slot0 | Event.io_slot1));
}

test "the armed mask drops card detect, and nothing else" {
    // The bit that produced an unstoppable CLIC line 21: cd latches during pin setup, nothing in
    // the command path clears it, and while it is unmasked the controller's output never
    // deasserts. `configureInterrupts` writes `armed`, not `default`.
    try testing.expectEqual(@as(u32, 0xB7CE), Event.armed);
    try testing.expectEqual(@as(u32, 0), Event.armed & Event.cd);
    try testing.expectEqual(Event.cd, Event.default ^ Event.armed);
    // Every event a transfer actually waits on survives the change.
    for ([_]u32{ Event.cmd_done, Event.dto, Event.re, Event.rcrc, Event.dcrc, Event.rto, Event.drto, Event.hto, Event.hle, Event.sbe, Event.ebe }) |e| {
        try testing.expect(Event.armed & e != 0);
    }
}