From c3faa7729dece4df4c36cc987fed21cc1af2e8b7 Mon Sep 17 00:00:00 2001 From: SDD Date: Fri, 16 Oct 2026 13:19:25 +0300 Subject: [PATCH] docs: correct stale README - DUARTs/VRAM are modelled, fix memory_access template args, add gate list and new baseline --- harness/mame/README.md | 83 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 74 insertions(+), 9 deletions(-) diff --git a/harness/mame/README.md b/harness/mame/README.md index bdff39b..c4a7905 100644 --- a/harness/mame/README.md +++ b/harness/mame/README.md @@ -13,18 +13,28 @@ tree is disposable and lives outside the project harness/mame/ ├── vt1200.cpp # the MAME driver (symlinked into the MAME tree) ├── build.sh # clone-safe build wrapper -├── trace.lua # Lua: trace execution from the reset vector -├── overflow.lua # Lua: exercise the pcfReadBitmaps n*4 overflow -├── FINDINGS.md # results, evidence, and what was learned +├── *.lua # probe / capture / dump scripts (many; see the reports) └── roms/vt1200/ # MAME ROM dir (symlink to ../../vt1200_v22.bin) ``` +Reports in this directory: + +| file | what it records | +|---|---| +| `GATE_CLEANUP_REPORT.md` | promoting the working config to the default; retiring the settled env gates | +| `RENDER_REPORT.md` | the active-pixel scanline renderer, and the geometry it derived | +| `DUART_REPORT.md` | the DUARTs: wiring, the ISR-driven transmit, the datasheet-verified model edits | +| `BRINGUP_LOG.md` | the whole bring-up narrative, **including withdrawn claims** — read it sceptically | +| `ROMPATCH_REPORT.md` | runtime ROM patching (debug only — see the caveat) | + ## Address model (the important part) The TMS34010 is **bit-addressed**: a register/PC holds a bit address, and a pointer `P` refers to physical byte `P >> 3`. MAME models this with a program -space of `memory_access<32, 16, 3>`, i.e. the **address-map unit is 1 bit** -(a 16-bit word spans 16 address units). Therefore: +space of `memory_access<32, 1, 3>`, i.e. the **address-map unit is 1 bit** +(a 16-bit word spans 16 address units). Source: `tms34010.h` — note the +TMS34020 differs (`memory_access<32, 2, 3>`), so this is *not* interchangeable +with the 34020. Therefore: * Address-map entries here are **bit addresses**, not byte addresses. * `read_word(0x3f200000)` returns ROM bytes 0..1 (physical byte 0x07e40000). @@ -39,10 +49,65 @@ The driver maps: | ROM | `0x3f200000`–`0x3fffffff` | 1.75 MiB at byte 0x07e40000 | | ROM aliases | `0x7f…`, `0xbf…`, `0xff200000`–`0xffffffff` | same ROM (top 2 logical bits not decoded) | -The `0xff…` alias is what makes the reset-vector page resolve. Board -peripherals (LANCE Ethernet, DUARTs) are **not** modelled; their reads return -`0xffff` and writes are dropped. The terminal will therefore not boot to the -X server — that is expected and not the goal. +The `0xff…` alias is what makes the reset-vector page resolve. + +### What is modelled by default + +This **changed** — see `GATE_CLEANUP_REPORT.md`. The working configuration used +to be a six-variable incantation; it is now the default, and a bare +`vt1200 vt1200` with **no environment** runs it. + +* Video RAM at bit `0x04000000` — required for the level-1 VIDEO MEMORY test. +* The board-window handshake model (two-tick busy bit). +* MAME's `SCN2681` DUART at **DUART1** (`0x0640000`, host/printer), with input + port **IP4–IP6 held high** — that is how the driver reads the VR150 monitor + switch (`0x70`). The level-1 host-port transmit is **ISR-driven**, so a real + DUART is required here, not a convenience. +* A mono palette (pens 0/1 = black/white) and an active-pixel scanline renderer + that reads VRAM. See `RENDER_REPORT.md`. + +A bare run progresses through POST and level 1 and stops at `HOST PORT - 15`, +then **wedges in the system-board LED loop** — a level-1 failure is *fatal*, not +merely reported, so the OS is unreachable while it fails. + +### What is not modelled + +**LANCE Ethernet**, and **DUART2** (`0x0620000`, keyboard/mouse — opt in with +`VT1200_DUART2=1`). The OS is therefore not usable yet: it is reached, but it +does not paint. + +### Getting past level 1 + +`VT1200_SKIP_LEVEL1=1` drives DUART1's **IP3** high, which the firmware takes as +a signal to jump to the OS cold-start and skip **all 15** level-1 tests. Note +what this is: a *modelled board input*, and the real machine reads IP3 **low**. +So a level-1-skipped run is evidence about the **OS, graphics and crash +behaviour**, and is **not** evidence about the real terminal's POST. + +The skip is deliberately **not** the default: the real machine runs level 1, so +the faithful configuration stays the default and the switch is how we diverge. + +## Environment knobs (14; down from 33) + +All opt-in, all off by default, so a bare run is the working configuration. +Instrumentation: `VT1200_DUARTLOG`, `VT1200_BOARD_LOG`, `VT1200_BOARD_MAP`, +`VT1200_IRQLOG`, `VT1200_LOG_UNMAPPED`, `VT1200_DPYLOG` (+`_FRAMES`), +`VT1200_DUMP_FRAME`, `VT1200_DUMP_RAM`, `VT1200_DUMP_VRAM`, `VT1200_DUMP_DIR`, +`VT1200_NO_RENDER`. Behaviour switches: `VT1200_SKIP_LEVEL1`, `VT1200_DUART2`. + +## Regression baseline + +`progress.lua` at 200 frames, **no env**: + +``` +PC=3FDCE400 samples=53 (78 distinct PCs) +``` + +This value **changed** when the working config became the default — previously +`PC=3FDCE400 samples=199` (a single PC), because a no-env run used to wedge at +the hardware-ready gate. The new value is *better*: a bare run now executes real +POST work. It is a change detector, not a specification — if it moves without +you meaning it to, find out why. ## Build