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
}
}
}