emulators-debug-log-audit

name

emulators-debug-log-audit

description

Parse and interpret execution debug logs generated by the EMULATORS framework, correlating each CPU instruction block with its VIC-II, CIA, SID, interrupt, stop, raster, badline, and memory-access cycles. Use for .LOG traces from EMULATORS when diagnosing cycle timing, raster effects, CPU stalls, IRQ/NMI entry, instruction/chip synchronization, or when reconstructing execution around a PC or mapped register.

EMULATORS Debug Log Audit

Workflow

1. Inspect the relevant debug... methods before assigning semantics to fields; the log format follows the current implementation.
2. Run scripts/analyze_log.py LOG --summary first. It streams the file and is suitable for large traces.
3. Locate relevant code with --match, for example --match 'PC:\$0bd|\$d011|Interrupt'.
4. Use --before N --after N to preserve CPU-block context. A block is delimited by a line containing only +.
5. Correlate the CPU header cycle with every chip cycle contained in that block. Expect the number of ordinary VIC-II/CIA cycles to equal the CPU instruction duration, except additional-info records.
6. Distinguish observation from inference. Report absolute emulator cycles, PC, instruction, raster row/cycle, CPU state, IRQ source/reason, and relevant register values.
7. For C64 video or CIA conclusions, also use the corresponding VIC-II or CIA audit skill and its reference.

Interpretation Rules

• CPU <cycle> Info Cycle opens an instruction-level block. Because debugLastExecutionData runs before the new instruction, Last N cycles describes the preceding instruction, while the following PC line describes the instruction executed in the current block. Compare durations across consecutive instruction blocks, never within the same block.
• PC is the instruction address; operand annotations show the effective address and observed/transferred value.
• Read numeric CPU states from the current enum before naming them.
• Each VICII <cycle> Info Cycle is one recovered cycle. Cross-check ROW/Cycle in Internal with Raster position.
• debugVICIICycle records the VIC-II snapshot before that cycle is processed. Event lines appended below it describe actions during the same cycle; the resulting state normally appears in the next snapshot.
• In full-instruction CPU mode, chip cycles are recovered after the CPU instruction has executed. A mapped-register write can therefore already be visible while earlier cycles of that instruction are being logged; do not infer its physical bus-write cycle from block membership alone.
• Treat badline fields, RC, VC, VCBASE, VLMI, DEN and CPU stops as one state machine.
• Repeated Interrupt CPU requested records while IRQ remains asserted are not repeated edges. Pair them with wait, rejection and launch records.
• Read debugCIACycle and timer accessors before naming every CIA tuple field.
• A PC jump alone does not prove an interrupt; require explicit interrupt evidence or vector/stack reconstruction.

Required Output

Provide a compact event timeline, invariants that hold or fail, the earliest divergent cycle, ranked causes with log evidence, and conditional solutions. Do not edit emulator code without explicit authorization.

See references/format.md for provenance and checks.