mmio.c

C source for Emulating a round-screen ESP32 board, 648 lines. Raw file

#include <stdlib.h>
// mmio.c - ESP32-S3 peripheral registers (0x6000_0000..0x6010_0000).
//
// The whole 1 MB peripheral window is backed by RAM so every "write a config
// word, read it back" register just works; specific registers that have real
// hardware behaviour (status/"done" bits, the MSPI command engine) are modelled
// on top. This lets the UNCHANGED ROM + ESP-IDF drivers run to completion.
//
// MSPI (SPIMEM1 @ 0x6000_2000) is the manual-command flash/PSRAM controller. The
// ROM/IDF program a command into the USER2/ADDR/DLEN/W0.. registers, then set a
// trigger bit in CMD (0x00) and poll CMD until it reads 0 (transaction done). We
// honour that contract: on a nonzero CMD write we decode the transaction, run it
// against the emulated flash chip or octal PSRAM, put any read data back in the
// W0.. buffer, and clear CMD to 0 so the poll completes.
#include <stdio.h>
#include <string.h>
#include "mem.h"
#include "sdcard.h"

uint32_t g_last_read, g_last_write;   // for the harness stuck-detector
int g_reboot_req;                     // firmware asked for a soft reset (RTC_CNTL SW_SYS_RST)
extern int g_mspi_dbg;
uint64_t g_ticks;                     // monotonic system time (advanced by main.c), drives SYSTIMER
static uint32_t st_int_raw;           // SYSTIMER_INT_RAW target0/1/2 (bits 0..2)
static uint64_t st_next[3];           // next alarm time per comparator
static uint64_t st_latch[2];          // per-core UNITx_OP-latched counter snapshot
static uint32_t xcore_pend;           // FROM_CPU_INTR0..3 (cross-core) pending, bits 0..3
static uint64_t rtc_latch;            // RTC_CNTL main-timer value latched by TIME_UPDATE
int             g_rtc_slp_armed;      // SLEEP_EN was set (RTC_CNTL STATE0 bit31): report an
                                      // immediate light-sleep wakeup so rtc_sleep_start returns.
                                      // xtensa.c also uses it to model a deep-sleep terminal
                                      // `j .` spin as a chip reset, and to disarm on app return.
static uint32_t lcd_int_raw;          // LCD_CAM LC_DMA_INT_RAW (trans-done etc.)
static uint64_t lcd_done_at;          // g_ticks at which the current i80 transfer's TRANS_DONE fires
int cur_core(void);                   // which core is stepping (xtensa.c)

#define MMIO_BASE 0x60000000u
#define MMIO_SIZE 0x00100000u          // 1 MB peripheral window
static uint8_t mmio[MMIO_SIZE];

static inline uint32_t RD(uint32_t a) {
    uint32_t o = a - MMIO_BASE;
    return mmio[o] | (mmio[o+1]<<8) | (mmio[o+2]<<16) | ((uint32_t)mmio[o+3]<<24);
}
static inline void WR(uint32_t a, uint32_t v) {
    uint32_t o = a - MMIO_BASE;
    mmio[o]=v; mmio[o+1]=v>>8; mmio[o+2]=v>>16; mmio[o+3]=v>>24;
}

// ---------------- USB-Serial-JTAG (0x6003_8000) ----------------
// The PaperS3 talks to the host over the ESP32-S3's built-in USB-Serial-JTAG CDC
// (register FIFO, NOT USB-OTG/TinyUSB). The IDF driver: reads bytes from EP1 while
// EP1_CONF.OUT_EP_DATA_AVAIL(bit2) is set (RX), writes bytes to EP1 then sets
// EP1_CONF.WR_DONE(bit0) to flush (TX). Interrupts: OUT_RECV_PKT(bit2)=RX packet,
// IN_EMPTY(bit3)=host took the TX data. Source 96, matrix MAP @ core-base+0x180.
// We model a host that can push ONE app image to the running menu (its push.c RMP1
// protocol) via env PAPER_USB_PUSH="file[:name]", and print the device's replies.
static uint8_t *usj_rx;                // host->device pending bytes (the RMP1 frame)
static int      usj_rx_head, usj_rx_len;
static int      usj_allow;              // stop-and-wait credit: bytes the host has released
static uint8_t  usj_tx[64]; static int usj_tx_len;   // device->host current EP packet
static int      usj_in_empty = 1;      // TX "host picked up" latch (INT_RAW bit3)
static int      usj_fed;               // the push frame has been queued into usj_rx
#define USJ_CHUNK 4096                  // push.py stop-and-wait chunk size
// Bytes currently readable = released-but-unread, and only while data remains.
#define USJ_EXPOSED (usj_rx_len > 0 && usj_rx_head < usj_allow)

static uint32_t crc32_zlib(const uint8_t *p, size_t n) {
    uint32_t crc = ~0u;
    for (size_t i = 0; i < n; i++) { crc ^= p[i];
        for (int k = 0; k < 8; k++) crc = (crc >> 1) ^ (0xEDB88320u & (uint32_t)-(int)(crc & 1)); }
    return ~crc;
}
// Build the push.c wire frame: "RMP1" | name_len u8 | name | size u32le | crc32 u32le | data.
static void usj_build_push(void) {
    const char *spec = getenv("PAPER_USB_PUSH");
    if (!spec || usj_rx) return;
    char path[512]; const char *name = 0;
    const char *colon = strrchr(spec, ':');
    if (colon && colon != spec && colon[1] && !strchr(colon, '/')) {   // "file:name"
        size_t pl = (size_t)(colon - spec); if (pl >= sizeof path) pl = sizeof path - 1;
        memcpy(path, spec, pl); path[pl] = 0; name = colon + 1;
    } else { snprintf(path, sizeof path, "%s", spec);
        const char *slash = strrchr(path, '/'); name = slash ? slash + 1 : path; }
    FILE *f = fopen(path, "rb"); if (!f) { fprintf(stderr, "[usj] cannot open %s\n", path); return; }
    fseek(f, 0, SEEK_END); long sz = ftell(f); fseek(f, 0, SEEK_SET);
    if (sz <= 0) { fclose(f); return; }
    uint8_t *data = malloc(sz); if (fread(data, 1, sz, f) != (size_t)sz) { fclose(f); free(data); return; }
    fclose(f);
    int nl = (int)strlen(name); if (nl > 255) nl = 255;
    long total = 4 + 1 + nl + 4 + 4 + sz;
    usj_rx = malloc(total); usj_rx_len = 0; usj_rx_head = 0;
    uint8_t *q = usj_rx;
    memcpy(q, "RMP1", 4); q += 4;
    *q++ = (uint8_t)nl; memcpy(q, name, nl); q += nl;
    *q++ = sz; *q++ = sz>>8; *q++ = sz>>16; *q++ = sz>>24;
    uint32_t crc = crc32_zlib(data, sz);
    *q++ = crc; *q++ = crc>>8; *q++ = crc>>16; *q++ = crc>>24;
    *q++ = getenv("PAPER_USB_RUN") ? 1 : 0;       // run flag: 1 = auto-launch after upload
    memcpy(q, data, sz); q += sz; free(data);
    usj_rx_len = (int)(q - usj_rx);
    // Stop-and-wait credit: the device reads the header + the first 4 KB chunk before it
    // sends the first 'K'; each 'K' thereafter releases another chunk (see the TX flush).
    usj_allow = (4 + 1 + nl + 4 + 4 + 1) + USJ_CHUNK;
    fprintf(stderr, "[usj] pushing %s as \"%s\": %ld bytes (frame %d)\n", path, name, sz, usj_rx_len);
}

// ---------------- SHA accelerator (0x6003_B000) ----------------
// The 2nd-stage bootloader verifies the app image's SHA-256 through the ROM ets_sha
// driver, which drives this hardware block: it loads a 512-bit message block into the
// text memory (base+0x80), writes START (first block, H<-IV) or CONTINUE (subsequent,
// H kept), polls BUSY, and reads the running hash from H memory (base+0x40). We compute
// one SHA-256 block synchronously so the real driver + real image verify unchanged.
static uint32_t ror32(uint32_t x, int n) { return (x >> n) | (x << (32 - n)); }
static void sha256_block(uint32_t H[8], const uint8_t p[64]) {
    static const uint32_t K[64] = {
        0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
        0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
        0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
        0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
        0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
        0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
        0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
        0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2 };
    uint32_t w[64];
    for (int i = 0; i < 16; i++)
        w[i] = ((uint32_t)p[4*i]<<24)|((uint32_t)p[4*i+1]<<16)|((uint32_t)p[4*i+2]<<8)|p[4*i+3];
    for (int i = 16; i < 64; i++) {
        uint32_t s0 = ror32(w[i-15],7)^ror32(w[i-15],18)^(w[i-15]>>3);
        uint32_t s1 = ror32(w[i-2],17)^ror32(w[i-2],19)^(w[i-2]>>10);
        w[i] = w[i-16] + s0 + w[i-7] + s1;
    }
    uint32_t a=H[0],b=H[1],c=H[2],d=H[3],e=H[4],f=H[5],g=H[6],h=H[7];
    for (int i = 0; i < 64; i++) {
        uint32_t S1 = ror32(e,6)^ror32(e,11)^ror32(e,25), ch = (e&f)^(~e&g);
        uint32_t t1 = h + S1 + ch + K[i] + w[i];
        uint32_t S0 = ror32(a,2)^ror32(a,13)^ror32(a,22), maj = (a&b)^(a&c)^(b&c);
        uint32_t t2 = S0 + maj;
        h=g; g=f; f=e; e=d+t1; d=c; c=b; b=a; a=t1+t2;
    }
    H[0]+=a; H[1]+=b; H[2]+=c; H[3]+=d; H[4]+=e; H[5]+=f; H[6]+=g; H[7]+=h;
}
// Run one block. `cont`=0 seeds H with the SHA-256 IV (START); `cont`=1 keeps the
// running state held in H memory (CONTINUE). H memory holds the state as big-endian
// words, which is also the final digest byte order the driver reads back.
static void sha_run(int cont) {
    static const uint32_t IV[8] = {
        0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19 };
    uint32_t H[8]; uint8_t blk[64];
    for (int i = 0; i < 8; i++)
        H[i] = cont ? ((uint32_t)mmio[0x3B040+4*i]<<24 | (uint32_t)mmio[0x3B040+4*i+1]<<16 |
                       (uint32_t)mmio[0x3B040+4*i+2]<<8 | mmio[0x3B040+4*i+3]) : IV[i];
    for (int i = 0; i < 64; i++) blk[i] = mmio[0x3B080+i];
    sha256_block(H, blk);
    for (int i = 0; i < 8; i++) {
        mmio[0x3B040+4*i]=H[i]>>24; mmio[0x3B040+4*i+1]=H[i]>>16;
        mmio[0x3B040+4*i+2]=H[i]>>8; mmio[0x3B040+4*i+3]=H[i];
    }
}

// ---------------- EXTMEM cache block (0x600c_0000..) ----------------
// Autoload/invalidate/sync "done" status regs software never writes -> read done.
static int cache_status(uint32_t a) {
    switch (a) {
    case 0x600c4028: case 0x600c4040: case 0x600c404c: case 0x600c4088:
    case 0x600c4094: case 0x600c40a0: case 0x600c40c0: return 1;
    default: return 0;
    }
}

// ---------------- Octal PSRAM (AP-Hex, 8 MB) ----------------
// The M5Stack PaperS3 has AP Memory octal PSRAM. esp_psram_impl_ap_hex.c detects
// it by reading mode registers (vendor 0x0d, kgd 6, density 0x3 = 64Mbit/8MB) and
// by a write/read-back test at address 0. The array is the shared backing in mem.c
// (so MMU-mapped reads see what the SPI command path wrote); mode registers here.
static uint8_t psram_mr[16] = {
    [0] = 0x20,   // MR0: lt=1 (fixed latency)
    [1] = 0x0d,   // MR1: vendor_id=0x0d (AP)
    [2] = 0xc3,   // MR2: density=0x3 (64Mbit), dev_id=0, kgd=6 (pass) -> 6<<5|3
    [4] = 0x00,   // MR4: write latency etc.
    [8] = 0x00,   // MR8: x8 mode, 16-byte burst
};

// ---------------- flash chip (32 MB, backed by mem_flash) ----------------
#define FLASH_JEDEC_ID 0x001940efu     // Winbond-style: mfg 0xEF, type 0x40, cap 0x19 (32MB)
static int flash_wren;

// Write the W0.. data buffer (offset 0x58) of an MSPI controller.
static void wbuf_put(uint32_t base, const uint8_t *p, uint32_t n) {
    if (n > 64) n = 64;
    for (uint32_t i = 0; i < n; i++) mmio[(base + 0x58 - MMIO_BASE) + i] = p[i];
}
static void wbuf_get(uint32_t base, uint8_t *p, uint32_t n) {
    if (n > 64) n = 64;
    for (uint32_t i = 0; i < n; i++) p[i] = mmio[(base + 0x58 - MMIO_BASE) + i];
}

// Run one manual MSPI transaction previously programmed into `base`'s registers.
static void mspi_exec(uint32_t base, uint32_t cmdreg) {
    uint32_t user2 = RD(base + 0x20);            // USER2: cmd value + cmd bitlen
    uint32_t cmd   = user2 & 0xffff;
    int      cbits = ((user2 >> 28) & 0xf) + 1;
    if (cbits <= 8) cmd &= 0xff;
    // The esp_flash HAL doesn't use the USER command for writes/erases — it triggers the
    // MSPI's DEDICATED command bits in SPI_MEM_CMD (WREN/WRDI/PP/SE/BE/CE/RDSR/RDID/READ).
    // The ROM/bootloader uses the USER path (SPI_MEM_USR, bit18). Decode the dedicated bits
    // here (addr/data registers are shared) — else WREN/erase silently no-op as a stale USER2
    // command, so the app's flash erase fails with ESP_ERR_NOT_FOUND ("WREN flag not set").
    if      (cmdreg & (1u << 30)) cmd = 0x06;    // FLASH_WREN
    else if (cmdreg & (1u << 29)) cmd = 0x04;    // FLASH_WRDI
    else if (cmdreg & (1u << 25)) cmd = 0x02;    // FLASH_PP  (page program)
    else if (cmdreg & (1u << 24)) cmd = 0x20;    // FLASH_SE  (4 KB sector erase)
    else if (cmdreg & (1u << 23)) cmd = 0xd8;    // FLASH_BE  (64 KB block erase)
    else if (cmdreg & (1u << 22)) cmd = 0x60;    // FLASH_CE  (chip erase)
    else if (cmdreg & (1u << 27)) cmd = 0x05;    // FLASH_RDSR
    else if (cmdreg & (1u << 28)) cmd = 0x9f;    // FLASH_RDID
    else if (cmdreg & (1u << 31)) cmd = 0x03;    // FLASH_READ
    // else: SPI_MEM_USR (bit18) — keep the USER2-decoded command above.
    uint32_t addr  = RD(base + 0x04);            // ADDR
    uint32_t misolen = (((RD(base + 0x28) & 0x7ff)) + 1) / 8;   // MISO bytes
    uint32_t mosilen = (((RD(base + 0x24) & 0x7ff)) + 1) / 8;   // MOSI bytes
    uint8_t  buf[64];
    extern int g_mspi_dbg; static int nc;
    if (g_mspi_dbg && nc < 40) { nc++; fprintf(stderr, "[mspi] cmd=%04x addr=%08x miso=%u mosi=%u user=%08x user2=%08x\n",
        cmd, addr, misolen, mosilen, RD(base+0x18), user2); }

    switch (cmd) {
    // --- octal PSRAM ---
    case 0x0000:  // SYNC_READ (linear)
        for (uint32_t i = 0; i < misolen && i < 64; i++) { uint8_t *p = mem_psram((addr+i) & (mem_psram_size()-1)); buf[i] = p ? *p : 0; }
        wbuf_put(base, buf, misolen);
        break;
    case 0x8080:  // SYNC_WRITE (linear)
        wbuf_get(base, buf, mosilen);
        for (uint32_t i = 0; i < mosilen && i < 64; i++) { uint8_t *p = mem_psram((addr+i) & (mem_psram_size()-1)); if (p) *p = buf[i]; }
        break;
    case 0x4040:  // REG_READ: addr = mode-register index
        for (uint32_t i = 0; i < misolen && i < 64; i++) buf[i] = psram_mr[(addr + i) & 15];
        wbuf_put(base, buf, misolen ? misolen : 1);
        if (g_mspi_dbg) fprintf(stderr, "[psram MR read] addr=%u -> %02x %02x\n", addr, buf[0], misolen>1?buf[1]:0);
        break;
    case 0xc0c0:  // REG_WRITE
        wbuf_get(base, buf, mosilen ? mosilen : 1);
        for (uint32_t i = 0; i < mosilen && i < 16; i++) psram_mr[(addr + i) & 15] = buf[i];
        break;

    // --- SPI NOR flash ---
    case 0x9f: {  // RDID (JEDEC)
        uint8_t id[3] = { FLASH_JEDEC_ID & 0xff, (FLASH_JEDEC_ID>>8)&0xff, (FLASH_JEDEC_ID>>16)&0xff };
        wbuf_put(base, id, 3); break;
    }
    case 0x05: case 0x35: case 0x15: {   // RDSR/RDSR2/RDSR3: not busy, not WP
        uint8_t s = flash_wren ? 0x02 : 0x00; wbuf_put(base, &s, 1); break;
    }
    case 0x06: flash_wren = 1; break;    // WREN
    case 0x04: flash_wren = 0; break;    // WRDI
    // READ / FAST_READ / dual & quad reads (DOUT 3b, DIO bb, QOUT 6b, QIO eb) + 4-byte
    // variants. The emulator ignores bus width, so all map to a linear read from `addr`.
    case 0x03: case 0x0b: case 0x13: case 0x0c: case 0x0d:
    case 0x3b: case 0xbb: case 0x6b: case 0xeb:
    case 0x3c: case 0xbc: case 0x6c: case 0xec: {
        uint8_t *f = mem_flash(addr);
        if (f) { uint32_t n = misolen < 64 ? misolen : 64; wbuf_put(base, f, n); }
        break;
    }
    case 0x02: case 0x12: {              // PAGE PROGRAM
        uint8_t *f = mem_flash(addr);
        if (f && flash_wren) { wbuf_get(base, buf, mosilen); for (uint32_t i=0;i<mosilen;i++) f[i] &= buf[i]; }
        flash_wren = 0; break;
    }
    case 0x20: case 0x21: {              // SECTOR ERASE (4 KB)
        uint8_t *f = mem_flash(addr & ~0xfffu); if (f && flash_wren) memset(f, 0xff, 0x1000);
        flash_wren = 0; break;
    }
    case 0xd8: {                         // BLOCK ERASE (64 KB)
        uint8_t *f = mem_flash(addr & ~0xffffu); if (f && flash_wren) memset(f, 0xff, 0x10000);
        flash_wren = 0; break;
    }
    default: break;                      // other commands: no data effect
    }
}

// ---------------- register read/write ----------------
// ---- GT911 capacitive touch over I2C1 ----
// Host-injected touch point (set by the GUI mouse handler in gui.m, in PANEL pixels).
int g_touch_down, g_touch_x, g_touch_y;
int g_spi2_irq;   // GP-SPI2 TRANS_DONE interrupt armed (one-shot; see mmio_cpu_int)
static uint8_t i2c_tx[64]; static int i2c_txn;         // bytes the driver clocked out (TX FIFO)
static uint8_t i2c_rx[64]; static int i2c_rxn, i2c_rxi; // bytes the GT911 returns (RX FIFO)

// GT911 register map read (auto-incrementing). 0x814E = status ([3:0] = point count,
// bit7 = buffer ready). The touch driver reads 8 bytes from 0x814F and takes
// x = @0x8150 | (@0x8151 & 0xf)<<8, y = @0x8152 | (@0x8153 & 0xf)<<8.
static uint8_t gt911_rd(uint16_t reg) {
    switch (reg) {
    case 0x8140: return 0x39;                           // product id "911\0" -> '9'
    case 0x8141: return 0x31; case 0x8142: return 0x31; case 0x8143: return 0x00;
    case 0x814E: return g_touch_down ? 0x81 : 0x00;     // ready + 1 point, or no fresh frame
    case 0x814F: return 0;                              // (buf[0], driver skips)
    case 0x8150: return g_touch_x & 0xff;              // x low
    case 0x8151: return (g_touch_x >> 8) & 0x0f;        // x high nibble
    case 0x8152: return g_touch_y & 0xff;              // y low
    case 0x8153: return (g_touch_y >> 8) & 0x0f;        // y high nibble
    case 0x8154: return 20;                            // touch size
    default: return 0;
    }
}

static uint32_t reg_read(uint32_t a) {
    if (a == 0x6002701cu) return i2c_rxi < i2c_rxn ? i2c_rx[i2c_rxi++] : 0; // I2C1 RX FIFO pop
    // Reset/strapping latches the hardware sets on power-up, read by the mask ROM to
    // decide how to boot. RESET_STATE: reset cause = POWERON_RESET(1) for both CPUs
    // (procpu bits[5:0], appcpu bits[11:6]). GPIO_STRAP: low nibble bit3 = SPI fast
    // flash boot (ETS_IS_FAST_FLASH_BOOT) so the ROM loads the 2nd-stage from flash.
    if (a == 0x60008038u) return (RD(a) & ~0xFFFu) | 0x041u;   // RTC_CNTL_RESET_STATE
    if (a == 0x60004038u) return 0x00000008u;                  // GPIO_STRAP: SPI_FAST_FLASH_BOOT
    if (a == 0x6003507cu) {                                     // WDEV_RND_REG: hardware RNG
        static uint32_t rng = 0x1a2b3c4du;                     // returns a fresh 32-bit sample each read
        rng = rng * 1664525u + 1013904223u; return rng;
    }
    if (a == 0x6003b018u) return 0;                             // SHA_BUSY: synchronous, never busy
    if (a == 0x6004106cu) return lcd_int_raw & RD(0x60041064);  // LCD_CAM LC_DMA_INT_ST = RAW & ENA
    if (a == 0x6002702cu) return RD(0x60027020) & RD(0x60027028); // I2C1 INT_STATUS = RAW & ENA
    // RTC_CNTL main timer (RTC slow-clock counter): TIME0/1 return the value latched by
    // the last TIME_UPDATE write. rtc_time_get() and the clock-calibration/delay loops in
    // rtc_init read it, so it must advance. Source it from g_ticks (monotonic system time).
    if (a == 0x60008010u) return (uint32_t)rtc_latch;           // RTC_CNTL_TIME0 (low 32)
    if (a == 0x60008014u) return (uint32_t)(rtc_latch >> 32);   // RTC_CNTL_TIME1 (high)
    // RTC_CNTL_INT_RAW (0x60008044): rtc_sleep_start sets SLEEP_EN (STATE0 bit31) then spins
    // on bits[1:0] here for the wake/reject status. Light sleep retains the digital core and
    // resumes in-place, and emulated time isn't wall-clock, so model an INSTANT wake: once
    // armed, report bit0 (SLP_WAKEUP) set / bit1 (SLP_REJECT) clear, so the poll exits and
    // rtc_sleep_start returns "woke up". (Deep sleep would reset the chip; these apps use the
    // idle/automatic light-sleep path, which must return.)
    if (a == 0x60008044u) return g_rtc_slp_armed ? 0x1u : RD(a);
    if (a == 0x60023004u || a == 0x60023008u) return RD(a) | (1u << 29);  // SYSTIMER UNITx_OP: value always valid
    // SYSTIMER UNIT0/1 VALUE_HI/LO: return the snapshot THIS core latched with UNITx_OP
    // UPDATE. Per-core snapshots keep the counter-read consistency loop stable under our
    // core interleaving (the two cores would otherwise re-latch the shared regs mid-read).
    if (a >= 0x60023040u && a <= 0x6002304cu) {
        uint64_t v = st_latch[cur_core()];
        return ((a & 4) == 0) ? (uint32_t)((v >> 32) & 0xFFFFF) : (uint32_t)v;  // +0/+8=HI, +4/+c=LO
    }
    if (a == 0x60023068u) return st_int_raw;                              // SYSTIMER_INT_RAW
    if (a == 0x60023070u) return st_int_raw & (RD(0x60023064) & 7);       // SYSTIMER_INT_ST (raw & ena)
    if (a == 0x6000e040u) return RD(a) | (1u << 24);    // I2C_MST_BBPLL_CAL_DONE: analog PLL cal always done
    if (a == 0x600c4130) return 0x1001;                 // cache sync state: idle
    if (a == 0x600c4150 || a == 0x600c4154) {           // D/ICACHE freeze: DONE(b2)=ENA(b0)
        uint32_t v = RD(a); return (v & ~4u) | ((v & 1u) << 2);
    }
    // USB-Serial-JTAG CDC FIFO/status (host<->device console; menu app-push channel).
    if (a == 0x60038000u) {                                     // EP1 rdwr_byte: pop one RX byte
        if (USJ_EXPOSED) { uint8_t b = usj_rx[usj_rx_head++]; usj_rx_len--; return b; }
        return 0;
    }
    if (a == 0x60038004u)                                       // EP1_CONF: IN_EP_DATA_FREE|OUT_EP_DATA_AVAIL
        return (1u << 1) | (USJ_EXPOSED ? (1u << 2) : 0);
    if (a == 0x60038008u)                                       // INT_RAW: OUT_RECV_PKT(2) | IN_EMPTY(3)
        return (USJ_EXPOSED ? (1u << 2) : 0) | (usj_in_empty ? (1u << 3) : 0);
    if (a == 0x6003800cu)                                       // INT_ST = RAW & ENA
        return ((USJ_EXPOSED ? (1u << 2) : 0) | (usj_in_empty ? (1u << 3) : 0)) & RD(0x60038010u);
    if (cache_status(a)) return 0xffffffff;             // cache op done
    return RD(a);
}

// The flash/PSRAM MMU page table lives in this MMIO window at 0x600C_5000; mem.c
// reads entries from here to translate cacheable virtual addresses.
uint32_t mmu_entry(uint32_t index) { return RD(0x600C5000u + index * 4); }

// ---------------- SYSTIMER alarms -> interrupts ----------------
// The FreeRTOS tick is a periodic SYSTIMER comparator alarm (TARGETi_CONF period),
// routed through the interrupt matrix to a per-core CPU interrupt. We fire each
// enabled comparator every `period` ticks and latch its raw-int bit until acked.
void systimer_step(void) {       // called once per emulated step from main.c
    if (lcd_done_at && g_ticks >= lcd_done_at) { lcd_int_raw |= 2; lcd_done_at = 0; }  // i80 TRANS_DONE
    uint32_t ena = RD(0x60023064) & 7;                      // SYSTIMER_INT_ENA
    for (int i = 0; i < 3; i++) {
        if (!(ena & (1u << i))) { st_next[i] = 0; continue; }
        uint32_t period = RD(0x60023034u + i*4) & 0x03ffffff;   // TARGETi_CONF period
        if (!period) continue;
        if (!st_next[i]) st_next[i] = g_ticks + period;
        if (g_ticks >= st_next[i]) { st_int_raw |= (1u << i); st_next[i] = g_ticks + period; }
    }
}

// Hardware CPU-interrupt bits asserted for `core`, routed through that core's slice
// of the interrupt matrix (MAP array base 0x600C2010 core0 / 0x600C2810 core1, one
// 32-bit MAP register per peripheral source holding the target CPU-interrupt number).
// A source reaches this core only if its MAP points at a CPU int this core enabled —
// callers AND the result with INTENABLE, so an un-routed source (MAP=6, nobody's int)
// harmlessly drops out. Sources: SYSTIMER TARGET0/1 = 53/54 (FreeRTOS tick, one per
// core); FROM_CPU_INTR0..3 = 78..81 (cross-core reschedule/IPC, esp_crosscore_int_send).
uint32_t mmio_cpu_int(int core) {
    // Interrupt-matrix MAP array: core0 at 0x600C2000, core1 at +0x800. Each peripheral
    // source's MAP register is at a fixed offset (NOT source_number*4): SYSTIMER TARGET0
    // = 0xE4, TARGET1 = 0xE8; FROM_CPU_INTR0..3 = 0x13C,0x140,0x144,0x148.
    uint32_t base = 0x600C2000u + (core ? 0x800u : 0u);
    uint32_t bits = 0;
    uint32_t ena = RD(0x60023064) & 7;                          // SYSTIMER_INT_ENA
    if ((st_int_raw & ena) & (1u << core))                      // TARGET0->core0, TARGET1->core1
        bits |= 1u << (RD(base + (core ? 0xE8u : 0xE4u)) & 0x1f);
    for (int n = 0; n < 4; n++)                                 // FROM_CPU_INTR0..3
        if (xcore_pend & (1u << n))
            bits |= 1u << (RD(base + 0x13Cu + (uint32_t)n * 4) & 0x1f);
    if (lcd_int_raw & RD(0x60041064u)) {                        // LCD_CAM (src 24): TRANS_DONE, level
        uint32_t map = RD(base + 0x60u) & 0x3f;                 //   MAP @ INTERRUPT_COREx_BASE+0x60
        if (map != 6) { bits |= 1u << (map & 0x1f); } // 6 = unconnected default
    }
    extern int g_spi2_irq;
    if (g_spi2_irq) {                                          // GP-SPI2 (src 21) TRANS_DONE — one-shot,
        uint32_t map = RD(base + 0x54u) & 0x3f;                //   armed at USR only when the int is enabled,
        if (map != 6) { bits |= 1u << (map & 0x1f); }         //   cleared by the ISR (INT_CLR @+0x38). MAP @+0x54
    }
    // USB-Serial-JTAG (src 96): OUT_RECV_PKT while host data pending, IN_EMPTY after a TX
    // flush — level-driven from usj state, AND-ed with INT_ENA. MAP @ INTERRUPT_COREx+0x180.
    {
        uint32_t uena = RD(0x60038010u);
        uint32_t uraw = (USJ_EXPOSED ? (1u << 2) : 0) | (usj_in_empty ? (1u << 3) : 0);
        if (uraw & uena & 0xc) {
            uint32_t map = RD(base + 0x180u) & 0x3f;
            if (map != 6) { bits |= 1u << (map & 0x1f); }
        }
    }
    // I2C_EXT1 (src 43) interrupt is modelled but NOT delivered: enabling it lets touch_init
    // succeed (probe ACKs), but the interrupt-driven multi-segment READ path then triggers an
    // abort in the touch task (empty panic details) that reboots into a null-PC loop — a
    // touch-only issue not worth destabilising the display for (no touch input when headless).
    // Left disabled so touch fails gracefully ("no GT911"); the probe/ACK model stays as the
    // foundation for finishing GT911 later (needs RX-FIFO data + the abort/reboot fixed).
    if (RD(0x60027020u) & RD(0x60027028u)) {        // I2C_EXT1 (GT911 touch) — now delivered; the MOVSP/alloca fix made the touch task stable
        uint32_t map = RD(base + 0xACu) & 0x3f;                 //   MAP @ INTERRUPT_COREx_BASE+0xAC
        if (map != 6) { bits |= 1u << (map & 0x1f); }
    }
    return bits;
}

// GDMA OUT (channel 0 -> LCD_CAM) descriptor processing. The e-ink driver builds a
// classic dma_descriptor_t chain in internal SRAM and hands its head to GDMA_OUT_LINK_
// CH0 (0x6003f080, low 20 bits of the address; base 0x3FC00000). Each descriptor dw0 =
// {size[11:0], length[23:12], eof[30], owner[31]} with buf @+4, next @+8. On a transfer
// we (a) read the row bytes straight from the DMA buffer and accumulate them into the
// panel model, and (b) write the owner bit back to CPU (as the real DMA does on done) so
// the driver's ISR gdma_link_mount_buffers() ownership check finds a free item. This is
// the faithful data path — no reliance on hooking the driver's tx_color symbol.
static void gdma_out_process(void) {
    extern void panel_row(const uint8_t *, int);
    uint32_t link = RD(0x6003f080u) & 0xfffffu;
    uint32_t d = link ? (0x3fc00000u | link) : 0;
    for (int i = 0; i < 64 && d; i++) {
        uint32_t w0 = mem_r32(d), buf = mem_r32(d + 4), nxt = mem_r32(d + 8);
        uint32_t len = (w0 >> 12) & 0xfff;
        if (buf && len) {
            static uint8_t row[600]; if (len > sizeof row) len = sizeof row;
            for (uint32_t k = 0; k < len; k++) row[k] = mem_r8(buf + k);
            panel_row(row, (int)len);
        }
        mem_w32(d, w0 & ~0x80000000u);          // owner -> CPU (DMA-done writeback)
        if (!(nxt) || (w0 & (1u << 30))) break;  // stop at EOF / end of chain
        d = nxt;
    }
}

// Soft reset (SW_SYS_RST): the digital peripherals reset but the RTC domain and flash
// persist. We clear the transient modelled peripheral state so the re-run boot starts
// clean; the boot hint (RTC_CNTL STORE4/5) and flash (the cached app) survive. The USB
// push is NOT re-armed (usj_fed stays set) so a launched app doesn't re-trigger it.
void mmio_reboot(void) {
    st_int_raw = 0; memset(st_next, 0, sizeof st_next); memset(st_latch, 0, sizeof st_latch);
    xcore_pend = 0; lcd_int_raw = 0; lcd_done_at = 0; flash_wren = 0; g_spi2_irq = 0;
    i2c_txn = 0; i2c_rxn = 0; i2c_rxi = 0; g_rtc_slp_armed = 0;
    usj_rx_len = 0; usj_rx_head = 0; usj_allow = 0; usj_tx_len = 0; usj_in_empty = 1;
    if (usj_rx) { free(usj_rx); usj_rx = 0; }
}

uint32_t mmio_read(uint32_t a) { g_last_read = a; return reg_read(a); }

static void gdma_out_process(void);

void mmio_write(uint32_t a, uint32_t v) {
    g_last_write = a;
    // USB-Serial-JTAG: EP1 write pushes a TX byte; EP1_CONF.WR_DONE flushes the packet
    // to the host (we print it); INT_CLR acks IN_EMPTY. RX (OUT_RECV_PKT) is level-driven
    // from usj_rx_len, so it self-clears when the host frame is drained.
    if (a == 0x60038000u) { if (usj_tx_len < (int)sizeof usj_tx) usj_tx[usj_tx_len++] = v & 0xff; return; }
    if (a == 0x60038004u) {
        if (v & 1u) {                                   // WR_DONE: emit the queued TX bytes
            if (usj_tx_len) {
                // After the frame is queued the console is on UART0, so the USB channel
                // carries only the push protocol: each 'K' is a chunk-ack — release the
                // next 4 KB chunk (stop-and-wait flow control, like push.py's read(1)=='K').
                if (usj_fed) for (int i = 0; i < usj_tx_len; i++) if (usj_tx[i] == 'K') usj_allow += USJ_CHUNK;
                static int verbose = -1; if (verbose < 0) verbose = getenv("PAPER_USB_PUSH") ? 1 : 0;
                if (verbose) fprintf(stderr, "[usj-tx] %.*s", usj_tx_len, (char *)usj_tx);
                usj_tx_len = 0;
            }
            usj_in_empty = 1;                            // signal SERIAL_IN_EMPTY (host took it)
        }
        return;
    }
    if (a == 0x60038014u) { if (v & (1u << 3)) usj_in_empty = 0; return; }   // INT_CLR: ack IN_EMPTY
    // RTC_CNTL_OPTIONS0 software reset. esp_restart() -> software_reset_cpu(0) sets
    // SW_PROCPU_RST (bit5); the whole-chip software_reset() sets SW_SYS_RST (bit31). Either
    // means "restart": the RTC domain (STORE4/5 boot hint) and flash persist, so main.c
    // re-runs the boot from the ROM reset vector and the custom bootloader picks up the hint.
    if (a == 0x60008000u && (v & ((1u << 5) | 0x80000000u))) { g_reboot_req = 1; return; }
    // RTC_CNTL_STATE0 (0x60008018): bit31 = SLEEP_EN triggers sleep. Arm the instant-wake
    // model (see the 0x60008044 read) so the light-sleep entry path resumes immediately.
    if (a == 0x60008018u && (v & 0x80000000u)) { g_rtc_slp_armed = 1; WR(a, v); return; }
    if (a == 0x60038010u) { WR(a, v);                                        // INT_ENA (stored)
        // The driver enables OUT_RECV_PKT during install (its RX path is ready) — that's our
        // cue to hand the queued app-push frame to the host->device FIFO.
        if ((v & (1u << 2)) && !usj_fed) { usj_build_push(); usj_fed = 1; }
        return;
    }
    // I2C1 (I2C_EXT1 @ 0x60027000) — the GT911 capacitive-touch bus. The i2c_master driver
    // builds a command list (COMD0.. @+0x58: RESTART=6/WRITE=1/READ=3/STOP=2/END=4 in bits
    // [13:11]), loads the address/register bytes into the TX FIFO, sets CTR.TRANS_START
    // (+0x04 bit5), and waits on the I2C1 interrupt (source 43, matrix MAP @+0xAC) for
    // TRANS_COMPLETE (INT bit7) / END_DETECT (bit3) / NACK (bit10). We model a GT911 that is
    // present and idle: ACK every transfer (never NACK) and raise the terminator that matches
    // the command list. Register reads return 0 (RX FIFO stays zero = no touch), so
    // touch_read() sees status reg 0x814E bit7 clear = "no fresh frame".
    if (a == 0x6002701cu) { if (i2c_txn < 64) i2c_tx[i2c_txn++] = v & 0xff; WR(a, v); return; } // I2C1 TX FIFO push
    if (a == 0x60027018u && (v & 0x300)) { i2c_txn = 0; i2c_rxn = i2c_rxi = 0; WR(a, v); return; } // TX/RX FIFO reset
    if (a == 0x60027004u && (v & (1u << 5))) {          // I2C1 CTR: TRANS_START
        WR(a, v & ~(1u << 5));                           //   trans_start self-clears
        // Walk the command list, driving the GT911 register model: WRITE(n) with an even
        // (write) address of >=3 bytes sets the register pointer [reg_hi,reg_lo] (+ any data
        // bytes written to it); READ(n) returns auto-incrementing GT911 register bytes into
        // the RX FIFO. ops in bits[13:11]: RESTART=6/WRITE=1/READ=3/STOP=2/END=4; count=bits[7:0].
        int ti = 0, has_end = 0; uint16_t reg = 0;
        i2c_rxn = i2c_rxi = 0;
        for (int i = 0; i < 16; i++) {
            uint32_t c = RD(0x60027058u + i*4u); int op = (c >> 11) & 7, n = c & 0xff;
            if (op == 1) {                               // WRITE n bytes (consume from TX FIFO)
                if (n >= 3 && ti + 2 < i2c_txn && !(i2c_tx[ti] & 1)) {
                    reg = (i2c_tx[ti+1] << 8) | i2c_tx[ti+2];       // [addr, reg_hi, reg_lo, data..]
                    for (int k = 3; k < n && ti+k < i2c_txn; k++)   // writes (e.g. clear 0x814E)
                        if ((uint16_t)(reg+(k-3)) == 0x814E) { /* status clear: nothing to store */ }
                }
                ti += n;
            } else if (op == 3) {                        // READ n bytes -> GT911 data
                for (int k = 0; k < n && i2c_rxn < 64; k++) i2c_rx[i2c_rxn++] = gt911_rd(reg++);
            } else if (op == 4) { has_end = 1; break; }  // END  -> segment boundary
            else if (op == 2 || op == 0) break;          // STOP -> transaction done
        }
        i2c_txn = 0;                                     // TX FIFO consumed
        WR(0x60027020u, RD(0x60027020u) | (has_end ? (1u << 3) : (1u << 7)));   // INT_RAW
        return;
    }
    if (a == 0x60027024u) {                             // I2C1 INT_CLR
        WR(0x60027020u, RD(0x60027020u) & ~v); WR(a, 0); return;
    }
    // EPD gate-driver start pulse GDSP (GPIO 17): the driver drives it low (GPIO
    // OUT_W1TC) at the top of each field to reset the panel to physical row 0.
    if (a == 0x6000400Cu && (v & (1u << 17))) { extern void panel_frame_reset(void); panel_frame_reset(); }
    if (a == 0x60000000u) { putchar(v & 0xFF); fflush(stdout); return; }   // UART0 TX
    if (a == 0x6002306cu) { st_int_raw &= ~v; return; }                    // SYSTIMER_INT_CLR
    if (a == 0x6003b010u) { WR(a, v); if (v & 1) sha_run(0); return; }     // SHA_START:   H<-IV, hash block
    if (a == 0x6003b014u) { WR(a, v); if (v & 1) sha_run(1); return; }     // SHA_CONTINUE: hash block, keep H
    if (a == 0x6000800cu) { if (v & 0x80000000u) rtc_latch = g_ticks; WR(a, v); return; }  // RTC_CNTL_TIME_UPDATE
    // LCD_CAM i80 (e-ink panel) bus: writing LCD_START runs the transfer; we complete it
    // synchronously and raise LCD_TRANS_DONE so the driver's wait loop finishes. START and
    // UPDATE are self-clearing (the driver polls them clear before the next op).
    if (a == 0x60041014u) { WR(a, v & ~((1u<<27)|(1u<<20)));                 // LCD_USER
        // LCD_START: don't complete synchronously — schedule TRANS_DONE a little later so
        // the driver finishes its post-start bookkeeping before its ISR fires (a same-cycle
        // done makes it mis-account the transaction pool). ~300 steps ≈ the real transfer.
        if (v & (1u<<27)) { gdma_out_process(); lcd_done_at = g_ticks + 40; }  return; }
    if (a == 0x60041070u) { lcd_int_raw &= ~v; WR(a, v); return; }           // LC_DMA_INT_CLR

    // GP-SPI2/SPI3 (general-purpose SPI master, 0x60024000 / 0x60025000). The SD-card
    // SPI host starts a user transaction by writing SPI_CMD.SPI_USR (bit24) and then
    // polls it until hardware clears it. There is no SD card wired on this build, so
    // MISO idles high: we complete the transaction immediately (clear USR/UPDATE) and
    // put 0xFF in the CPU data buffer (SPI_W0..W15 @ +0x98). The sdspi/sdmmc probe then
    // reads all-ones, retries, and cleanly reports "no card" instead of hanging.
    if (a == 0x60024000u || a == 0x60025000u) {                              // SPI_CMD_REG
        if (v & (1u << 24)) {                                                //   SPI_USR: run
            if (a == 0x60024000u) {   // SPI2 host = CO5300 AMOLED over QSPI
                // The esp_lcd QSPI panel-io sends every command, parameter and pixel
                // run through GDMA channel 0. Gather this transaction's MOSI payload
                // from the OUT descriptor chain and hand it to the CO5300 decoder,
                // which maintains the CASET/RASET window and writes RAMWR pixels into
                // the panel's frame memory — the faithful screen data path.
                static uint8_t xbuf[480 * 1024]; uint32_t xn = 0;
                uint32_t link = RD(0x6003f080u) & 0xfffff;
                uint32_t d = link ? (0x3fc00000u | link) : 0;
                for (int i = 0; i < 8192 && d; i++) {
                    uint32_t w0 = mem_r32(d), buf = mem_r32(d + 4), nxt = mem_r32(d + 8);
                    uint32_t L = (w0 >> 12) & 0xfff;
                    if (buf && L) for (uint32_t k = 0; k < L && xn < sizeof xbuf; k++) xbuf[xn++] = mem_r8(buf + k);
                    mem_w32(d, w0 & ~0x80000000u);          // DMA-done: owner -> CPU
                    if ((w0 & (1u << 30)) || !nxt) break;   // suc_eof / end of chain
                    d = nxt;
                }
                extern void co5300_spi2_xfer(const uint8_t *, uint32_t);
                if (xn) co5300_spi2_xfer(xbuf, xn);
            } else {                                        // SPI3: no device wired
                for (int i = 0; i < 16; i++) WR(a + 0x98u + i*4u, 0xFFFFFFFFu);
            }
            WR(a + 0x3Cu, RD(a + 0x3Cu) | (1u << 12));                       //   raise TRANS_DONE (@+0x3C bit12)
            if (a == 0x60024000u && (RD(a + 0x34u) & (1u << 12))) g_spi2_irq = 1;  // arm int if enabled
        }
        WR(a, v & ~((1u << 24) | (1u << 23)));                               //   USR + UPDATE self-clear
        return;
    }
    if (a == 0x60024038u || a == 0x60025038u) {                             // SPI_DMA_INT_CLR
        uint32_t base = a & 0xffffff00u;
        WR(base + 0x3Cu, RD(base + 0x3Cu) & ~v);                            //   clear the polled status bits
        if ((a == 0x60024038u) && (v & (1u << 12))) g_spi2_irq = 0;         //   ISR ack -> disarm the interrupt
        WR(a, 0); return;
    }

    // Cross-core interrupt: SYSTEM_CPU_INTR_FROM_CPU_0..3 (0x600C_0030..003C). The
    // sending core writes bit0=1 to raise FROM_CPU_INTRn (a level-triggered matrix
    // source, 78..81); the target core's ISR writes 0 to clear it. This is how the
    // scheduler on one core forces the other to reschedule (esp_crosscore_int_send).
    if (a >= 0x600C0030u && a <= 0x600C003Cu) {
        int n = (a - 0x600C0030u) >> 2;
        if (v & 1) xcore_pend |= (1u << n); else xcore_pend &= ~(1u << n);
        WR(a, v); return;
    }

    WR(a, v);
    // MSPI command trigger: SPIMEM1 CMD (0x6000_2000) — run the programmed
    // transaction and clear CMD to 0 so the firmware's poll completes.
    if (a == 0x60002000u && v != 0) { mspi_exec(0x60002000u, v); WR(0x60002000u, 0); }

    // SYSTIMER: writing UNITx_OP UPDATE (bit30) latches the 52-bit counter into
    // that unit's VALUE_HI/LO. We source the count from the monotonic g_ticks.
    if ((a == 0x60023004u || a == 0x60023008u) && (v & (1u << 30))) {
        st_latch[cur_core()] = g_ticks;                       // latch a per-core snapshot
    }

    // RTC-clock calibration (TIMG0/1 RTCCALICFG @ +0x68): the firmware starts a
    // count and polls RTC_CALI_RDY (bit15), then reads RTC_CALI_VALUE (RTCCALICFG1
    // bits[31:7]) = main-clock cycles per RTC_CALI_MAX slow-clock cycles. We complete
    // instantly with a value for a ~136 kHz RC_SLOW clock against the 40 MHz XTAL.
    if (a == 0x6001F068u || a == 0x60020068u) {
        if (v & (0x80000000u | 0x1000u)) {        // CALI_START or CALI_START_CYCLING
            uint32_t max = (v >> 16) & 0x7fff;
            uint32_t val = max * 294u; if (val > 0x1ffffffu) val = 0x1ffffffu;
            WR(a, v | 0x8000u);                   // RTC_CALI_RDY
            WR(a + 4, val << 7);                  // RTCCALICFG1 VALUE
        }
    }
}