thejayman77
ec82764bef
RTL (GS rasterizer, EE core stub, platform bridge, LPDDR4B path), sim regression (272 TBs), docs, and tooling. Copyrighted PS2 content (BIOS, game code, GS dumps, and all dump-derived textures/traces) is excluded via .gitignore and stays local. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
261 lines
6.5 KiB
Markdown
261 lines
6.5 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
cycle subsystem event arg0 arg1 arg2 arg3 flags
|
|
```
|
|
|
|
Header lines:
|
|
|
|
- must begin with `#`
|
|
- should identify source, scenario, and schema version
|
|
|
|
Example:
|
|
|
|
```text
|
|
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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
|