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>
2.1 KiB
2.1 KiB
Decision 0000: Trace Format
Status: Locked
Context
Trace format is a required Phase 0 decision because every subsystem contract already depends on debug visibility, and those traces are much more useful if they share a known structure.
The project needs one format that is:
- simple enough to emit from early RTL stubs,
- simple enough to generate from emulator-side instrumentation,
- human-readable during bring-up,
- structured enough for automated diffs later.
Options considered
- One shared tabular text format for everything.
- Subsystem-specific text formats with no shared envelope.
- Binary trace format from day one.
- Common text envelope plus subsystem-specific payload fields.
Decision
Adopt a common text envelope plus subsystem-specific payload fields format for
Phase 0 and Phase 1.
The common envelope should include:
- cycle or monotonic timestamp,
- subsystem id,
- event type,
- schema/version id,
- payload fields encoded as self-describing key/value pairs or a stable column layout documented per subsystem.
Golden-reference traces should be normalized into the same envelope before
comparison. The trace files under sim/traces/ remain text during early bring-up.
Binary traces are deferred unless text traces become a demonstrated bottleneck.
Consequences
- Early traces stay readable in code review and terminal workflows.
- RTL stubs can emit useful traces before any heavy tooling exists.
- Emulator-side tooling has a clear normalization target.
- Different subsystems may still define different payload fields, but they must fit inside the same outer structure.
- If performance later requires binary traces, the project can add them behind the same logical schema rather than reinventing the event model.
Inputs to use when locking
docs/contracts/validation.md- per-subsystem "required debug visibility" sections in
docs/contracts/ sim/traces/README.md
Follow-up
- The stub-module plan should name the initial envelope fields explicitly.
- Subsystem contracts may later gain a short "trace payload schema" section once the first stubs are specified.