S1a = S1 + the mechanisms below. Today the 71 CLI flags are identical to S1; this page will track S1a as they diverge. The difference right now is entirely in environment variables: S1a shares S1's 16 env vars and adds 11 of its own — the M2 / M4 / M6X physics mechanisms plus extra per-shim kill switches. The shared 71-flag + 16-env reference is reproduced in full below so this page stands alone.
S1a = S1 + 下面的機制。今天這 71 個 CLI 旗標與 S1 相同;本頁會隨 S1a 分化而追蹤更新。此刻的差異完全在環境變數:S1a 共用 S1 的 16 個環境變數,並加自己的 11 個 —— M2 / M4 / M6X 物理機制,加上額外的 per-shim 關閉開關。共用的 71 旗標 + 16 環境變數參考在下方完整重現,讓本頁自足。
The S1a differenceS1a 的差異What S1a adds over S1 — the 11 mechanism env varsS1a 比 S1 多的 —— 11 個機制環境變數
Each S1a mechanism restores a slice of physics the binary switch-level model cannot express, and lands behind its own switch so S1's golden checksum is never disturbed. M2 charge-decay is the only one ON by default (it retired a shim after a three-arm proof); the rest are opt-in. The mechanisms supersede the hand-written shims they replace — arm the mechanism and its shims auto-disable.
每個 S1a 機制還原一片二值開關級模型表達不了的物理,並躲在自己的開關後面,絕不動到 S1 的金 checksum。只有 M2 電荷衰減預設開(它經三段論證後退役了一個 shim);其餘都是 opt-in。機制會取代它們替換掉的手寫 shim —— 武裝機制,對應的 shim 自動關閉。
Physics mechanisms物理機制
| Variable變數 | Value值 | Default預設 | What it does / what it supersedes作用 / 取代什麼 |
|---|---|---|---|
NO_M2DECAY(M2 charge-decay)(M2 電荷衰減) |
set = OFF有設 = 關 | ON by default預設開 | M2 charge-decay is default-ON in S1a: engine-level per-bit timestamp decay on the 2C02 io-bus latch island (the "decay register" leaks to 0 in ~600 ms). It retires the runner-level _io_db decay shim (three-arm proven 2026-07-18: ppu_open_bus shim PASS / no-shim FAIL / mechanism PASS). Set NO_M2DECAY to turn the mechanism OFF and restore the old io_db shim. There is no M2_DECAY enabling env — a stale code comment says so, but the mechanism is default-on and NO_M2DECAY is the only control.M2 電荷衰減在 S1a 預設開:2C02 io 匯流排 latch 島上的引擎級 per-bit 時戳衰減(「衰減暫存器」不刷新 ~600ms 漏到 0)。它退役了 runner 級的 _io_db 衰減 shim(2026-07-18 三段論證:ppu_open_bus shim PASS / 拔 shim FAIL / 機制 PASS)。設 NO_M2DECAY 把機制關掉、還原舊 io_db shim。沒有 M2_DECAY 這個啟用 env —— 有句過時的 code 註解那樣寫,但機制是預設開,NO_M2DECAY 才是唯一控制。 |
M2_CAP |
set, ≠0有設、≠0 | opt-in選用 | M2 physical-capacitance floating arbitration: floating groups resolve by physical capacitance (die polygons + gate W×L) instead of the engine's connection-count proxy — swapped in at Reset() fill time, read at LoadSystem. Changes the NodeStates checksum by design (~10.3% of floating-pair elections flip). Use for the M2 census / study, not for the golden gate.M2 物理電容浮接裁決:浮接群改用物理電容(晶粒多邊形 + 閘極 W×L)解析,取代引擎的連接數代理 —— 在 Reset() 填值時換入,LoadSystem 時讀取。設計上會改 NodeStates checksum(~10.3% 浮接對選舉翻盤)。用於 M2 普查 / 研究,不是金閘。 |
M2_CENSUS |
set, ≠0有設、≠0 | opt-in · DEBUG選用 · DEBUG | DEBUG-build firing census: shadow the legacy connection-count key and tally, per floating resolve, how often the M2 physical key and the legacy key disagree. Needs M2_CAP and a DEBUG build; diagnostic only.DEBUG 版開火普查:影子跑 legacy 連接數鍵,對每次浮接解析統計 M2 物理鍵與 legacy 鍵多常不一致。需 M2_CAP 與 DEBUG 版;僅診斷。 |
M4_EDGE |
set, ≠0有設、≠0 | opt-in選用 | Arm the M4 generic edge-capture latch primitive with its built-in annotation rows (DMC pcm_latch = data-wins; ALU input latches = hold). A mechanism, independent of --no-shims. When armed it supersedes the DmcLatch + AluLatch shims (they auto-disable).武裝 M4 通用邊沿捕捉閂鎖原語,附內建標註列(DMC pcm_latch = 資料贏;ALU 輸入閂鎖 = hold)。這是機制,與 --no-shims 無關。武裝後取代 DmcLatch + AluLatch shim(它們自動關)。 |
M4_DL |
set, ≠0有設、≠0 | opt-in · needs M4_EDGE選用 · 需 M4_EDGE | Add the DL/idl transparent-latch row to the M4 mechanism (glitch immunity at $4016/$4017; scoped, ≥2-bit capture signature). Read inside EnableM4EdgeLatch, so it only takes effect when M4_EDGE is armed. Targets the DL shim.為 M4 機制加上 DL/idl 透明閂鎖列($4016/$4017 毛刺免疫;有範圍、≥2 位元捕捉簽章)。在 EnableM4EdgeLatch 內讀取,只有 M4_EDGE 武裝時才生效。瞄準 DL shim。 |
M6X |
set, ≠0有設、≠0 | opt-in選用 | Arm the M6×M3 unified cross-chip phase-arbitration table — one (trigger, gate, delay, window) mechanism. It supersedes the dot-339 + BGSerialIn + even_odd downstream-clamp shims (they gate off when it is armed).武裝 M6×M3 統一跨晶片相位裁決表 —— 一個 (trigger, gate, delay, window) 機制。它取代 dot-339 + BGSerialIn + even_odd 下游 clamp shim(武裝時它們關閉)。 |
Per-shim kill switches added in S1a (set = skip that shim)S1a 新增的 per-shim 關閉開關(有設 = 跳過該 shim)
| Variable變數 | Skips跳過 | Notes備註 |
|---|---|---|
NO_DMC_SHIM | DMC pcm_latch edge-capture shimDMC pcm_latch 邊沿捕捉 shim | Also auto-off when M4_EDGE is armed (the mechanism supersedes it). No S1 equivalent.M4_EDGE 武裝時也自動關(機制取代它)。S1 無對應。 |
NO_ALU_SHIM | ALU input-latch hold shimALU 輸入閂鎖 hold shim | Env twin of the --no-alu-shim CLI flag; also auto-off under M4_EDGE.--no-alu-shim CLI 旗標的 env 版;M4_EDGE 下也自動關。 |
NO_LXA_SHIM | LXA $AB magic=$FF bus-fight shimLXA $AB magic=$FF 匯流排對抗 shim | No S1 equivalent (S1 always arms it under !--no-shims).S1 無對應(S1 在 !--no-shims 下恆開)。 |
NO_FRAMEIRQ_SHIM | frame-IRQ flag-hold shimframe-IRQ 旗標 hold shim | No S1 equivalent.S1 無對應。 |
NO_IODECAY_SHIM | runner-level _io_db decay fallback shimrunner 級 _io_db 衰減備援 shim | Only relevant when the M2 decay mechanism is OFF (i.e. under NO_M2DECAY); when M2 decay is on, this shim is already superseded.只有 M2 衰減機制關掉時(即 NO_M2DECAY 下)才有意義;M2 衰減開時此 shim 已被取代。 |
Mechanism ⇄ shim map (see the shim ledger for the full retirement status):
NO_M2DECAY→io_db decay · M4_EDGE→DmcLatch + AluLatch · M4_DL→DL · M6X→dot-339 + BGSerialIn + even_odd. Each mechanism keeps the golden checksum unchanged while OFF, and every retirement is gated on AC 141/141 + the 147-ROM regression with it ON.
機制 ⇄ shim 對應(完整退役狀態見shim 總帳):NO_M2DECAY→io_db 衰減 · M4_EDGE→DmcLatch + AluLatch · M4_DL→DL · M6X→dot-339 + BGSerialIn + even_odd。每個機制關閉時金 checksum 不變,每次退役都以機制開時 AC 141/141 + 147 顆回歸為閘。
1 · Entry points1 · 入口Mode selectors執行模式(擇一) identical to S1 today今天與 S1 相同
| Flag旗標 | Argument引數 | What it does作用 |
|---|---|---|
--benchmark | <rom> | Throughput mode: run a fixed number of master half-cycles, print hc/s, simulated FPS, MIPS, and the NodeStates checksum. ROM path optional.效能量測模式:跑固定數量的主 half-cycle,輸出 hc/s、模擬 FPS、MIPS、NodeStates checksum。ROM 路徑可選。 |
--test | <rom> | Run one test ROM to a verdict (blargg $6000, AccuracyCoin block, screen text, or CRC) or until the frame budget runs out; result in the exit code.跑單顆測試 ROM 到判定(blargg $6000、AccuracyCoin 塊、畫面文字或 CRC),或到幀預算耗盡;結果在 exit code。 |
--test-dir | <dir> | Batch-run every *.nes under a directory (recursive); prints an N/total passed summary.批次跑目錄下每顆 *.nes(遞迴);印 N/total passed 總結。 |
--rom | <rom> | Headless build has no window — a bare ROM renders 3 frames to screenshot.png; positional catch-all.headless 版無視窗 —— 純 ROM render 3 幀到 screenshot.png;位置性引數。 |
--selftest | — | Run the built-in inverter / NAND / pass-gate / callback / static-merge micro-circuits.跑內建 inverter / NAND / pass-gate / callback / static-merge 微電路。 |
--help -h /? | — | Print usage and exit.印使用說明並結束。 |
2 · Simulation environment2 · 模擬環境How the chip is loaded and run晶片怎麼載入與跑 identical to S1 today今天與 S1 相同
| Flag旗標 | Argument引數 | What it does作用 |
|---|---|---|
--system-def-dir | <dir> | Directory of the .js system-module definitions (default data/system-def)..js 系統模組定義的目錄(預設 data/system-def)。 |
--extra-ram | — | Force-map cart extra-RAM ($6000-$7FFF). Required for the golden checksum; --ac-verdict auto-disables it.強制掛載 cart extra-RAM($6000-$7FFF)。金 checksum 必帶;--ac-verdict 會自動停用。 |
--region | ntsc|pal|dendy | Select region timing (default ntsc).選區域時序(預設 ntsc)。 |
--joypad | — | Attach the behavioral joypad + u7/u8 tie-rewire (per-test). OFF by default (load-time graph change re-rolls the alignment lottery).掛行為層手把 + u7/u8 tie-rewire(per-test)。預設關(載入期圖變更會重擲對齊彩票)。 |
--reset-hold-extra | <K> | Hold reset K extra half-cycles (CPU/PPU phase-alignment). Flagship recipe uses K=1.reset 多按住 K 個 half-cycle(CPU/PPU 相位對齊)。旗艦配方用 K=1。 |
--pin | [N] | Pin the hot thread + High priority + EcoQoS-off to cut bench variance (Windows). No arg = auto P-core; N = force core N. Bit-exact; no frequency change.釘熱執行緒 + High priority + 關 EcoQoS 降 variance(Windows)。無引數 = 自動 P-core;N = 強制核 N。bit-exact;不改頻率。 |
--no-lower | — | Skip the S1.5 netlist-lowering pass (mapped-checksum A/B gate).跳過 S1.5 netlist-lowering pass(mapped-checksum A/B 閘)。 |
--fast-path | — | No-op — fast-path is always on; accepted for compatibility.無作用 —— fast-path 恆開;保留相容。 |
3 · Verdict detection3 · 測試判定How a test-ROM result is read測試 ROM 結果怎麼判 identical to S1 today今天與 S1 相同
| Flag旗標 | Argument引數 | What it does作用 |
|---|---|---|
--ac-verdict | — | AccuracyCoin unattended verdict: read the completion block at CPU RAM $07F0 (DE B0 61 + passed/total/skipped). Auto-disables extra-RAM; storm detection + $0400-$04FF table dump at exit.AccuracyCoin 無人值守判定:讀 CPU RAM $07F0 完成塊(DE B0 61 + passed/total/skipped)。自動停用 extra-RAM;含風暴偵測 + 結束傾印 $0400-$04FF 表。 |
--screen-verdict | — | B-class: per-frame nametable scan for a terminal Passed/Failed marker; 2-frame confirm.B 類:逐幀掃 nametable 找 terminal Passed/Failed;2 幀確認。 |
--pass-marker | <txt> | Custom terminal PASS text for ROMs that never print "Passed".為不印 "Passed" 的 ROM 自訂 PASS 字串。 |
--expected-crc | <A,B,…> | C-class: accept set for an on-screen 8-hex CRC (dmc_dma visual tests); 2-frame confirm.C 類:畫面 8-hex CRC 接受集(dmc_dma 視覺測試);2 幀確認。 |
--max-wait | <sec> | Wall-clock safety cap (0 = disabled). --max-frames is primary.wall-clock 安全上限(0 = 停用)。--max-frames 為主。 |
--max-frames | <N> | Simulation-frame budget — the primary limit (default 900 ≈ 15 sim-sec).模擬幀預算 —— 主要限制(預設 900 ≈ 15 模擬秒)。 |
--input | "<spec>" | Scripted input, Button:sec[:holdSec] (e.g. A:2,Start:6.5).腳本化輸入,Button:秒[:holdSec](如 A:2,Start:6.5)。 |
--test-json | <path> | Structured per-test result record (schema aprvisual-testrom/1).結構化每測結果記錄(schema aprvisual-testrom/1)。 |
--test-screenshot | <path> | Save the final frame as a PNG.把最終幀存成 PNG。 |
--shot-delay | <N> | N extra frames after the verdict before the screenshot (cosmetic).判定後多跑 N 幀再截圖(裝飾)。 |
4 · Snapshot / resume · 5 · progress4 · 快照/續跑 · 5 · 進度Windowed regression & long-run telemetry窗口回歸與長跑遙測 identical to S1 today今天與 S1 相同
| Flag旗標 | Argument引數 | What it does作用 |
|---|---|---|
--snapshot-frames | <N> | Full engine-state snapshot every N frames (0 = off). ~380 KB each; carries live shim state + CRC-32.每 N 幀存完整引擎狀態(0 = 關)。每顆 ~380 KB;含 live shim 狀態 + CRC-32。 |
--snapshot-dir | <dir> | Where the snapshot .sav files land.snapshot .sav 輸出目錄。 |
--resume | <sav> | Restore a snapshot after LoadSystem, continue from frame+1. Fingerprint check refuses a config mismatch.LoadSystem 後還原快照,從 frame+1 續跑。指紋校驗不符即拒。 |
--progress-frames | <N> | Every N frames: checkpoint latest.png + a JSON line in progress.jsonl. 0 = off.每 N 幀:checkpoint latest.png + progress.jsonl 一行 JSON。0 = 關。 |
--progress-dir | <dir> | Where those checkpoints land (cleared of stale files at start).checkpoint 輸出目錄(啟動時清舊檔)。 |
6 · Benchmark / perf6 · 效能量測Throughput knobs & profiling dumps吞吐旋鈕與剖析傾印 identical to S1 today今天與 S1 相同
| Flag旗標 | Argument引數 | What it does作用 |
|---|---|---|
--bench-hc | <N> | Benchmark exactly N raw master half-cycles. Golden: 300000 → 0x794A43ABDF169ADA (mechanisms OFF).benchmark 精確跑 N 個原始主 half-cycle。金:300000 → 0x794A43ABDF169ADA(機制關)。 |
--log-dir | <dir> | Benchmark JSON log output directory (default log).benchmark JSON log 輸出目錄(預設 log)。 |
--dump-states | <path> | Dump per-node states after the bench run (A/B per-node diff).bench 後傾印全節點狀態(A/B 逐節點 diff)。 |
--array-footprint | — | Print the hot unmanaged-array base+size at setup (IBS/SPE bucketing).設定時印熱 unmanaged 陣列 base+size(IBS/SPE 分桶)。 |
--payload-hist | <path> | NodeInfo inline-payload size distribution.NodeInfo inline-payload 大小分佈。 |
--fc-taint-stats | <path> | same-state-prune eligibility (FC-free vs FC-tainted; diagnostic).same-state-prune 適格性(FC-free vs FC-tainted;診斷)。 |
7 · Shim toggles & shared env vars7 · Shim 開關與共用環境變數The analog-race patch surface類比賽跑補丁面
In S1a, most of these shims are superseded by mechanisms. The CLI flags below are identical to S1, but note: arming
M4_EDGE auto-disables the ALU + DMC shims, and arming M6X auto-disables the dot-339 / BGSerialIn / even_odd write-delay shims. The 16 shared env vars are identical to S1; the 11 S1a-only mechanism env vars are documented in What S1a adds above.
在 S1a,大多數這些 shim 已被機制取代。下方 CLI 旗標與 S1 相同,但注意:武裝 M4_EDGE 會自動關 ALU + DMC shim,武裝 M6X 會自動關 dot-339 / BGSerialIn / even_odd 寫延遲 shim。16 個共用環境變數與 S1 相同;11 個 S1a 專屬機制環境變數見上方 S1a 加了什麼。
CLI shim flagsCLI shim 旗標 identical to S1與 S1 相同
| Flag旗標 | Argument引數 | What it does作用 |
|---|---|---|
--no-shims | — | Disable all test-mode shims. Does NOT disable the S1a M2 / M4 / M6X mechanisms — those are gated by their own env vars.停用全部 test-mode shim。不會關 S1a 的 M2 / M4 / M6X 機制 —— 那些由自己的環境變數控制。 |
--no-alu-shim | — | A/B the ALU input-latch hold shim (also skippable via NO_ALU_SHIM; auto-off under M4_EDGE).A/B ALU 輸入閂鎖 hold shim(也可用 NO_ALU_SHIM 跳過;M4_EDGE 下自動關)。 |
--no-dbl2007-shim | — | A/B the $2007 double-read merge shim.A/B $2007 雙讀合併 shim。 |
--no-ppu-ale-read-feedback-shim | — | Expose the raw CHR ALE+/RD analog-feedback loop (P4 guard).暴露原始 CHR ALE+/RD 類比回授環(P4 guard)。 |
--oam-dma-ppu-bus-shim | — | Re-affirm the $4014-from-PPU-I/O-bus OAM write hold (already ON by default).重申 $4014-自-PPU-I/O-bus OAM 寫 hold(預設本來就開)。 |
--no-oam-dma-ppu-bus-shim | — | Disable that OAM-DMA-PPU-bus shim.停用該 OAM-DMA-PPU-bus shim。 |
--ppu-write-delay | <N> | $2001 write-effect delay in hc (even_odd; default 16; 0 = off). Auto-off under M6X.$2001 寫入生效延遲 N hc(even_odd;預設 16;0 = 關)。M6X 下自動關。 |
--ppu-write-delay-global | <N> | dot-339 sprite-counter-reset delay in hc (default 24; 0 = off). Auto-off under M6X.dot-339 精靈計數器重置延遲 N hc(預設 24;0 = 關)。M6X 下自動關。 |
--callback-drain-limit | <N> | Non-convergence guard: fail with callback/node evidence if one drain exceeds N dispatches (AC recipe uses 2000).非收斂 guard:單次排水超 N 次 dispatch 就帶證據失敗(AC 配方用 2000)。 |
Shared environment variables (16)共用環境變數(16 個) identical to S1與 S1 相同
| Variable變數 | Value值 | What it does作用 |
|---|---|---|
| Group A — ALERead phase muxA 組 — ALERead 相位 mux | ||
ALEREAD_MUX | set (any)有設(任意) | Arm the ALERead $2007-access phase mux + node-split (cuts ppu.io_ab↔cpu.ab). MUST be present before LoadSystem. Required for the ALERead test; the flagship recipe sets ALEREAD_MUX=1. The one everyone forgets.武裝 ALERead $2007 存取相位 mux + node-split(切開 ppu.io_ab↔cpu.ab)。必須在 LoadSystem 前存在。ALERead 測試必需;旗艦配方設 ALEREAD_MUX=1。大家最常忘的那個。 |
MUX_HC | sw,rpS,rpE,fzS,fzE | Tune the five mux window edges. Default 13,13,25,44,52 — the only calibration verified to PASS in-suite (matches the code default).調 mux 五個窗邊。預設 13,13,25,44,52 —— 唯一驗證套內 PASS 的校準(與 code 預設相同)。 |
MUX_GATE | vlo,vhi,hlo,hhi | Override the mux detection gate. Default 3,3,220,226 — tight, so only the boing2k7 stunt read triggers it.覆蓋 mux 偵測閘。預設 3,3,220,226 —— 很緊,只有 boing2k7 特技讀取會觸發。 |
MUX_DBG | set有設 | Print [mux] arm/detect/replay/freeze trace (also on under OB_DEBUG).印 [mux] arm/detect/replay/freeze 追蹤(OB_DEBUG 下也會開)。 |
| Group B — per-shim kill switches (set = skip)B 組 — per-shim 關閉開關(有設 = 跳過) | ||
NO_OB_SHIM | set有設 | Skip the open-bus last-transferred-byte replay shim.跳過 open-bus 最後傳輸位元組重放 shim。 |
NO_DL_SHIM | set有設 | Skip the DL/idl φ2-transparency shim at $4016/$4017. (In S1a, M4_DL is the mechanism form.)跳過 $4016/$4017 的 DL/idl φ2 透明 shim。(在 S1a,M4_DL 是其機制形式。) |
NO_ABORT_SHIM | set有設 | Skip the deferred-$4015 DMC-DMA abort shim.跳過延遲 $4015 的 DMC-DMA 中止 shim。 |
NO_OAMEDGE_SHIM | set有設 | Skip the rendering-disable-edge OAM-write-suppression shim.跳過關渲染邊沿抑制 OAM 寫入的 shim。 |
NO_BGS_SHIM | set有設 | Skip the BG-serial reload-delay shim (M6 family; superseded by M6X).跳過 BG 序列 reload 延遲 shim(M6 家族;被 M6X 取代)。 |
| Group C — forensic debug probesC 組 — 取證除錯探針 | ||
OB_DEBUG | 1 | Turn on the test-only forensic probe group ([ob]/[dl]/[dma]/[pcm]/[ae]…; some carry hardcoded time windows). Also enables the mux trace.開 test-only 取證探針群([ob]/[dl]/[dma]/[pcm]/[ae]…;部分帶硬編時間窗)。也開 mux 追蹤。 |
LAE_DEBUG | 1 | LAE shim forensic output.LAE shim 取證輸出。 |
ODMA_DEBUG | set有設 | OAM-DMA-PPU-bus shim forensic output.OAM-DMA-PPU-bus shim 取證輸出。 |
PB_DEBUG | set有設 | PPU ALE/read-feedback shim forensic output.PPU ALE/read-feedback shim 取證輸出。 |
PWD_DEBUG | 1 | $2001 write-delay shim forensic output.$2001 寫入延遲 shim 取證輸出。 |
OE_DEBUG | set有設 | OAM-blank-edge shim forensic output.OAM-blank-edge shim 取證輸出。 |
PC_WIN | lo,hi | A lo,hi time-window (in hc) scoping the forensic probes; default = the IDR-forensics window 13750000,15090000.一個 lo,hi 時間窗(以 hc 計)限定取證探針;預設 = IDR-forensics 窗 13750000,15090000。 |
8 · Diagnostic probes8 · 診斷探針The forensic toolbox取證工具箱 identical to S1 today今天與 S1 相同
| Flag旗標 | Argument引數 | What it does作用 |
|---|---|---|
--dump-node | <name> / @<id> | Dissect one node: pull-up, gated transistors, channel-end transistors. Raw-id aliases (cpu.#nnnn) do not resolve here — only in test mode.解剖單節點:pull-up、被 gate 的電晶體、channel 端電晶體。raw-id 別名(cpu.#nnnn)在此不解析 —— 只在 test 模式。 |
--dump-module | <name> | Parse <system-def-dir>/<name>.js and print a summary.解析 <system-def-dir>/<name>.js 並印摘要。 |
--dump-system | — | Compose the full nes-001 + cart netlist and print counts + probes.組出完整 nes-001 + cart 網表並印計數 + 探針。 |
--names | <id1,id2,…> | Engine id → name (keeps the name map).引擎 id → 名稱(保留名稱映射)。 |
--watch | <names> | Comma list of node names, printed per frame (pairs with --micro / after --resume).節點名逗號清單,每幀印(配 --micro / --resume 後)。 |
--micro | <path> | Run N frames, dump work RAM $0200-$07FF.跑 N 幀,傾印工作 RAM $0200-$07FF。 |
--micro-frames | <N> | --micro frame count (default 3).--micro 幀數(預設 3)。 |
--trace | <path> | Classic trace-column output.傳統 trace 欄位輸出。 |
--cycles | <N> | --trace cycle count (default 64).--trace 週期數(預設 64)。 |
--bus-trace | <path> | DMC bus microscope ($4013/$4015 + RDY-stall cycles).DMC 匯流排顯微鏡($4013/$4015 + RDY-stall 週期)。 |
--op-probe | <path> <hexaddr> | hc-log the datapath buses when AB hits the address.AB 命中位址時做 hc 級 datapath 匯流排記錄。 |
--rdy-probe | <path> | Per-frame cpu.rdy transition counts.每幀 cpu.rdy 轉換計數。 |
--phase-probe | <path> | Per-hc CPU/PPU clock-phase dump.每 hc CPU/PPU 時鐘相位傾印。 |
--probe2002 | <path> | Trace bus/PPU signals at the next $2002 read after vblank.追蹤 vblank 後下一個 $2002 讀取的訊號。 |
--probe-vbl | <path> | Trace the 2C02 vbl-flag latch through the $2002 read path.追蹤 2C02 vbl 旗標 latch 經 $2002 讀取路徑。 |
--probe-2001 | <path> | Trace $2001 write → bkg_enable → rendering + the dot-339 skip window.追蹤 $2001 寫 → bkg_enable → rendering + dot-339 skip 窗。 |
--probe-dma | <path> | Trace the OAM-DMA address bus + open bus (read_buffer #67).追蹤 OAM-DMA 位址匯流排 + open bus(read_buffer #67)。 |
--ppu-memory-trace | <lo> <hi> | Trace CHR/VRAM callbacks while the CPU PC is in this inclusive hex range.CPU PC 在此 hex 範圍(含端點)內時追蹤 CHR/VRAM callback。 |
--ppu-memory-trace-x | <hex> | Restrict the PPU memory trace to one CPU X value.把 PPU memory trace 限定到單一 CPU X 值。 |
--ac-dump-work | — | Dump AccuracyCoin work/results RAM $0500-$06FF at verdict.判定時傾印 AccuracyCoin 工作/結果 RAM $0500-$06FF。 |
9 · Screen output9 · 畫面輸出Framebuffer dumpsframebuffer 傾印 identical to S1 today今天與 S1 相同
| Flag旗標 | Argument引數 | What it does作用 |
|---|---|---|
--screenshot | <rom> | Run N frames, dump the framebuffer to a PNG.跑 N 幀後把 framebuffer 傾印成 PNG。 |
--frames | <N> | Frame count for --screenshot / --ppu-dump (default 3).--screenshot / --ppu-dump 幀數(預設 3)。 |
--out | <path> | Output PNG path for --screenshot (default screenshot.png).--screenshot 輸出 PNG 路徑(預設 screenshot.png)。 |
--frame-dump | <rom> | Per-frame PNG dump with progress + timing.逐幀 PNG 傾印(含進度 + 計時)。 |
--frame-count | <N> | Number of frames for --frame-dump (default 50).--frame-dump 幀數(預設 50)。 |
--out-dir | <dir> | Output directory for --frame-dump (default frames).--frame-dump 輸出目錄(預設 frames)。 |
--ppu-dump | <rom> | Run N frames, dump palette RAM / VRAM nametable / rendering state / pclk1 samples.跑 N 幀,傾印 palette RAM / VRAM nametable / rendering 狀態 / pclk1 取樣。 |
10 · Common recipes10 · 常用配方Copy-paste command lines可貼上的指令列
Golden checksum (mechanisms OFF — must match S1)黃金驗證(機制關 —— 必須與 S1 相同)
dotnet AprVisual.S1A.dll --benchmark AprVisualBenchMark/roms/full_palette.nes --bench-hc 300000 \
--extra-ram --system-def-dir AprVisualBenchMark/data/system-def
# checksum MUST be 0x794A43ABDF169ADA (benchmark path never loads shims OR mechanisms)S1a mechanism A/B (arm a mechanism, its shims auto-retire)S1a 機制 A/B(武裝機制,對應 shim 自動退役)
M4_EDGE=1 dotnet AprVisual.S1A.dll --test ... # M4 edge-latch replaces DmcLatch + AluLatch
M4_EDGE=1 M4_DL=1 dotnet AprVisual.S1A.dll --test ... # + the DL transparent row ($4016/$4017)
M6X=1 dotnet AprVisual.S1A.dll --test ... # M6xM3 phase table replaces dot-339 + BGSerialIn + even_odd
NO_M2DECAY=1 dotnet AprVisual.S1A.dll --test ... # turn the default-ON M2 decay OFF (restores io_db shim)
M2_CAP=1 dotnet AprVisual.S1A.dll --benchmark ... # physical-capacitance arbitration — CHANGES the checksum by designPowerShell: $env:M4_EDGE=1; dotnet … (set the env var first).PowerShell:$env:M4_EDGE=1; dotnet …(先設環境變數)。
AccuracyCoin flagship run (shared surface — same as S1)AccuracyCoin 掛牌跑(共用面 —— 與 S1 相同)
The
ALEREAD_MUX env is load-bearing and the thing everyone forgets. Without it the ALERead test fails; MUX_HC=13,13,25,44,52 is the only calibration verified to PASS in-suite (it equals the code default). The flagship must carry --max-frames 12000 — the default 900 stops the run early.
ALEREAD_MUX 環境變數是關鍵、也是大家最常忘的。沒有它 ALERead 測試就掛;MUX_HC=13,13,25,44,52 是唯一驗證套內 PASS 的校準(等於 code 預設)。旗艦必帶 --max-frames 12000 —— 預設 900 會提早停。
ALEREAD_MUX=1 MUX_HC=13,13,25,44,52 \
dotnet AprVisual.S1A.dll --test AprAccuracyCoinUnattended/AccuracyCoin.nes --ac-verdict --joypad \
--callback-drain-limit 2000 --reset-hold-extra 1 --pin 2 \
--system-def-dir AprVisualBenchMark/data/system-def --max-frames 12000 \
--snapshot-frames 10 --snapshot-dir out/snaps --progress-frames 600 --progress-dir out/prog
# S1a note: M2 charge-decay is default-ON here; the io_db shim is already retiredShim A/B isolationShim A/B 隔離
# S1a adds five per-shim kill switches over S1 (NO_DMC_SHIM / NO_ALU_SHIM / NO_LXA_SHIM /
# NO_FRAMEIRQ_SHIM / NO_IODECAY_SHIM), on top of the five shared ones:
NO_OB_SHIM=1 NO_DL_SHIM=1 NO_ABORT_SHIM=1 NO_OAMEDGE_SHIM=1 NO_BGS_SHIM=1 \
NO_DMC_SHIM=1 NO_ALU_SHIM=1 NO_LXA_SHIM=1 NO_FRAMEIRQ_SHIM=1 \
dotnet AprVisual.S1A.dll --test ...
# --no-shims kills the shims at once, but NOT the M2/M4/M6X mechanisms (env-gated)
One-runner rule: run only one simulation instance at a time; do not build during a benchmark (the DLL is locked). Every mechanism must keep the golden checksum unchanged while OFF and hold AC 141/141 + the 147-ROM regression while ON.
單 runner 鐵律:同一時間只跑一個模擬實例;benchmark 期間不 build(DLL 鎖)。每個機制關閉時金 checksum 須不變,開啟時須守住 AC 141/141 + 147 顆回歸。
11 · The 147-ROM test battery11 · 147 測試 ROM 實戰Four verdict paths, a controller, and a budget四種判定、手把、與預算 identical to S1 today今天與 S1 相同
Running the nes-test-roms battery is identical to S1 — the four verdict classes (blargg $6000 protocol, screen text, screen CRC), the controller simulation (--joypad + --input), and the budget/timeout flags are the same 71-flag surface. The full cookbook — one copy-paste command per verdict class, controller scripting, and the exit-code / detection=none notes — lives on the S1 page: S1 CLI §11 · The 147-ROM test battery. Just swap AprVisual.S1.dll → AprVisual.S1A.dll.跑 nes-test-roms 電池與 S1 完全相同 —— 四種判定(blargg $6000 協定、畫面文字、畫面 CRC)、手把模擬(--joypad + --input)、預算/timeout 旗標,都是同一組 71 旗標面。完整 cookbook(每種判定一行可貼上指令、手把腳本、exit code / detection=none 說明)在 S1 頁:S1 CLI §11 · 147 測試 ROM 實戰。只要把 AprVisual.S1.dll → AprVisual.S1A.dll。
Why it matters for S1a. The 147-ROM regression is one of the three verification anchors every S1a mechanism must clear — the golden checksum with the mechanism OFF, then AC 141/141 and the 147 sweep with it ON. A mechanism that breaks even one blargg ROM does not ship.
為什麼對 S1a 重要。147 顆回歸是每個 S1a 機制必過的三個驗證錨之一 —— 機制關時金 checksum,機制開時 AC 141/141 和 147 全跑。弄壞任一顆 blargg ROM 的機制不能出貨。