From bc6779c6cc10e61af1cbe2d3aacddb8f94db33b6 Mon Sep 17 00:00:00 2001 From: dimiro1 Date: Thu, 24 Sep 2026 19:51:58 +0200 Subject: [PATCH 1/2] Say where in the frame the machine was touched, and stand on a scanline Three gaps a session of mid-screen raster work found in the headless debugger, easiest first. The REPL's `state` reported the beam position and stopped there. For raster work those are the symptom; loopy's v, t, fine-x and the write latch are what explains them -- a coarse-X off by one tile on exactly one scanline says so in `ppu.v` and nowhere else in the program. The report has carried the same four all along, spelled the same way. `--log-events FILE` is the second, and it is wiring rather than new machinery: `Debugger.setEventSink` already hands out every PPU, audio and mapper write and both interrupts with the beam position each landed on, and nothing but the desktop's Events tab was listening. `EventTracer` writes them down beside `Tracer`, one record a line with the frame, scanline and dot, and `events on|reads|off` does it inside a session. It stops nothing, which is the whole point: a watchpoint on $2006 in a game whose NMI handler writes it forty times a frame is forty stops for one frame's worth of answer, and a trace of the same run is a gigabyte. This is the middle, and `EventLogRunTests` holds a logged run to the unlogged run's frame hash and cycle count. Seven whitespace separated fields on every line, which is why `EventKind` grew an `id()` beside its label: five of the seven labels are two words, so a reader cutting a line up would read the value of a PPU write as the word "write". `run-until-scanline N` is the third, and it is a sibling command rather than a beam term in `break ... if`. A condition stays answerable from a `CPU.State` and a `peek`, which is what its javadoc promises and what keeps it testable without a machine -- and the question raster work actually asks has no address in it at all. And `--headless --help` opens with a map of its own sections, because it is 250 lines and the half people miss is the half below the picture. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 107 +++++- README.md | 3 +- .../github/dimiro1/mynes/debug/Debugger.java | 34 +- .../dimiro1/mynes/debug/EventTracer.java | 324 ++++++++++++++++++ .../mynes/debug/DebuggerEventsTests.java | 83 +---- .../dimiro1/mynes/debug/EventTracerTests.java | 274 +++++++++++++++ .../github/dimiro1/mynes/debug/SplitROM.java | 83 +++++ .../dimiro1/mynes/headless/Headless.java | 18 + .../dimiro1/mynes/headless/Options.java | 67 ++++ .../github/dimiro1/mynes/headless/Repl.java | 171 +++++++++ .../github/dimiro1/mynes/headless/Report.java | 19 + .../dimiro1/mynes/headless/Session.java | 199 ++++++++++- .../mynes/headless/EventLogRunTests.java | 259 ++++++++++++++ .../dimiro1/mynes/headless/OptionsTests.java | 18 + .../dimiro1/mynes/headless/ReplTests.java | 100 ++++++ 15 files changed, 1654 insertions(+), 105 deletions(-) create mode 100644 mynes-core/src/main/java/com/github/dimiro1/mynes/debug/EventTracer.java create mode 100644 mynes-core/src/test/java/com/github/dimiro1/mynes/debug/EventTracerTests.java create mode 100644 mynes-core/src/test/java/com/github/dimiro1/mynes/debug/SplitROM.java create mode 100644 mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/EventLogRunTests.java diff --git a/CLAUDE.md b/CLAUDE.md index 4a1b0ef..ec01824 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,7 +26,10 @@ The jar is under `mynes-desktop/` because that is the module with a main class i still one file and still the whole emulator: the fat jar flattens all three modules and their dependencies into it. -`java -jar $JAR --headless --help` lists every option. Maven can run it too -- +`java -jar $JAR --headless --help` lists every option. **It is long, and the half people miss is +the half below the picture**, so it opens with a map of its own sections -- which is worth reading +before reimplementing something that is already a flag a hundred and fifty lines further down. +Maven can run it too -- `mvn -q compile exec:exec@headless -Dmynes.args="--rom ROM.nes --frames 300"` -- but it costs a couple of seconds a run against the jar's third of one, so build the jar for anything iterative. `mvn -q compile exec:exec` opens the window, which a cloud workspace has nowhere to put. Neither @@ -87,6 +90,7 @@ frame boundary is too coarse for: ``` step [N] advance N instructions rather than N frames +run-until-scanline N advance until the beam next reaches scanline N disasm [ADDR] [COUNT] disassemble, from the PC by default break ADDR [if COND] stop before the instruction at ADDR, where COND holds unbreak ADDR forget that one @@ -135,6 +139,43 @@ DMC's sample fetches are the processor reading, so they are invisible to a read first `step` is the reset sequence**, which runs no instruction: it leaves the CPU standing on the first one rather than past it. +### Standing part way down a frame + +`run-until-scanline N` is the third of the `run-until` family, and the only one that stops +*somewhere* rather than when something happens: the other two watch the picture and this watches the +beam. What it is for is reading the chip's own state mid-frame -- `run-until-scanline 167` then +`state`, where **`ppu.v`, `ppu.t`, `ppu.fineX` and `ppu.writeLatch`** are, beside the scanline and +the dot. Those four are the answer and the beam position is the symptom: `v`'s low five bits are the +coarse X the next tile comes from, so a background that is one tile out on exactly one scanline says +so there and nowhere else in the program. The report has had the same four under `ppu` all along. + +**It stops between instructions, so it lands a few dots into the line rather than on dot 0.** That +is the price of everything else still meaning something where it stops -- a machine halted +mid-instruction has no program counter a disassembly can start from. Seven CPU cycles is the usual +overshoot, twenty-one dots; a step that swallows an OAM transfer is five hundred, which is the one +case it overshoots the line altogether, so **read the `scanline` it came back with** rather than +assuming. There is no maximum, unlike the other two: the PPU is clocked whatever the program does, +so a line the region has arrives inside a frame -- and a line it has not, `run-until-scanline 300` +on NTSC, is refused rather than waited for. Asked for the line it is already on it goes round, +which is what makes calling it in a loop a way of watching one line over successive frames. + +**A watchpoint is usually the better question, and it is worth knowing which one is being asked.** +"Where does this write land" is `watch $2005` and needs no line guessed in advance; this asks "what +does the machine look like at line 167", which nothing else here can. They compose: a breakpoint +that fires first stops it and is reported, so both can be set and the answer is which happened. + +```sh +printf 'run 60\nrun-until-scanline 167\nstate\nquit\n' \ + | java -jar $JAR --headless --rom ROM.nes --interactive +``` + +**Beam terms are deliberately not in a `break` condition.** `break $C000 if scanline >= 167` reads +well and is not expressible, and the reason is the one `Condition`'s own javadoc gives: a condition +is answerable from a `CPU.State` and a `peek`, which is what keeps it cheap and what makes it +testable without a machine. The escape hatch is `run-until-scanline 167`, then `break $C000`, then +`run` -- and the question raster work actually asks has no address in it at all, which is what this +command is. + ### Writing down every instruction `trace PATH [LINES]` logs one line per instruction in nestest's format, `trace off` stops, and a bare @@ -162,6 +203,62 @@ three times its cycle count -- so a cross-emulator diff belongs on the CPU colum exactly. `Tracer` is where all of it lives, and the window has the same thing under **Debug > Start Trace...** +### Writing down where in the frame the machine was touched + +The other half of that trade, and the one raster work wants. `--log-events FILE` writes down every +PPU, audio and mapper register write and both interrupts -- the accesses that are the machine being +*told* something -- one record a line, with the frame, the scanline and the dot each landed on: + +``` +# frame line dot event address value pc + 64 23 82 ppu-write $2005 $00 $80FF + 64 241 19 nmi $FFFA -- $8057 +``` + +**Nothing is stopped and the machine does not slow down**, which is the whole point and is what +separates it from a watchpoint. `Debugger.setEventSink` rides on hooks `MMU` already carries and is +deliberately outside `Debugger.isArmed()`, so a game being logged is a game running at full speed -- +which it has to be, since which line a game writes `$2005` on is a question about a main loop that +is finishing on time. A `watch $2006` in a game whose NMI handler writes it forty times a frame is +forty stops and forty resumes for one frame's worth of answer; a `trace` of the same 200 frames is a +gigabyte. This is the middle, and it is a few hundred records a frame. + +Which turns "where does this write land, on every frame, for two hundred frames" from a stop and a +`state` and a `run` per write into one run: + +```sh +java -jar $JAR --headless --rom ROM.nes --frames 200 --input 60/40x3:start --log-events ev.log +grep '\$2005' ev.log # every split, every frame, with the line it landed on +``` + +**Seven whitespace separated fields on every line, whatever happened**, which is why the event is +written as `Debugger.EventKind.id()` -- `ppu-write`, `mapper-write`, `nmi` -- rather than as the +label the window's tooltips use: five of the seven are two words, and a reader cutting the line up +would read the value of a PPU write as the word "write". `awk '$2 == 167 {print $5}'` works. The +single `#` header is the only line that is not a record, is marked the way the REPL marks a comment +and does not count against the limit. An interrupt has `--` where a byte would be, since a zero +there is a byte somebody could believe. + +**Writes always, reads only when asked.** `--log-reads` adds the `$2002` and `$4016` polls, which +are worth seeing exactly when the question is why a game is waiting -- and which are the one part of +this a machine can feel, since recording reads puts a hook on the line every instruction fetch comes +past. It is refused without `--log-events`, for the reason `--filter none=low` is. Work RAM and +cartridge RAM are never in it either way: a game writes those thousands of times a frame and all of +it is the game thinking, which is what `watch` and `read` are for. + +`events on PATH [LINES]`, `events reads PATH [LINES]` and `events off` do it inside an interactive +session, and a bare `events` says how far it has got -- the shape of `trace`, since it is the same +kind of thing. The limit is the session's because a session is open ended; a run of a schedule is +already bounded by `--frames`. + +**It is not on the comparability checklist**, for the reason the video filters are not: a logged run +and an unlogged one are byte for byte the same run, which `EventLogRunTests` holds to the frame hash +and the cycle count. `eventLog` in the report says what was written, always present with explicit +nulls -- and `eventLog.records` is the number worth reading, since a log that came back empty is a +question about what was expected rather than a file worth opening. `EventTracer` in core is where it +lives, beside `Tracer`, and the window draws the same events as a raster under **Debug > Control +Panel**'s Events tab. + ### Failing on purpose `--expect-not-blank`, `--expect-audio` and `--expect-motion N` make a run exit 4 when they do not @@ -1209,9 +1306,11 @@ mynes-core/ depends on nothing controllers mynes/mappers/ the twelve boards: 0 to 4, 7, 9 to 11, 66, 71, and 155 on MMC1's own class mynes/state/ save states, battery .sav files, and .mnm session recordings - mynes/debug/ the disassembler, the breakpoints and their conditions, the tracer, and - the meter that says how much of its frame the program used and which - bytes of memory it has -- all shared by the window and the REPL + mynes/debug/ the disassembler, the breakpoints and their conditions, the two logs -- + every instruction, and every register write with the beam position it + landed on -- and the meter that says how much of its frame the program + used and which bytes of memory it has; all shared by the window and the + REPL mynes/cheat/ Game Genie codes, and the device MMU asks on every read of PRG ROM mynes/video/ colour indices to pixels: the overscan crop, the frame renderer, the NTSC filter that decodes the signal instead of reading a palette, and the tube diff --git a/README.md b/README.md index e8a3fe9..2eec199 100644 --- a/README.md +++ b/README.md @@ -293,7 +293,8 @@ hash, colour counts, how many frames showed motion. `--expect-not-blank`, `--exp deterministic, a frame hash makes a fair regression test. There is also `--interactive`, a JSON-per-line REPL with the whole debugger in it: breakpoints, -watchpoints, stepping, disassembly, tracing, rewind, movies. +watchpoints, stepping, disassembly, tracing, rewind, movies, and a log of every register write with +the scanline it landed on. `--headless --help` lists every option, and [CLAUDE.md](CLAUDE.md) covers it all in detail. That file is written for coding agents, but it is just as accurate for people. diff --git a/mynes-core/src/main/java/com/github/dimiro1/mynes/debug/Debugger.java b/mynes-core/src/main/java/com/github/dimiro1/mynes/debug/Debugger.java index 7cb793d..6f80b75 100644 --- a/mynes-core/src/main/java/com/github/dimiro1/mynes/debug/Debugger.java +++ b/mynes-core/src/main/java/com/github/dimiro1/mynes/debug/Debugger.java @@ -150,20 +150,36 @@ public record Stop(Reason reason, int pc, Access access, int address, int value, * program being fetched, and neither is a thing the machine did. */ public enum EventKind { - PPU_READ("PPU read"), - PPU_WRITE("PPU write"), - AUDIO_READ("audio read"), - AUDIO_WRITE("audio write"), - CARTRIDGE_WRITE("mapper write"), - NMI("NMI"), - IRQ("IRQ"); - + PPU_READ("ppu-read", "PPU read"), + PPU_WRITE("ppu-write", "PPU write"), + AUDIO_READ("audio-read", "audio read"), + AUDIO_WRITE("audio-write", "audio write"), + CARTRIDGE_WRITE("mapper-write", "mapper write"), + NMI("nmi", "NMI"), + IRQ("irq", "IRQ"); + + private final String id; private final String label; - EventKind(final String label) { + EventKind(final String id, final String label) { + this.id = id; this.label = label; } + /** + * One word, for a file. The same split the regions and the video filters make, and here it + * earns itself twice over: a log written with the labels below would put two words in one + * column for five of the seven, so a line of it would have six fields or seven depending on + * what happened -- and a reader that cut it up on whitespace would read the value of a PPU + * write as the word "write". + */ + public String id() { + return id; + } + + /** + * How it is spelled for somebody reading a tooltip. + */ public String label() { return label; } diff --git a/mynes-core/src/main/java/com/github/dimiro1/mynes/debug/EventTracer.java b/mynes-core/src/main/java/com/github/dimiro1/mynes/debug/EventTracer.java new file mode 100644 index 0000000..3ebc4b4 --- /dev/null +++ b/mynes-core/src/main/java/com/github/dimiro1/mynes/debug/EventTracer.java @@ -0,0 +1,324 @@ +package com.github.dimiro1.mynes.debug; + +import com.github.dimiro1.mynes.PPU; + +import java.io.BufferedWriter; +import java.io.Closeable; +import java.io.IOException; +import java.io.OutputStreamWriter; +import java.io.Writer; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; + +/** + * Everything the machine did to its hardware, written down with the beam position it did it at. + *

+ * {@link Tracer}'s sibling, and the other half of the same trade. That one writes every instruction + * and answers "what did the program do"; this one writes only the accesses that are the machine + * being told something -- the PPU registers, the sound chip, the mapper and the two + * interrupts -- and answers where in the frame each one landed. Which is a question nothing + * else here can answer: a {@code watch} stops the machine, so a write the NMI handler makes dozens + * of times a frame costs a stop and a resume for each one, and a trace of the same 200 frames is a + * gigabyte to grep. + *

+ * This does not arm the machine. {@link Debugger#setEventSink} rides on hooks the bus + * already carries, so a game being logged is a game running at full speed -- which it has to be, + * since which scanline a game writes $2005 on is a question about a game whose main loop is + * finishing on time. + * + *

+ * # frame line  dot   event         address value   pc
+ *      64   23   82   ppu-write     $2005     $00   $80FF
+ *      64  241   19   nmi           $FFFA      --   $8057
+ * 
+ * + * Fixed columns and one record a line, so the file reads as a table -- and seven whitespace + * separated fields on every line whatever happened, which is why the event is written as + * {@link Debugger.EventKind#id()} rather than as its label: {@code grep '\$2005'} and + * {@code awk '$2 == 167 {print $5}'} both work on it. The single {@code #} header is the only line + * that is not a record, and is marked the way the REPL's own scripts mark a comment. A number + * wider than its column pushes the rest of the line right rather than being cut, which keeps a + * long run honest at the cost of its alignment. + *

+ * Three columns are worth a word. The frame is not in what the sink is handed and is asked + * of the PPU here, because "the same line every frame" and "one frame in six" are the two answers + * this file exists to tell apart. The dot is good to within two and no better: the machine + * is clocked a CPU cycle at a time and three dots go past in one, so it is the last of the three + * the cycle covered. And the pc is past the instruction that made the access, by however + * long that instruction was, since the operand bytes have already been fetched -- it is an + * orientation rather than an answer, and {@code watch} is what answers exactly. + *

+ * Everything here happens on the thread clocking the machine, which is the thread the sink is + * called on, and nothing here synchronises. + */ +public final class EventTracer implements Debugger.EventSink, Closeable { + /** + * How much to hold before touching the disk. The same as {@link Tracer}'s and for the same + * reason, even though this writes a hundredth as much: a program waiting out the picture with + * reads switched on polls $2002 every seven cycles, and that is the case worth sizing for. + */ + private static final int BUFFER = 1 << 16; + + /** + * Where each column ends, for the three that are right aligned, and where it starts for the + * three that are not. One set of constants for the header and the records both, so the two + * cannot drift apart. + */ + private static final int FRAME_END = 7; + private static final int LINE_END = 12; + private static final int DOT_END = 17; + private static final int EVENT_START = 20; + private static final int ADDRESS_START = 34; + private static final int VALUE_END = 47; + private static final int PC_START = 50; + + /** + * What an interrupt has instead of a byte. An interrupt reads and writes nothing, and a zero + * there would be a byte somebody could believe. + */ + private static final String NO_VALUE = "--"; + + private static final char[] HEX = "0123456789ABCDEF".toCharArray(); + + private final Writer out; + private final PPU ppu; + + /** + * How many records to write before going quiet, or 0 for as many as it takes. + */ + private final long limit; + + /** + * Reused rather than allocated per event, which is safe for the reason nothing here + * synchronises: one thread clocks the machine and this is only ever called from it. + */ + private final StringBuilder line = new StringBuilder(64); + + private long records; + private boolean full; + private boolean closed; + + /** + * The first failure writing, or null. Kept rather than thrown, for {@link Tracer}'s reason: + * {@link #onEvent} cannot throw through a bus write, and a disk that filled up half way through + * is worth telling somebody about at the end rather than losing. + */ + private IOException failure; + + private EventTracer(final Writer out, final PPU ppu, final long limit) { + this.out = out; + this.ppu = ppu; + this.limit = limit; + } + + /** + * Opens one on a file, replacing whatever was there, and writes the header. + * + * @param path where to write it. Parent directories are made. + * @param ppu the machine's PPU, for the frame column -- which is the column that turns a pile + * of writes into "every frame, on line 167". + * @param limit how many records to write before going quiet, or 0 for no limit. One that has + * reached its limit closes the file and answers {@link #isFull()}; it does not + * take itself off the debugger, because whoever put it there is the only one who + * knows the debugger exists. + */ + public static EventTracer to(final Path path, final PPU ppu, final long limit) + throws IOException { + + var parent = path.getParent(); + + if (parent != null) { + Files.createDirectories(parent); + } + + var tracer = new EventTracer( + new BufferedWriter( + new OutputStreamWriter( + Files.newOutputStream(path), StandardCharsets.US_ASCII), + BUFFER), + ppu, + limit); + + tracer.header(); + + return tracer; + } + + @Override + public void onEvent( + final Debugger.EventKind kind, + final int address, + final int value, + final int scanline, + final int dot, + final int pc + ) { + if (closed) { + return; + } + + line.setLength(0); + rightTo(Long.toString(ppu.getFrame()), FRAME_END); + rightTo(Integer.toString(scanline), LINE_END); + rightTo(Integer.toString(dot), DOT_END); + leftAt(kind.id(), EVENT_START); + pad(ADDRESS_START); + word(address); + rightTo(value < 0 ? NO_VALUE : byteHex(value), VALUE_END); + pad(PC_START); + word(pc); + line.append('\n'); + + write(); + } + + /** + * How many records have been written. + */ + public long records() { + return records; + } + + /** + * Whether it wrote all it was asked for and stopped. The file is closed by then, so what was + * written is on disk. + */ + public boolean isFull() { + return full; + } + + /** + * The first failure writing, or null if there was none. + */ + public IOException failure() { + return failure; + } + + /** + * Closes the file. Doing it twice is not an error, which is what lets a session close one that + * already stopped itself at its limit. + */ + @Override + public void close() throws IOException { + if (closed) { + return; + } + + closed = true; + out.close(); + } + + // ================================================================================== internals + + /** + * The one line in the file that is not a record, marked as a comment so that anything reading + * the rest can drop it on the character rather than on the line number. + */ + private void header() { + line.setLength(0); + line.append('#'); + rightTo("frame", FRAME_END); + rightTo("line", LINE_END); + rightTo("dot", DOT_END); + leftAt("event", EVENT_START); + leftAt("address", ADDRESS_START); + rightTo("value", VALUE_END); + leftAt("pc", PC_START); + line.append('\n'); + + // Through append rather than through write, because the header is furniture rather than + // something anybody asked for: it is not a record and it does not count against the limit. + // Counting it would make "events on x.log 1" a file with a heading and nothing in it. + append(); + } + + /** + * One record, counted, and the file closed if that was the last one asked for. + */ + private void write() { + if (!append()) { + return; + } + + records++; + + if (limit > 0 && records >= limit) { + full = true; + + try { + close(); + } catch (IOException e) { + remember(e); + } + } + } + + /** + * Puts the line on the disk. False if it did not get there, after which nothing more will be + * written. + */ + private boolean append() { + try { + out.append(line); + + return true; + } catch (IOException e) { + remember(e); + + return false; + } + } + + /** + * Quietly, and once: a disk that has filled up will fill up again on the next write, and a + * million copies of one message is not a better report than one. + */ + private void remember(final IOException e) { + if (failure == null) { + failure = e; + } + + closed = true; + + try { + out.close(); + } catch (IOException ignored) { + // Already failing, and the first exception is the one worth keeping. + } + } + + private void rightTo(final String text, final int column) { + pad(column - text.length()); + line.append(text); + } + + private void leftAt(final String text, final int column) { + pad(column); + line.append(text); + } + + private void pad(final int to) { + while (line.length() < to) { + line.append(' '); + } + } + + private void word(final int value) { + line.append('$') + .append(HEX[(value >> 12) & 0x0F]) + .append(HEX[(value >> 8) & 0x0F]) + .append(HEX[(value >> 4) & 0x0F]) + .append(HEX[value & 0x0F]); + } + + /** + * A byte, as the value column spells it. A string rather than appended in place like the + * address beside it, because the column is right aligned and so has to know how wide it is + * before it starts -- and because a few hundred of these a frame is nothing next to the write + * that follows them. + */ + private static String byteHex(final int value) { + return "$" + HEX[(value >> 4) & 0x0F] + HEX[value & 0x0F]; + } +} diff --git a/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/DebuggerEventsTests.java b/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/DebuggerEventsTests.java index 2158b15..b2cd620 100644 --- a/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/DebuggerEventsTests.java +++ b/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/DebuggerEventsTests.java @@ -49,7 +49,7 @@ private record Event(Debugger.EventKind kind, int address, int value, int scanli @BeforeAll static void runTheSplitROM() { - fromTheSplitROM = run(splitROM(), 10, false); + fromTheSplitROM = run(SplitROM.image(), 10, false); } @Test @@ -122,7 +122,7 @@ void nothingIsAReadUnlessReadsWereAskedFor() { */ @Test void anInstructionFetchIsNeverAnEventEvenWithReadsOn() { - var events = run(splitROM(), 6, true); + var events = run(SplitROM.image(), 6, true); assertTrue( events.stream().anyMatch(event -> event.kind().isRead()), @@ -146,7 +146,7 @@ void anInstructionFetchIsNeverAnEventEvenWithReadsOn() { */ @Test void recordingDoesNotArmTheMachine() { - var nes = new NES(Cart.load(splitROM(), "events.nes")); + var nes = new NES(Cart.load(SplitROM.image(), "events.nes")); var debugger = new Debugger(); debugger.attach(nes); @@ -157,7 +157,7 @@ void recordingDoesNotArmTheMachine() { @Test void takingTheSinkOffStopsTheRecording() { - var nes = new NES(Cart.load(splitROM(), "events.nes")); + var nes = new NES(Cart.load(SplitROM.image(), "events.nes")); var debugger = new Debugger(); var seen = new ArrayList(); @@ -182,7 +182,7 @@ void takingTheSinkOffStopsTheRecording() { */ @Test void aWatchpointAndARecordingDoNotUnhookEachOther() { - var nes = new NES(Cart.load(splitROM(), "events.nes")); + var nes = new NES(Cart.load(SplitROM.image(), "events.nes")); var debugger = new Debugger(); var seen = new ArrayList(); @@ -224,77 +224,4 @@ private static List run(final byte[] rom, final int frames, final boolean // warm up, and what they hold is a handful of $2002 polls rather than anything it does. return seen.stream().filter(event -> event.scanline() >= 0).toList(); } - - /** - * A cartridge that splits the screen, assembled here. - *

- * Its NMI does nothing but raise a flag; the main loop waits for it, counts out about 15400 - * cycles -- 135 scanlines, so a little over a hundred lines into the next picture -- and writes - * the scroll twice, which is what a game does to put a status bar over a scrolling level. Then - * it writes to work RAM, which is there to be ignored. - *

-     * C000  SEI / CLD / LDX #$FF / TXS
-     *       LDA #$00 / STA $2001 / STA $01     rendering off, the NMI's flag cleared
-     * C00C  BIT $2002 / BPL -5                 two vblanks, which is how one waits for the PPU
-     * C011  BIT $2002 / BPL -5
-     *       LDA #$80 / STA $2000               and only then the NMI
-     * C01B  LDA $01 / BEQ -4             loop: wait for it
-     *       LDA #$00 / STA $01
-     * C023  LDY #$0C / LDX #$00 / DEX / BNE -3 / DEY / BNE -8
-     *       LDA #$40 / STA $2005 / STA $2005   the split
-     *       STA $0200                          and one write to work RAM, to be ignored
-     * C038  JMP $C01B
-     *
-     * C100  INC $01 / RTI
-     * 
- * The interrupt rather than a $2002 poll for the same reason the pads cartridge uses one: a - * program that polls the flag can have a read land on the dot it is raised, lose that vblank - * and slip a frame, which would put the split on a different line every so often. - */ - private static byte[] splitROM() { - var program = new int[]{ - 0x78, 0xD8, 0xA2, 0xFF, 0x9A, - 0xA9, 0x00, 0x8D, 0x01, 0x20, - 0x85, 0x01, - 0x2C, 0x02, 0x20, 0x10, 0xFB, - 0x2C, 0x02, 0x20, 0x10, 0xFB, - 0xA9, 0x80, 0x8D, 0x00, 0x20, - 0xA5, 0x01, 0xF0, 0xFC, - 0xA9, 0x00, 0x85, 0x01, - 0xA0, 0x0C, - 0xA2, 0x00, - 0xCA, 0xD0, 0xFD, - 0x88, 0xD0, 0xF8, - 0xA9, 0x40, 0x8D, 0x05, 0x20, 0x8D, 0x05, 0x20, - 0x8D, 0x00, 0x02, - 0x4C, 0x1B, 0xC0, - }; - - var handler = new int[]{0xE6, 0x01, 0x40}; - var image = new byte[16 + 0x4000 + 0x2000]; - - image[0] = 'N'; - image[1] = 'E'; - image[2] = 'S'; - image[3] = 0x1A; - image[4] = 1; - image[5] = 1; - - for (var i = 0; i < program.length; i++) { - image[16 + i] = (byte) program[i]; - } - - for (var i = 0; i < handler.length; i++) { - image[16 + 0x0100 + i] = (byte) handler[i]; - } - - // One 16KB bank is mirrored into both halves of $8000-$FFFF, so the code above is - // assembled for $C000 and the two vectors point into it. - image[16 + 0x3FFA] = 0x00; - image[16 + 0x3FFB] = (byte) 0xC1; - image[16 + 0x3FFC] = 0x00; - image[16 + 0x3FFD] = (byte) 0xC0; - - return image; - } } diff --git a/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/EventTracerTests.java b/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/EventTracerTests.java new file mode 100644 index 0000000..482a5f4 --- /dev/null +++ b/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/EventTracerTests.java @@ -0,0 +1,274 @@ +package com.github.dimiro1.mynes.debug; + +import com.github.dimiro1.mynes.Cart; +import com.github.dimiro1.mynes.NES; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * The log of what the machine was told, and where in the frame it was told it. + *

+ * Two things are worth holding this to. The first is that it says the same thing + * {@link DebuggerEventsTests} already checks the sink says -- the split lands on one scanline, on + * every frame -- since a writer that lost the beam position would be a file of writes with the only + * column anybody wanted missing. The second is the shape: a log is read by grep and awk far + * more often than by eye, so seven fields on every line whatever happened is a promise rather than + * a courtesy. + */ +class EventTracerTests { + /** + * Where the PPU raises its interrupt, which is where the split ROM's NMI is served. + */ + private static final int VBLANK_LINE = 241; + + @TempDir + private Path directory; + + private NES machine() { + return new NES(Cart.load(SplitROM.image(), "events.nes")); + } + + /** + * Runs the split ROM with a log attached and hands back the file's records, header dropped. + */ + private List log(final int frames, final boolean reads, final long limit) + throws IOException { + + var path = records(frames, reads, limit); + + return Files.readAllLines(path).stream().filter(line -> !line.startsWith("#")).toList(); + } + + /** + * A record cut into its fields. Trimmed first, since every column but the event and the + * addresses is right aligned and so every line starts with the padding -- which is what awk + * skips for itself and {@code String.split} hands back as an empty first field. + */ + private static String[] fields(final String record) { + return record.trim().split("\\s+"); + } + + private Path records(final int frames, final boolean reads, final long limit) + throws IOException { + + var nes = machine(); + var debugger = new Debugger(); + var path = directory.resolve("events.log"); + + debugger.attach(nes); + + try (var tracer = EventTracer.to(path, nes.getPPU(), limit)) { + debugger.setEventSink(tracer, reads); + + for (var frame = 0; frame < frames; frame++) { + var was = nes.getPPU().getFrame(); + + while (nes.getPPU().getFrame() == was) { + nes.tick(); + } + } + + debugger.setEventSink(null, false); + } + + return path; + } + + @Test + void theSplitIsWrittenDownOnTheScanlineItHappenedOn() throws Exception { + var splits = log(10, false, 0).stream() + .filter(line -> line.contains("$2005")) + .toList(); + + assertFalse(splits.isEmpty(), "the cartridge writes $2005 twice a frame"); + + var lines = splits.stream().map(line -> fields(line)[1]).distinct().toList(); + + assertEquals(1, lines.size(), "and on the same line every frame, not " + lines); + } + + /** + * The column that is not in what the sink is handed, and the one that turns a pile of writes + * into "every frame, on line 167". A log with it stuck would say the same thing as one taken + * over a single frame. + */ + @Test + void theFrameColumnCountsFrames() throws Exception { + var frames = log(10, false, 0).stream() + .map(line -> Long.parseLong(fields(line)[0])) + .distinct() + .toList(); + + assertTrue(frames.size() > 5, "ten frames of a game that writes every frame, not " + frames); + + for (var i = 1; i < frames.size(); i++) { + assertTrue( + frames.get(i) > frames.get(i - 1), + "written in the order they happened, not " + frames); + } + } + + /** + * The promise the whole format rests on. Five of the seven kinds are two words when they are + * spelled for a person, so a line written with the labels would have six fields or seven + * depending on what happened -- and {@code awk '{print $6}'} would read the value of a PPU + * write as the word "write". + */ + @Test + void everyRecordHasSevenFieldsWhicheverKindItIs() throws Exception { + var records = log(10, true, 0); + var kinds = records.stream().map(line -> fields(line)[3]).distinct().sorted().toList(); + + assertTrue(kinds.contains("ppu-write"), "the split, in " + kinds); + assertTrue(kinds.contains("ppu-read"), "the $2002 polls, in " + kinds); + assertTrue(kinds.contains("nmi"), "and the interrupt, in " + kinds); + + for (var record : records) { + assertEquals(7, fields(record).length, record); + } + } + + /** + * An interrupt reads and writes nothing, and a zero in the byte column would be a byte somebody + * could believe. + */ + @Test + void anInterruptHasDashesWhereAByteWouldBe() throws Exception { + var interrupts = log(10, false, 0).stream() + .filter(line -> fields(line)[3].equals("nmi")) + .toList(); + + assertFalse(interrupts.isEmpty(), "the cartridge switches the NMI on and leaves it on"); + + for (var interrupt : interrupts) { + var fields = fields(interrupt); + + assertEquals(String.valueOf(VBLANK_LINE), fields[1], interrupt); + assertEquals("$FFFA", fields[4], "and names its own vector"); + assertEquals("--", fields[5], "and has no byte"); + } + } + + /** + * The header is furniture, so it is marked as a comment and does not count against the limit -- + * a log asked for ten records that wrote nine and a heading would be off by one in the one + * number a caller checks. + */ + @Test + void theHeaderIsACommentAndIsNotARecord() throws Exception { + var path = records(10, false, 10); + var all = Files.readAllLines(path); + + assertTrue(all.get(0).startsWith("#"), all.get(0)); + assertEquals(11, all.size(), "ten records and the heading"); + + for (var i = 1; i < all.size(); i++) { + assertFalse(all.get(i).startsWith("#"), "only the first line is a comment"); + } + } + + /** + * The edge the header makes: a heading counted against the limit would turn a log asked for one + * record into a file with a heading and nothing in it. + */ + @Test + void aLimitOfOneStillWritesOneRecord() throws Exception { + var all = Files.readAllLines(records(10, false, 1)); + + assertEquals(2, all.size(), "the heading and the one record"); + assertFalse(all.get(1).startsWith("#")); + } + + @Test + void aLogStopsAtItsLimitAndSaysSo() throws Exception { + var nes = machine(); + var debugger = new Debugger(); + var path = directory.resolve("short.log"); + + debugger.attach(nes); + + var tracer = EventTracer.to(path, nes.getPPU(), 5); + + debugger.setEventSink(tracer, false); + + // Ten frames, which is three times the five records asked for: the cartridge makes an + // interrupt and two scroll writes a frame once it is going. + for (var frame = 0; frame < 10; frame++) { + var was = nes.getPPU().getFrame(); + + while (nes.getPPU().getFrame() == was) { + nes.tick(); + } + } + + assertTrue(tracer.isFull()); + assertEquals(5, tracer.records()); + assertNull(tracer.failure(), "nothing went wrong; it simply wrote all it was asked for"); + + // Closed itself, so what it wrote is on disk without anybody having to stop it -- and + // closing it again is not an error, which is what lets a session close one either way. + assertEquals(6, Files.readAllLines(path).size()); + tracer.close(); + + debugger.setEventSink(null, false); + } + + /** + * The whole reason this exists rather than a watchpoint. Everything else the debugger watches + * costs the driver its fast loop; this rides on hooks the bus already carries, so the game + * being logged is a game running normally -- which it has to be, since where a split lands is a + * question about a main loop that is finishing on time. + */ + @Test + void loggingDoesNotArmTheMachine() throws Exception { + var nes = machine(); + var debugger = new Debugger(); + + debugger.attach(nes); + + try (var tracer = EventTracer.to(directory.resolve("armed.log"), nes.getPPU(), 0)) { + debugger.setEventSink(tracer, true); + + assertFalse(debugger.isArmed(), "a log is not a reason to stop anywhere"); + + debugger.setEventSink(null, false); + } + } + + /** + * Work RAM is the game thinking rather than the machine being told anything, and the program + * writes $0200 on every pass to say so. + */ + @Test + void nothingBelowTheHardwareIsWrittenDown() throws Exception { + for (var record : log(10, false, 0)) { + var address = Integer.parseInt(fields(record)[4].substring(1), 16); + + assertTrue(address >= 0x2000, record); + } + } + + /** + * Two runs of the same cartridge produce the same file, which is the claim the rest of the + * headless mode rests on and the reason a log is worth diffing at all. + */ + @Test + void twoRunsWriteTheSameFile() throws Exception { + var first = String.join("\n", log(10, true, 0)); + var second = String.join("\n", log(10, true, 0)); + + assertEquals(first, second); + assertNotEquals("", first); + } +} diff --git a/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/SplitROM.java b/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/SplitROM.java new file mode 100644 index 0000000..cc73591 --- /dev/null +++ b/mynes-core/src/test/java/com/github/dimiro1/mynes/debug/SplitROM.java @@ -0,0 +1,83 @@ +package com.github.dimiro1.mynes.debug; + +/** + * A cartridge that splits the screen, assembled here. + *

+ * Its own class rather than a method on one test, because two of them want it and it is the same + * demonstration for both: the smallest cartridge that has an answer to "where in the frame did + * that happen". + *

+ * Its NMI does nothing but raise a flag; the main loop waits for it, counts out about 15400 + * cycles -- 135 scanlines, so a little over a hundred lines into the next picture -- and writes + * the scroll twice, which is what a game does to put a status bar over a scrolling level. Then + * it writes to work RAM, which is there to be ignored. + *

+ * C000  SEI / CLD / LDX #$FF / TXS
+ *       LDA #$00 / STA $2001 / STA $01     rendering off, the NMI's flag cleared
+ * C00C  BIT $2002 / BPL -5                 two vblanks, which is how one waits for the PPU
+ * C011  BIT $2002 / BPL -5
+ *       LDA #$80 / STA $2000               and only then the NMI
+ * C01B  LDA $01 / BEQ -4             loop: wait for it
+ *       LDA #$00 / STA $01
+ * C023  LDY #$0C / LDX #$00 / DEX / BNE -3 / DEY / BNE -8
+ *       LDA #$40 / STA $2005 / STA $2005   the split
+ *       STA $0200                          and one write to work RAM, to be ignored
+ * C038  JMP $C01B
+ *
+ * C100  INC $01 / RTI
+ * 
+ * The interrupt rather than a $2002 poll for the same reason the pads cartridge uses one: a + * program that polls the flag can have a read land on the dot it is raised, lose that vblank + * and slip a frame, which would put the split on a different line every so often. + */ +final class SplitROM { + private SplitROM() { + } + + static byte[] image() { + var program = new int[]{ + 0x78, 0xD8, 0xA2, 0xFF, 0x9A, + 0xA9, 0x00, 0x8D, 0x01, 0x20, + 0x85, 0x01, + 0x2C, 0x02, 0x20, 0x10, 0xFB, + 0x2C, 0x02, 0x20, 0x10, 0xFB, + 0xA9, 0x80, 0x8D, 0x00, 0x20, + 0xA5, 0x01, 0xF0, 0xFC, + 0xA9, 0x00, 0x85, 0x01, + 0xA0, 0x0C, + 0xA2, 0x00, + 0xCA, 0xD0, 0xFD, + 0x88, 0xD0, 0xF8, + 0xA9, 0x40, 0x8D, 0x05, 0x20, 0x8D, 0x05, 0x20, + 0x8D, 0x00, 0x02, + 0x4C, 0x1B, 0xC0, + }; + + var handler = new int[]{0xE6, 0x01, 0x40}; + var image = new byte[16 + 0x4000 + 0x2000]; + + image[0] = 'N'; + image[1] = 'E'; + image[2] = 'S'; + image[3] = 0x1A; + image[4] = 1; + image[5] = 1; + + for (var i = 0; i < program.length; i++) { + image[16 + i] = (byte) program[i]; + } + + for (var i = 0; i < handler.length; i++) { + image[16 + 0x0100 + i] = (byte) handler[i]; + } + + // One 16KB bank is mirrored into both halves of $8000-$FFFF, so the code above is + // assembled for $C000 and the two vectors point into it. + image[16 + 0x3FFA] = 0x00; + image[16 + 0x3FFB] = (byte) 0xC1; + image[16 + 0x3FFC] = 0x00; + image[16 + 0x3FFD] = (byte) 0xC0; + + return image; + } +} diff --git a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Headless.java b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Headless.java index 06795b8..b2efe9a 100644 --- a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Headless.java +++ b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Headless.java @@ -301,6 +301,17 @@ private static int runCartridge(final Options options) throws IOException { session.startRecording(options.loadState() == null && options.sramIn() == null); } + // Beside the recorder rather than with the hacks above, because it is the same kind of + // thing: something watching a run rather than something the run depends on. It does not + // arm the machine and costs it nothing, which is why it is safe to have on for a run + // that is also being measured. + if (options.logEvents() != null) { + session.startEventLog(options.logEvents(), options.logReads(), 0); + logger.log(Level.INFO, "writing down what the machine is told, to " + + options.logEvents() + + (options.logReads() ? ", reads included" : "")); + } + var outcome = options.interactive() ? interactive(options, session) : oneShot(options, session, frames, movie); @@ -309,6 +320,13 @@ private static int runCartridge(final Options options) throws IOException { // the few milliseconds of filing that follow it. var wallClockMillis = (System.nanoTime() - startedNanos) / 1_000_000; + // After that, for the same reason: flushing the last of a log is filing rather than + // running. For both modes, since either can have started one -- --log-events opens it + // above and the REPL's "events on" opens it half way through a session -- and doing + // nothing when nothing is being written is what lets one line cover both. The file is + // still described in the report afterwards. + session.stopEventLog(); + var recorded = outcome.recorded(); var recordedTo = outcome.recordedTo(); diff --git a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Options.java b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Options.java index 434a677..d1f0ee1 100644 --- a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Options.java +++ b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Options.java @@ -77,6 +77,15 @@ * a number rather than a yes. {@link Overclock#NONE} unless one was named. * @param genie Game Genie codes to put in the cartridge slot, already decoded. * @param dumps which memories to write out when the run ends. + * @param logEvents where to write down every PPU, audio and mapper write and both + * interrupts, with the beam position each happened at, or null. Costs the + * machine nothing and stops it never, which is what separates it from a + * watchpoint. No limit goes with it, unlike the REPL's {@code events}, + * because a run that walks a schedule is already bounded by + * {@code --frames} and a session is not. + * @param logReads whether that log also holds the reads -- the $2002 and $4016 polls. + * Refused without somewhere to write them, since a setting on a thing + * nobody switched on is a thing that quietly does nothing. * @param loadState a save state to start from instead of power on, or null. * @param saveState where to write a save state when the run ends, or null. * @param sramIn a battery file to fill the cartridge's RAM from before starting, or null. @@ -126,6 +135,8 @@ public record Options( Overclock overclock, List genie, List dumps, + Path logEvents, + boolean logReads, Path loadState, Path saveState, Path sramIn, @@ -216,6 +227,23 @@ The second is worth building once (mvn -B package -DskipTests) for anything run produce byte-identical artifacts on every run and on every computer, which is what makes a frame hash worth writing down and two reports worth diffing. + This is long, and the half of it people miss is the half below the picture. What is + further down, and what each part answers: + Input Nothing starts on its own. --input 60/40x3:start. + Picture Screenshots, the crops, the palette, and the two filters. + Sound --audio writes a WAV; --mute takes a voice out of the mixer. + Hacks Unlimited sprites, and the overclock that stops a dropped frame. + Memory --dump ram,oam,palette,nametables,prgram,chr, once it has + finished. + Where in the frame --log-events writes down every register write with the scanline + and the dot it landed on, and stops nothing to do it. + Saved games --load-state to skip the title screen, --save-state to make one. + Movies --record and --play a whole session, byte for byte. + Interactive --interactive is the debugger: breakpoints and their conditions, + watchpoints, single steps, disassembly, standing on a scanline, + the instruction trace, the event log, rewind. "help" inside it + lists the lot. + Cartridge and length --rom FILE The .nes file to run, or a .zip holding one -- which is how nearly every collection ships them. Required. A zip is opened @@ -393,6 +421,30 @@ The second is worth building once (mvn -B package -DskipTests) for anything run one file each, under . Palette RAM is in the report as well, being 32 bytes. + Where in the frame + --log-events FILE Write down every PPU, audio and mapper register write, and both + interrupts, one record a line, with the frame, scanline and dot + each landed on: + # frame line dot event address value pc + 64 23 82 ppu-write $2005 $00 $80FF + Nothing is stopped and the machine does not slow down, which is + what makes this rather than a watchpoint the way to ask where a + raster split lands on every frame of a long run. The dot is good + to within two: three dots go past in one CPU cycle, so it is the + last of the three the cycle covered. Work RAM and instruction + fetches are deliberately not in it -- those are the game + thinking, and the REPL's watch and read are for them. + A few hundred records a frame for a game with a music driver and + a split, so a long run is a few megabytes. The REPL's "events" + takes a limit as well; a run of a schedule is already bounded by + --frames. + --log-reads Put the reads in it too -- the $2002 wait and the $4016 pad + poll, which are worth seeing exactly when the question is why a + game is waiting. This is the one part a machine can feel, since + recording reads puts a hook on the line every instruction fetch + comes past, so it is off unless asked for. Refused without + --log-events. + Saved games and save states --sram-in FILE Fill the cartridge's battery RAM from FILE before the run. Raw 8KB of $6000-$7FFF, which is what every other emulator writes, @@ -500,6 +552,8 @@ public static Options parse(final String[] args) { var overclock = Overclock.NONE; var genie = new ArrayList(); var dumps = new LinkedHashSet(); + Path logEvents = null; + var logReads = false; Path loadState = null; Path saveState = null; Path sramIn = null; @@ -564,6 +618,8 @@ public static Options parse(final String[] args) { parseHacks(value(args, ++i, flag), hacks, overclock); case "--genie" -> parseGenie(value(args, ++i, flag), genie); case "--dump" -> parseDumps(value(args, ++i, flag), dumps); + case "--log-events" -> logEvents = Path.of(value(args, ++i, flag)); + case "--log-reads" -> logReads = true; case "--load-state" -> loadState = Path.of(value(args, ++i, flag)); case "--save-state" -> saveState = Path.of(value(args, ++i, flag)); case "--sram-in" -> sramIn = Path.of(value(args, ++i, flag)); @@ -610,6 +666,15 @@ public static Options parse(final String[] args) { + filter.id() + " does not draw on one. --filter crt does."); } + // And for the same reason again: the reads are the expensive half of the log and the half + // somebody asks for deliberately, so a run that asked for them and wrote no log at all + // would have been given the one thing it did not want -- silence. + if (logReads && logEvents == null) { + throw new UsageException( + "--log-reads says what goes in the event log, and there is no --log-events" + + " FILE to put it in."); + } + if (play != null) { // Each of these is a second answer to a question the movie has already answered, and a // run that quietly took one of them would not be the recorded session at all. Refused @@ -670,6 +735,8 @@ public static Options parse(final String[] args) { overclock, List.copyOf(genie), List.copyOf(dumps), + logEvents, + logReads, loadState, saveState, sramIn, diff --git a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Repl.java b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Repl.java index 2a0c41b..e6005c7 100644 --- a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Repl.java +++ b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Repl.java @@ -47,6 +47,10 @@ public final class Repl { run [N] advance N frames, default 1 run-until-change [MAX] advance until the picture differs, at most MAX frames run-until-still [N] [MAX] advance until the picture has held for N frames + run-until-scanline N advance until the beam next reaches scanline N, which is + where to stand to read the PPU's own state part way down a + frame. Instruction granularity, so the dot it lands on is a + few past the start of the line rather than 0 step [N] advance N instructions, default 1 disasm [ADDR] [COUNT] disassemble, from the PC by default break ADDR [if COND] stop before the instruction at ADDR, on the passes where @@ -64,6 +68,16 @@ COND holds. A condition compares two of a register (a, x, y, trace [PATH [LINES]] write every instruction to PATH in nestest's format, at most LINES of them; "trace off" stops, and bare "trace" says how far it has got. A frame is about two megabytes of it + events on PATH [LINES] write down every PPU, audio and mapper write and both + interrupts, one a line, with the frame, scanline and dot + each happened at. Nothing is stopped and the machine does + not slow down, which is what makes this rather than watch + the way to ask where a split lands every frame for 200 + frames + events reads PATH [LINES] the same, and the $2002 and $4016 polls as well. The read + hook sees every instruction fetch, so this is the one form + the machine can feel + events off stop; bare "events" says how far it has got press BUTTONS [N] hold BUTTONS for the next N frames hold BUTTONS hold BUTTONS until released release let go of everything @@ -265,6 +279,10 @@ private void dispatch(final String[] words) throws IOException { detachTracer(); } + // And the event log, for the same reason and in the same breath: one that reached its limit + // closed its file and went quiet, but it has no debugger to take itself off. + session.sweepEventLog(); + switch (name) { case "run" -> run(words.length > 1 ? number(words[1], name) : 1); case "run-until-change" -> runUntilChange( @@ -272,6 +290,7 @@ private void dispatch(final String[] words) throws IOException { case "run-until-still" -> runUntilStill( words.length > 1 ? number(words[1], name) : DEFAULT_STILL_FRAMES, words.length > 2 ? number(words[2], name) : DEFAULT_MAX_FRAMES); + case "run-until-scanline" -> runUntilScanline(words); case "step" -> stepInstructions(words.length > 1 ? number(words[1], name) : 1); case "disasm" -> disasm(words); case "break" -> breakpoint(words); @@ -279,6 +298,7 @@ private void dispatch(final String[] words) throws IOException { case "unbreak", "unwatch" -> unpoint(name, words); case "points" -> points(words); case "trace" -> trace(words); + case "events" -> events(words); case "press" -> press(words); case "hold" -> hold(words); case "release" -> release(); @@ -372,6 +392,58 @@ private void runUntilStill(final long still, final long max) throws IOException }); } + /** + * Advances until the beam next reaches a scanline. + *

+ * The third of the {@code run-until} family, and the one that stops somewhere rather than when + * something happens: the other two watch the picture, and this watches the beam. It is the way + * to read what the chip is scrolling with part way down a frame -- {@code run-until-scanline + * 167} then {@code state}, and {@code ppu.v} says which tile column the next line will come + * from. + *

+ * A watchpoint is a different question and usually the better one. "Where does this + * write land" is {@code watch $2005} and needs no number guessed in advance; this answers + * "what does the machine look like at line 167", which nothing else here can ask. It composes + * with the rest: a breakpoint that fires first stops it and is reported, so the two can be set + * together and whichever comes first wins. + *

+ * No maximum, unlike the other two, because there is nothing to wait for that might not happen: + * the PPU is clocked whatever the program does, so the beam reaches every line its region has + * inside a frame -- and a line the region does not have is refused rather than waited for. + */ + private void runUntilScanline(final String[] words) throws IOException { + if (words.length < 2) { + throw new UsageException( + "run-until-scanline wants a scanline, as in \"run-until-scanline 167\"."); + } + + var region = session.nes().getRegion(); + var target = (int) number(words[1], "run-until-scanline"); + + if (target < 0 || target >= region.scanlinesPerFrame()) { + throw new UsageException( + "a frame on this " + region.label() + " machine is " + + region.scanlinesPerFrame() + " scanlines, so there is no line " + + target + " for the beam to reach."); + } + + var start = session.frame(); + var stepped = session.runUntilScanline(target); + var ppu = session.nes().getPPU(); + + reply("run-until-scanline", node -> { + // Where it actually stopped rather than what was asked for, because the two differ: + // this lands a few dots into the line, and an OAM transfer in the way can carry it + // past the line altogether. + node.put("scanline", ppu.getScanline()); + node.put("dot", ppu.getDot()); + node.put("reached", ppu.getScanline() == target); + node.put("instructions", stepped.instructions()); + node.put("framesRun", session.frame() - start); + describe(node, stepped.stop()); + }); + } + /** * Advances instructions rather than frames, and says what the machine is standing on afterwards. *

@@ -612,6 +684,93 @@ private void putTrace(final Json.Object node) { } } + /** + * Starts writing down what the machine does to its hardware, stops, or says how far it has got. + *

+ * The shape of {@code trace} beside it, because it is the same kind of thing -- a file that + * fills up while the machine runs -- and the difference between the two is the whole reason + * both exist. A trace is every instruction, which is a couple of megabytes a frame and answers + * what the program did; this is only the accesses that are the machine being told + * something, which is a few hundred a frame, and it stamps each one with where the beam was. + *

+ * It stops nothing. A {@code watch} on $2006 in a game whose NMI handler writes it forty + * times a frame is forty stops and forty resumes for one frame's worth of answer; this runs the + * machine at full speed and hands back all two hundred frames of it to grep. Which is also why + * the reads are a separate form rather than a flag: they are the one part of this a machine can + * feel, since recording them puts a hook on the line every instruction fetch comes past. + */ + private void events(final String[] words) throws IOException { + if (words.length < 2) { + reply("events", this::putEvents); + return; + } + + var what = words[1].toLowerCase(Locale.ROOT); + + if (what.equals("off")) { + if (!session.loggingEvents()) { + throw new UsageException("nothing is being logged."); + } + + session.stopEventLog(); + + // Reported in the reply rather than thrown, the same as "trace off": a log that stopped + // early still wrote everything up to the point it stopped. + reply("events", this::putEvents); + + return; + } + + if (!what.equals("on") && !what.equals("reads")) { + throw new UsageException( + "events takes \"on\", \"reads\", \"off\" or nothing, not \"" + words[1] + + "\"."); + } + + if (words.length < 3) { + throw new UsageException( + "events " + what + " wants somewhere to write it, as in \"events " + what + + " events.log\"."); + } + + var path = Path.of(words[2]); + var limit = words.length > 3 ? number(words[3], "events") : 0; + + // A file that cannot be opened is a bad command rather than the end of the session, the + // same as a misspelled address. + try { + session.startEventLog(path, what.equals("reads"), limit); + } catch (IOException e) { + throw new UsageException("could not write " + path + ": " + e.getMessage()); + } + + reply("events", node -> { + node.put("limit", limit); + putEvents(node); + }); + } + + private void putEvents(final Json.Object node) { + node.put("on", session.loggingEvents()); + + var log = session.eventLog(); + + if (log == null) { + return; + } + + node.put("path", session.eventLogPath().toString()); + node.put("records", log.records()); + node.put("full", log.isFull()); + + // Only when there was one, the same as the trace's: a caller asking "did this go wrong?" + // should not have to compare against null on every reply. + if (log.failure() != null) { + node.put("failed", true); + node.put("failure", String.valueOf(log.failure().getMessage())); + } + } + private void press(final String[] words) { if (words.length < 2) { throw new UsageException("press wants buttons, as in \"press start\"."); @@ -690,6 +849,18 @@ private void state() { var picture = node.putObject("ppu"); picture.put("scanline", ppu.getScanline()); picture.put("dot", ppu.getDot()); + + // The four the chip scrolls with, and the reason this reply is worth taking at a + // breakpoint at all. Where the beam is is the symptom; v is the answer -- its low five + // bits are the coarse X the next tile comes from, so a background that is eight pixels + // out on one scanline says so here and says it nowhere else. t is what the next + // $2006/$2005 pair is assembling, fineX the scroll within the tile, and writeLatch + // which half of a two-write register the next write will be: a split that wrote an odd + // number of bytes leaves that true and puts every later write in the wrong half. + picture.put("v", ppu.getV()); + picture.put("t", ppu.getT()); + picture.put("fineX", ppu.getFineX()); + picture.put("writeLatch", ppu.isWriteLatchSet()); picture.put("renderingEnabled", ppu.isRenderingEnabled()); var video = node.putObject("video"); diff --git a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Report.java b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Report.java index b3bf7b2..84a45aa 100644 --- a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Report.java +++ b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Report.java @@ -420,6 +420,25 @@ public static String write( InputSchedule.describe(event.buttons()).forEach(buttons::add); } + // Beside the dumps because it is the same kind of thing -- a file this run wrote that is + // too big to put in here -- and not on the comparability checklist above, because logging + // does not arm the machine and changes nothing it does. Always present, with explicit + // nulls, so two reports line up key for key whether either run logged anything. The record + // count is the whole point of its being here: a log that came back empty is a question + // about what was expected rather than a file worth opening. + var eventLog = report.putObject("eventLog"); + put(eventLog, "path", session.eventLogPath()); + + if (session.eventLog() == null) { + eventLog.putNull("reads"); + eventLog.putNull("records"); + eventLog.putNull("full"); + } else { + eventLog.put("reads", session.eventLogReads()); + eventLog.put("records", session.eventLog().records()); + eventLog.put("full", session.eventLog().isFull()); + } + var dumps = report.putArray("dumps"); for (var dump : outcome.dumps()) { var node = dumps.addObject(); diff --git a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Session.java b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Session.java index cefd7ce..cbf33bc 100644 --- a/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Session.java +++ b/mynes-headless/src/main/java/com/github/dimiro1/mynes/headless/Session.java @@ -3,6 +3,7 @@ import com.github.dimiro1.mynes.NES; import com.github.dimiro1.mynes.cheat.GameGenie; import com.github.dimiro1.mynes.debug.Debugger; +import com.github.dimiro1.mynes.debug.EventTracer; import com.github.dimiro1.mynes.state.Movie; import com.github.dimiro1.mynes.state.MovieRecorder; import com.github.dimiro1.mynes.state.Rewind; @@ -147,6 +148,32 @@ public record AudioStats(long samples, double peak, double rms, long silentFrame */ private @Nullable MovieRecorder recorder; + /** + * Where what the machine does to its hardware is being written down, and where that went. Null + * until somebody asks, and kept after it has been stopped so that the report and the REPL can + * still say how long the file is -- which is the question somebody asks straight after stopping + * one. + *

+ * Here rather than in {@link Repl} beside the instruction tracer, because both headless modes + * can start one: {@code --log-events} on a run that walks a schedule, and {@code events on} in + * a session. Two owners would be two answers to "is one running". + */ + private @Nullable EventTracer events; + + private @Nullable Path eventsPath; + + /** + * Whether that log holds the reads as well. Kept beside it rather than left on the command + * line, so that a session which opened one half way through is described by what it asked for + * rather than by what the run started as. + */ + private boolean eventsReads; + + /** + * Whether {@link #events} is still attached to the debugger and still writing. + */ + private boolean logging; + /** * How many frames this session has gone back over its whole life, which is what the report * carries. Cumulative and never reset: the question it answers is whether the run is comparable @@ -396,34 +423,86 @@ private Frame watchedFrame(final long completed) throws IOException { /** * Runs instructions rather than frames, stopping early if the debugger says to. - *

- * Frames still finish underneath -- the sound is collected and the picture counted whenever the - * PPU crosses a boundary -- because the APU's ring holds only a few frames of samples and a long - * step that never drained it would lose the end of them. */ public Stepped stepInstructions(final long count) throws IOException { - var ppu = nes.getPPU(); - var cpu = nes.getCPU(); Debugger.Stop stop = null; var ran = 0L; while (ran < count && stop == null) { - var completed = ppu.getFrame(); - var wasPC = cpu.getPC(); + stop = stepOne(); + ran++; + } - nes.step(); + return new Stepped(ran, stop); + } + + /** + * Runs instructions until the beam next reaches a scanline, which is how to stand somewhere in + * particular part way down a frame. + *

+ * The beam has to leave the line before it can arrive at it. Asked for the line it is + * already on, this runs most of a frame and comes back on the next pass rather than returning + * the same moment twice -- which is what makes calling it in a loop a way to watch one line + * over successive frames. + *

+ * Instruction granularity, so it lands a few dots into the line rather than on dot 0. + * That is the price of every other instrument still meaning something where it stops: a machine + * halted between instructions has a program counter a disassembly can start from and a + * breakpoint can be checked against, and one halted mid-instruction has neither. Seven CPU + * cycles is the usual overshoot, which is twenty-one dots; a step that swallows an OAM + * transfer is five hundred, which is the one case this overshoots the line altogether, so the + * scanline it actually stopped on is worth reading rather than assuming. + *

+ * Nothing bounds it but the line itself. The PPU is clocked by every tick whatever the program + * is doing, so a line the region has is reached inside a frame and a line it has not is + * refused before this is called. + * + * @param target which scanline to stop on. + * @return how many instructions that took, and whatever stopped it sooner. + */ + public Stepped runUntilScanline(final int target) throws IOException { + var ppu = nes.getPPU(); + Debugger.Stop stop = null; + var ran = 0L; + var away = ppu.getScanline() != target; + var arrived = false; + + while (!arrived && stop == null) { + stop = stepOne(); ran++; - if (ppu.getFrame() != completed) { - endOfFrame(null); + if (ppu.getScanline() == target) { + arrived = away; + } else { + away = true; } - - stop = debugger.afterInstruction(cpu.getPC(), wasPC); } return new Stepped(ran, stop); } + /** + * One instruction, with the bookkeeping a frame that ended underneath it owes. + *

+ * Frames still finish here -- the sound is collected and the picture counted whenever the PPU + * crosses a boundary -- because the APU's ring holds only a few frames of samples and a long + * walk that never drained it would lose the end of them. + */ + private Debugger.Stop stepOne() throws IOException { + var ppu = nes.getPPU(); + var cpu = nes.getCPU(); + var completed = ppu.getFrame(); + var wasPC = cpu.getPC(); + + nes.step(); + + if (ppu.getFrame() != completed) { + endOfFrame(null); + } + + return debugger.afterInstruction(cpu.getPC(), wasPC); + } + /** * The bookkeeping a finished frame owes: its sound collected, its picture hashed, and whether * it differs from the one before it written down. @@ -810,6 +889,100 @@ public void beginReplay(final Movie movie) { previousHash = FrameAnalysis.hash(nes.getPPU().getFrameBuffer()); } + // ============================================================================== the event log + + /** + * Starts writing down every PPU, audio and mapper write, and both interrupts, with the beam + * position each happened at. + *

+ * The machine is not armed by this and does not slow down. That is the whole reason to + * reach for it rather than for a watchpoint: where in the frame a game writes $2005 is a + * question about a game whose main loop is finishing on time, and a gauge that stopped the + * machine a hundred times a frame to ask would be measuring itself. + * + * @param path where to write it. + * @param reads whether to log the reads as well. Off unless it is wanted: the read hook sees + * every instruction fetch, so this is the one setting here a machine can feel, and + * what it buys is the $2002 and $4016 polls. + * @param limit how many records to write before going quiet, or 0 for no limit. + * @throws UsageException if one is already being written, since two logs would be two answers + * to where the events are going. + */ + public void startEventLog(final Path path, final boolean reads, final long limit) + throws IOException { + + if (logging) { + throw new UsageException( + "the machine's events are already being written to " + eventsPath + "."); + } + + events = EventTracer.to(path, nes.getPPU(), limit); + eventsPath = path; + eventsReads = reads; + logging = true; + + debugger.setEventSink(events, reads); + } + + /** + * Stops writing it and closes the file, leaving it where it can still be described. + *

+ * Doing it when nothing is being written is not an error, which is what lets the end of a + * session and an explicit {@code events off} take the same path. + */ + public void stopEventLog() throws IOException { + if (!logging) { + return; + } + + logging = false; + debugger.setEventSink(null, false); + events.close(); + } + + /** + * Takes a log that has written all it was asked for off the debugger. + *

+ * A full one has already closed its file and gone quiet, but it cannot take itself off the + * debugger -- it has no reference to one -- so until somebody does, the machine pays for a + * sink that is doing nothing. Whoever is driving calls this between commands, the same way the + * REPL picks up a finished instruction trace. + */ + public void sweepEventLog() { + if (logging && events.isFull()) { + logging = false; + debugger.setEventSink(null, false); + } + } + + /** + * Whether one is still being written. + */ + public boolean loggingEvents() { + return logging; + } + + /** + * The log this session last opened, live or finished, or null if it opened none. + */ + public @Nullable EventTracer eventLog() { + return events; + } + + /** + * Where that went. + */ + public @Nullable Path eventLogPath() { + return eventsPath; + } + + /** + * Whether it holds the reads as well as the writes. + */ + public boolean eventLogReads() { + return eventsReads; + } + /** * The bytes of one of the things {@code --dump} can name. * diff --git a/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/EventLogRunTests.java b/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/EventLogRunTests.java new file mode 100644 index 0000000..3612f03 --- /dev/null +++ b/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/EventLogRunTests.java @@ -0,0 +1,259 @@ +package com.github.dimiro1.mynes.headless; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.github.dimiro1.mynes.Cart; +import com.github.dimiro1.mynes.NES; +import com.github.dimiro1.mynes.palette.Palettes; +import com.github.dimiro1.mynes.video.FilterStrength; +import com.github.dimiro1.mynes.video.VideoFilter; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +import java.io.BufferedReader; +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.io.PrintStream; +import java.io.StringReader; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Where in the frame the machine was touched, asked for from a command line and from a session. + *

+ * The core's {@code EventTracerTests} holds the file's shape and the beam position in it; what only + * exists once everything is joined up is the rest: that a flag opens one and the report names it, + * that the REPL's three forms start, stop and count the same log, and -- the claim the whole design + * rests on -- that a run being logged is byte for byte the run that was not. A gauge that changed + * the timing would be measuring itself. + */ +class EventLogRunTests { + private static final String ROM = "src/test/resources/nestest/nestest.nes"; + private static final ObjectMapper MAPPER = new ObjectMapper(); + + @TempDir + private Path out; + + private int run(final String... extra) { + var args = new ArrayList( + List.of("--rom", ROM, "--out", out.toString(), "--quiet", "--frames", "60")); + + args.addAll(List.of(extra)); + + return Headless.run(args.toArray(new String[0])); + } + + private JsonNode report() throws IOException { + return MAPPER.readTree(Files.readString(out.resolve("report.json"))); + } + + /** + * The file's records, header dropped, cut into their fields. + */ + private List records(final Path path) throws IOException { + return Files.readAllLines(path).stream() + .filter(line -> !line.startsWith("#")) + .map(line -> line.trim().split("\\s+")) + .toList(); + } + + /** + * Runs a REPL session against a fresh machine and hands back one parsed reply per line. + */ + private List session(final String... commands) throws IOException { + var cart = Cart.load(Files.readAllBytes(Path.of(ROM)), ROM); + var session = new Session( + new NES(cart), + Palettes.defaultPalette().colours(), + VideoFilter.NONE, + FilterStrength.defaultStrength(), + false, + false, + null); + var options = Options.parse(new String[]{"--rom", ROM, "--interactive"}); + var captured = new ByteArrayOutputStream(); + + try (var stdout = new PrintStream(captured, true, StandardCharsets.UTF_8); + var in = new BufferedReader(new StringReader(String.join("\n", commands) + "\n"))) { + + new Repl(session, options, in, stdout, false).run(); + } + + var replies = new ArrayList(); + + for (var line : captured.toString(StandardCharsets.UTF_8).lines().toList()) { + replies.add(MAPPER.readTree(line)); + } + + return replies; + } + + // ================================================================================ the command line + + @Test + void theFlagWritesALogAndTheReportNamesIt() throws Exception { + var path = out.resolve("events.log"); + + assertEquals(Headless.EXIT_OK, run("--log-events", path.toString())); + + var records = records(path); + + assertFalse(records.isEmpty(), "nestest writes its registers on every frame"); + assertEquals(records.size(), report().at("/eventLog/records").asLong()); + assertEquals(path.toString(), report().at("/eventLog/path").asText()); + assertFalse(report().at("/eventLog/reads").asBoolean()); + assertFalse(report().at("/eventLog/full").asBoolean()); + } + + /** + * Always present with explicit nulls, so two reports line up key for key whether either run + * logged anything. + */ + @Test + void theReportSaysSoEvenWhenNothingWasLogged() throws Exception { + run(); + + assertTrue(report().at("/eventLog/path").isNull()); + assertTrue(report().at("/eventLog/reads").isNull()); + assertTrue(report().at("/eventLog/records").isNull()); + assertTrue(report().at("/eventLog/full").isNull()); + } + + /** + * The reads are the expensive half and the half somebody asks for deliberately, which is why + * they are a flag of their own and why they are off without it. + */ + @Test + void theReadsAreOnlyThereWhenTheyWereAskedFor() throws Exception { + var quiet = out.resolve("writes.log"); + var loud = out.resolve("both.log"); + + run("--log-events", quiet.toString()); + + assertTrue( + records(quiet).stream().noneMatch(fields -> fields[3].endsWith("-read")), + "reads were not asked for"); + + run("--log-events", loud.toString(), "--log-reads"); + + assertTrue( + records(loud).stream().anyMatch(fields -> fields[3].equals("ppu-read")), + "nestest polls $2002 while it waits for vblank"); + assertTrue(report().at("/eventLog/reads").asBoolean()); + } + + /** + * A setting on a thing nobody switched on is a thing that quietly does nothing, which is the + * same refusal {@code --filter none=low} and {@code --warp} without a tube get. + */ + @Test + void readsWithNoLogToPutThemInIsRefused() { + assertEquals(Headless.EXIT_USAGE, run("--log-reads")); + } + + /** + * The claim the whole design rests on: the sink does not arm the machine, so the run it watches + * is the run that would have happened. Checked on the frame hash, which is the finest thing the + * report holds. + */ + @Test + void aLoggedRunIsByteForByteAnUnloggedOne() throws Exception { + run("--log-events", out.resolve("both.log").toString(), "--log-reads"); + + var logged = report().at("/video/finalFrame/hash").asText(); + var loggedCycles = report().at("/run/cpuCycles").asLong(); + + run(); + + assertEquals(logged, report().at("/video/finalFrame/hash").asText()); + assertEquals(loggedCycles, report().at("/run/cpuCycles").asLong()); + } + + // ====================================================================================== the REPL + + @Test + void theSessionStartsStopsAndCountsOne() throws Exception { + var path = out.resolve("repl.log"); + var replies = session( + "events", + "events on " + path, + "run 5", + "events", + "events off", + "events", + "quit"); + + assertFalse(replies.get(0).get("on").asBoolean(), "nothing is being logged yet"); + + var running = replies.get(3); + + assertTrue(running.get("on").asBoolean()); + assertEquals(path.toString(), running.get("path").asText()); + assertTrue(running.get("records").asLong() > 0); + + var stopped = replies.get(5); + + assertFalse(stopped.get("on").asBoolean()); + assertEquals( + running.get("records").asLong(), + stopped.get("records").asLong(), + "and it stopped counting when it stopped writing"); + + assertEquals(stopped.get("records").asLong(), records(path).size()); + } + + @Test + void theSessionAsksForTheReadsWithAFormOfItsOwn() throws Exception { + var path = out.resolve("reads.log"); + + session("events reads " + path, "run 5", "events off", "quit"); + + assertTrue( + records(path).stream().anyMatch(fields -> fields[3].equals("ppu-read")), + "the polls are in it"); + } + + /** + * A limit that has been reached takes the log off the machine rather than leaving it on doing + * nothing, which is the same sweep a finished instruction trace gets between commands. + */ + @Test + void aSessionLogStopsAtItsLimit() throws Exception { + var path = out.resolve("short.log"); + var replies = session("events on " + path + " 20", "run 5", "events", "quit"); + var full = replies.get(2); + + assertTrue(full.get("full").asBoolean()); + assertFalse(full.get("on").asBoolean(), "and took itself off"); + assertEquals(20, full.get("records").asLong()); + assertEquals(20, records(path).size()); + } + + @Test + void aSecondLogIsRefusedRatherThanReplacingTheFirst() throws Exception { + var replies = session( + "events on " + out.resolve("first.log"), + "events on " + out.resolve("second.log"), + "quit"); + + assertTrue(replies.get(0).get("ok").asBoolean()); + assertFalse(replies.get(1).get("ok").asBoolean()); + assertTrue(replies.get(1).get("error").asText().contains("first.log")); + } + + @Test + void theFormsThatMakeNoSenseAreRefused() throws Exception { + var replies = session("events off", "events wibble", "events on", "quit"); + + assertFalse(replies.get(0).get("ok").asBoolean(), "nothing is being logged"); + assertFalse(replies.get(1).get("ok").asBoolean(), "\"wibble\" is not one of the forms"); + assertFalse(replies.get(2).get("ok").asBoolean(), "and \"on\" wants somewhere to write it"); + } +} diff --git a/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/OptionsTests.java b/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/OptionsTests.java index c3759d6..514c179 100644 --- a/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/OptionsTests.java +++ b/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/OptionsTests.java @@ -200,6 +200,24 @@ void theWarpIsRefusedWithoutTheTube() { .getMessage().contains("crt")); } + /** + * The same refusal for the same reason: the reads are the expensive half of an event log and + * the half somebody asks for deliberately, so a run that asked for them and wrote no log at all + * would have been handed the one thing it did not want. + */ + @Test + void theReadsAreRefusedWithoutSomewhereToLogThem() { + assertNull(parse("--rom", "x.nes").logEvents()); + assertFalse(parse("--rom", "x.nes").logReads()); + + var both = parse("--rom", "x.nes", "--log-events", "ev.log", "--log-reads"); + + assertEquals(Path.of("ev.log"), both.logEvents()); + assertTrue(both.logReads()); + + assertTrue(refused("--rom", "x.nes", "--log-reads").getMessage().contains("--log-events")); + } + /** * The one video flag that is refused beside nothing, which is the difference between the shape * of a pixel and the two settings above it: those are things a particular filter does, and this diff --git a/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/ReplTests.java b/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/ReplTests.java index d9625a4..821cf7d 100644 --- a/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/ReplTests.java +++ b/mynes-headless/src/test/java/com/github/dimiro1/mynes/headless/ReplTests.java @@ -82,6 +82,20 @@ private List magnified(final int scale, final String... commands) return replies; } + /** + * A one-shot run of the same cartridge, so that a reply and a report can be held against each + * other. They describe one machine and should say so in one vocabulary. + */ + private String reportOf(final String... extra) throws IOException { + var args = new ArrayList<>( + List.of("--rom", ROM, "--out", directory.toString(), "--quiet")); + + args.addAll(List.of(extra)); + Headless.run(args.toArray(new String[0])); + + return Files.readString(directory.resolve("report.json")); + } + @Test void everyCommandGetsOneLineOfJsonBack() throws Exception { var replies = session("run 10", "run 10", "quit"); @@ -178,6 +192,92 @@ void stateSaysWhereEverythingIs() throws Exception { assertTrue(reply.at("/audio/samples").asLong() > 0); } + /** + * The scanline and the dot say where the beam is, which for anything to do with a raster is the + * symptom rather than the answer. These four are what explains it: the whole reason to stop a + * machine part way down a frame is to find out what the chip is about to scroll from, and a + * coarse-X that is one tile out says so here and nowhere else in the program. + */ + @Test + void stateCarriesTheRegistersTheChipScrollsWith() throws Exception { + var reply = session("run 60", "state", "quit").get(1); + + assertTrue(reply.at("/ppu/v").isNumber()); + assertTrue(reply.at("/ppu/t").isNumber()); + assertTrue(reply.at("/ppu/fineX").isNumber()); + assertTrue(reply.at("/ppu/writeLatch").isBoolean()); + } + + /** + * The same four the report has, spelled the same way. Two names for one register would be two + * things to learn and one of them wrong. + */ + @Test + void thoseAreSpelledTheWayTheReportSpellsThem() throws Exception { + var state = session("run 60", "state", "quit").get(1).get("ppu"); + var report = MAPPER.readTree(reportOf("--frames", "60")).get("ppu"); + + for (var field : List.of("scanline", "dot", "v", "t", "fineX", "writeLatch")) { + assertEquals( + report.get(field), + state.get(field), + field + " after sixty frames of the same cartridge"); + } + } + + /** + * The whole of the run-until family's third member: stand on a scanline and look. It lands a + * few dots in rather than on dot 0, because it stops between instructions so that everything + * else -- a disassembly, a breakpoint, the program counter -- still means something there. + */ + @Test + void runUntilScanlineStandsOnTheLineItWasAskedFor() throws Exception { + var reply = session("run 60", "run-until-scanline 167", "quit").get(1); + + assertTrue(reply.get("reached").asBoolean()); + assertEquals(167, reply.get("scanline").asInt()); + assertTrue(reply.get("dot").asInt() < 30, "a few dots in, not most of a line"); + assertTrue(reply.get("instructions").asLong() > 0); + } + + /** + * Asked for the line it is already on, it goes round rather than answering with the moment it + * is already standing in -- which is what makes calling it in a loop a way of watching one line + * over successive frames. + */ + @Test + void askingTwiceGivesTwoFrames() throws Exception { + var replies = session( + "run 60", "run-until-scanline 167", "run-until-scanline 167", "quit"); + + assertEquals(0, replies.get(1).get("framesRun").asLong()); + assertEquals(1, replies.get(2).get("framesRun").asLong()); + } + + /** + * Refused rather than waited for: a line the region has is reached inside a frame whatever the + * program is doing, and a line it has not would spin forever. + */ + @Test + void aScanlineTheMachineDoesNotHaveIsRefused() throws Exception { + var reply = session("run-until-scanline 400", "quit").getFirst(); + + assertFalse(reply.get("ok").asBoolean()); + assertTrue(reply.get("error").asText().contains("262"), reply.get("error").asText()); + } + + /** + * It composes with the debugger rather than replacing it: whichever of the two comes first + * stops the run and is reported, so both can be set and the answer is which happened. + */ + @Test + void aBreakpointStopsItBeforeTheLineArrives() throws Exception { + var reply = session("break $C008", "run-until-scanline 167", "quit").get(1); + + assertEquals("breakpoint", reply.get("stopped").asText()); + assertFalse(reply.get("reached").asBoolean()); + } + @Test void aScreenshotIsWrittenWhereItWasAskedFor() throws Exception { var path = directory.resolve("shot.png"); From d50bcf40c3ec35cfb4f29d6672a6ca7a402986da Mon Sep 17 00:00:00 2001 From: dimiro1 Date: Thu, 24 Sep 2026 22:37:05 +0200 Subject: [PATCH 2/2] Wait for the sweep rather than sleeping and hoping SweepTests.aViewOnScreenIsSweptUntilItGoesAway showed a window, slept a fixed 200ms and asserted a 5ms timer had ticked at least once. That whole budget is one cold first-window creation on the event dispatch thread -- a native peer, a graphics pipeline, a font or two -- so on a loaded Windows runner the thread can eat all of it with the timer started and not yet run, which reads as a timer that never started. It failed that way once on CI and passed on a re-run of the same commit. It only surfaced now because the Windows and macOS runners arrived in the commit before it: on Linux the test is skipped as headless, so this assertion had barely run in CI at all. So the positive half waits for the tick instead, up to ten seconds it will never spend -- the cost of being wrong is asymmetric, a red build nobody can reproduce against a few milliseconds on the one run where the machine was busy. The negative half keeps its fixed pause, because an absence has nothing to wait for and the timer is already stopped on the dispatch thread before the pause begins. Two smaller things fall out. isHeadless() is whether the JVM has a display at all, which is weaker than whether the window just asked for reached the screen, so the panel is asked directly and a machine that cannot show one skips rather than fails. And the dispose moves into a finally, so a failure leaves no window behind. Checked by breaking Sweep so the timer never starts: the test still fails, on the same assertion. Co-Authored-By: Claude Opus 5 (1M context) --- .../github/dimiro1/mynes/ui/SweepTests.java | 70 +++++++++++++++++-- 1 file changed, 63 insertions(+), 7 deletions(-) diff --git a/mynes-desktop/src/test/java/com/github/dimiro1/mynes/ui/SweepTests.java b/mynes-desktop/src/test/java/com/github/dimiro1/mynes/ui/SweepTests.java index 1ee7b65..3330161 100644 --- a/mynes-desktop/src/test/java/com/github/dimiro1/mynes/ui/SweepTests.java +++ b/mynes-desktop/src/test/java/com/github/dimiro1/mynes/ui/SweepTests.java @@ -7,24 +7,46 @@ import javax.swing.SwingUtilities; import java.awt.GraphicsEnvironment; import java.util.concurrent.atomic.AtomicInteger; +import java.util.function.BooleanSupplier; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assumptions.assumeFalse; +import static org.junit.jupiter.api.Assumptions.assumeTrue; /** * The rule every debug view's refresh timer keeps: it runs while somebody is looking and not * otherwise. + *

+ * The two halves are not checked the same way, and cannot be. That something eventually + * happens is waited for, since the only wrong answer a wait can give is a slow machine reported as + * a broken one. That something never happens has nothing to wait for, so it is a fixed pause and + * then a look -- which is sound here because the timer is stopped on the event dispatch thread + * before the pause begins. */ class SweepTests { /** - * Fast enough that a tick would have happened many times over inside the wait below, so a - * count of zero means the timer never started rather than that it was not given long enough. + * Fast enough that a tick is due many times over inside any of the waits below, so a count of + * zero means the timer never started rather than that it was not given long enough. */ private static final int FAST = 5; + /** + * How long to watch for something that should not happen. Only the negative halves use it: a + * pause is the only way to check an absence, and there is no length that makes one certain. + */ private static final int LONG_ENOUGH_MILLIS = 200; + /** + * How long to wait for something that should. Generous to the point of being silly against the + * five milliseconds a tick is due in, because the cost of being wrong is asymmetric -- too + * short is a red build nobody can reproduce, and too long is a few milliseconds on the one run + * where the machine was busy. A passing test never waits anything like this. + */ + private static final int PATIENCE_MILLIS = 10_000; + + private static final int POLL_MILLIS = 5; + /** * The half that matters most, and the one that can be asked anywhere: a view nobody has put on * screen polls nothing. That is what stops a test, or the README's camera, from clocking a @@ -64,12 +86,18 @@ void aViewOnScreenIsSweptUntilItGoesAway() throws Exception { frame[0].setVisible(true); }); - Thread.sleep(LONG_ENOUGH_MILLIS); - - var swept = ticks.get(); - assertTrue(swept > 0, "a view on screen is refreshed"); + try { + // The precondition the assumption above is only a proxy for. isHeadless() is whether + // the JVM has a display at all, which is a weaker question than whether the window + // just asked for reached the screen -- so the panel is asked instead, and a machine + // that cannot show one has nothing to sweep and nothing to say about sweeping. + assumeTrue(eventually(panel::isShowing), "the window never reached the screen"); - SwingUtilities.invokeAndWait(frame[0]::dispose); + assertTrue(eventually(() -> ticks.get() > 0), "a view on screen is refreshed"); + } finally { + // In a finally so that a failure above leaves no window behind on somebody's desk. + SwingUtilities.invokeAndWait(frame[0]::dispose); + } // The timer is stopped on the event dispatch thread, so let whatever was already queued // arrive before deciding it has stopped. @@ -82,4 +110,32 @@ void aViewOnScreenIsSweptUntilItGoesAway() throws Exception { assertEquals(atClose, ticks.get(), "and a view that has gone is not"); } + + /** + * Waits for something to become true, rather than sleeping a length somebody picked by eye and + * hoping it was enough. + *

+ * The window above is what makes that distinction matter. Putting the first one of a JVM's life + * on screen is the most expensive thing the event dispatch thread ever does -- a native peer, a + * graphics pipeline, a font or two -- and on a cold or loaded machine it can hold that thread + * long enough for a fixed pause to expire with the timer started and not yet run. Which reads + * as "the timer never started", and is the one answer this test must not give by accident. + * + * @return whether it became true before {@link #PATIENCE_MILLIS} ran out. + */ + private static boolean eventually(final BooleanSupplier condition) throws InterruptedException { + var deadline = System.nanoTime() + PATIENCE_MILLIS * 1_000_000L; + + while (!condition.getAsBoolean()) { + if (System.nanoTime() - deadline >= 0) { + return false; + } + + // On the test's thread rather than the dispatch thread, which is the whole point: + // waiting here is what leaves that one free to get to the work being waited for. + Thread.sleep(POLL_MILLIS); + } + + return true; + } }