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-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; + } } 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");