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>
65 lines
2.1 KiB
Markdown
65 lines
2.1 KiB
Markdown
# 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
|
|
|
|
1. One shared tabular text format for everything.
|
|
2. Subsystem-specific text formats with no shared envelope.
|
|
3. Binary trace format from day one.
|
|
4. 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.
|