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
- * 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.
- *
+ * 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
+ * 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.
+ *
+ * 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
+ * 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
- * 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.
+ *
+ * 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.
+ *