retroDE_ps2/sim/golden/trace_compare_spec.md

Golden Trace and Diff Spec

This document defines the first useful scope for the golden-reference harness after DobieStation runtime blocked at checkpoint 2.

The immediate target is not "full live-emulator comparison." The immediate target is:

• generated golden trace for a straight-line synthetic image,
• normalization into the common envelope,
• deterministic diff tooling,
• a clean upgrade path to live emulator traces later.

This spec is intentionally narrow so the harness plumbing can land now without waiting for a full EE implementation or a revived DobieStation runtime.

Scope

Phase covered by this spec:

• generated golden trace for a NOP-sled BIOS image,
• comparison against RTL ee_fetch.trace,
• event class limited to EE IFETCH.

Not in scope yet:

• real BIOS comparison,
• DobieStation runtime recovery,
• PCSX2 instrumentation,
• multi-event or multi-subsystem trace correlation,
• cycle-accurate timing comparison.

Comparison target

The first comparison target is a dedicated straight-line synthetic BIOS image.

Required properties:

• valid MIPS instruction stream,
• no branches in the compared window,
• no data loads or stores needed for correctness,
• deterministic sequential fetch progression.

For the first implementation, use a NOP sled:

• instruction word: 0x00000000
• image size: 4 MiB to match the BIOS window
• reset vector fetch starts at 0xBFC00000

Why this target:

• simple enough to reason about by inspection,
• valid execution stream for an emulator,
• meaningful now even with the current ee_fetch_stub,
• avoids comparing against the existing synthetic fixture whose words are not a sensible execution target.

Golden trace shape

The generated golden trace must use the project common envelope:

cycle subsystem event arg0 arg1 arg2 arg3 flags

Header lines:

• must begin with #
• should identify source, scenario, and schema version

Example:

# retroDE_ps2 golden trace, schema v1, source=generated, scenario=nop_sled
# columns: cycle subsystem event arg0 arg1 arg2 arg3 flags
0 EE IFETCH 0x00000000bfc00000 0x0000000000000000 0x0000000000000000 0x0000000000000000 -
1 EE IFETCH 0x00000000bfc00004 0x0000000000000000 0x0000000000000000 0x0000000000000000 -
2 EE IFETCH 0x00000000bfc00008 0x0000000000000000 0x0000000000000000 0x0000000000000000 -

Field rules for the generated NOP golden:

• cycle: monotonic ordinal index starting at 0
• subsystem: EE
• event: IFETCH
• arg0: fetch PC
• arg1: fetched instruction word, always 0x00000000
• arg2: response kind, 0x0000000000000000
• arg3: unused, 0x0000000000000000
• flags: -

RTL input expected by the diff

For the first compare, the RTL-side input is:

• sim/traces/rtl/ee_fetch.trace

The diff tool must ignore:

• comment lines beginning with #
• blank lines
• non-matching event classes if filtering is enabled

For the first compare, the tool should operate on EE IFETCH records only.

EE RESET lines are intentionally excluded from the first comparison target. They are useful trace events, but they are not part of the first golden fetch stream contract.

Normalized record model

The diff tool should parse each non-comment line into:

• cycle
• subsystem
• event
• arg0
• arg1
• arg2
• arg3
• flags

All numeric payloads should be normalized to integers internally.

flags normalization:

• - means zero
• 0x... means the parsed integer value

Diff semantics

Record selection

For the first implementation, compare records after filtering to:

• subsystem == EE
• event == IFETCH

Match strategy

Compare by record order, not by cycle.

Rationale:

• current RTL and future emulator traces may use different cycle/time bases,
• the first useful question is whether the fetch sequence matches,
• order-based comparison is the right fit for the current straight-line target.

Fields that must match

After filtering, the following fields must match exactly:

• subsystem
• event
• arg0
• arg1
• arg2
• arg3
• flags

Fields that are informational only

• cycle

The tool should still validate that cycle values are monotonic within each input trace, but cycle mismatch alone must not fail the compare.

Length mismatch policy

Length mismatch is a hard failure.

Cases:

• RTL shorter than golden: fail
• RTL longer than golden: fail
• either side empty after filtering: fail

Error output should report:

• filtered record counts on both sides,
• first missing index,
• which side ended early

Malformed input policy

Malformed input is a hard failure.

Examples:

• wrong number of columns,
• unparseable hex field,
• unknown event token in a filtered record,
• non-monotonic cycle values inside one trace

The tool should report:

• filename
• 1-based line number in the original file
• reason for rejection

Exit code contract

Suggested exit codes:

• 0: comparison passed
• 1: semantic mismatch
• 2: usage or missing-file error
• 3: malformed input / parse failure

This keeps "compare failed" distinct from "tool invocation broke."

Console output contract

On pass, print a concise summary:

PASS: matched 32 EE/IFETCH records (cycle ignored, order-based compare)

On mismatch, print:

• failing record index
• RTL record
• golden record
• short field-level mismatch summary

Example:

FAIL: mismatch at filtered record 5
  rtl:    EE IFETCH arg0=0x... arg1=0x...
  golden: EE IFETCH arg0=0x... arg1=0x...
  diff:   arg1 differs

Acceptance criteria

The first golden harness is accepted when all of the following are true:

1. A generated NOP-sled golden trace can be produced in the common envelope.
2. The diff tool can compare that golden trace against sim/traces/rtl/ee_fetch.trace.
3. The tool ignores EE RESET and compares only filtered EE IFETCH records.
4. A clean run against the current Wave 1 EE fetch path returns exit code 0.
5. A deliberate corruption of one fetched word in either input produces exit code 1 and reports the first mismatching filtered record.
6. A malformed trace line produces exit code 3.

Upgrade path

Once live emulator traces are available, reuse the same diff semantics with only two changes:

• replace the generated golden input with a normalized emulator trace,
• widen the compared window as far as the current RTL implementation remains meaningfully comparable.

Recommended next live-emulator order:

1. PCSX2, if a live source is needed before DobieStation runtime is recovered
2. DobieStation later, if the runtime block is removed