Initial commit: retroDE_ps2 — first-of-its-kind PS2 GS FPGA core (DE25-Nano / Agilex 5)

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>

rtl/debug/trace_sink_stub.sv

@@ -0,0 +1,88 @@
+// retroDE_ps2 — trace_sink_stub
+//
+// Simulation-only text trace writer for Wave 1 stubs.
+//
+// Purpose, owns, success condition, replacement path: see
+//   docs/stub_module_plan.md  (Wave 1, item 1)
+//   docs/contracts/validation.md
+//   docs/decisions/0000-trace-format.md
+//
+// Interface shape:
+//   - One sink instance per output file. A testbench instantiates multiple
+//     sinks (one per stub under test) and wires each stub's event port to
+//     its own sink. Offline tooling merges files by cycle when needed.
+//   - The cycle counter is internal and advances on clk while rst_n is high.
+//     Multi-clock-domain correlation is a later-wave concern.
+//
+// Line format (docs/decisions/0000):
+//     cycle  subsys  event  arg0  arg1  arg2  arg3  flags
+//   where flags is rendered as `-` when zero.
+
+`timescale 1ns/1ps
+
+module trace_sink_stub
+    import trace_pkg::*;
+#(
+    parameter string FILENAME       = "trace.txt",
+    parameter int    SCHEMA_VERSION = 1,
+    parameter string SINK_LABEL     = "trace"
+) (
+    input  logic          clk,
+    input  logic          rst_n,
+
+    input  logic          ev_valid,
+    input  subsys_e       ev_subsys,
+    input  event_e        ev_event,
+    input  logic [63:0]   ev_arg0,
+    input  logic [63:0]   ev_arg1,
+    input  logic [63:0]   ev_arg2,
+    input  logic [63:0]   ev_arg3,
+    input  logic [31:0]   ev_flags
+);
+
+    integer          fd;
+    longint unsigned cycle_count;
+
+    initial begin
+        fd = $fopen(FILENAME, "w");
+        if (fd == 0) begin
+            $fatal(1, "[trace_sink_stub %0s] cannot open %0s", SINK_LABEL, FILENAME);
+        end
+        $fdisplay(fd, "# retroDE_ps2 trace, schema v%0d, sink=%0s",
+                  SCHEMA_VERSION, SINK_LABEL);
+        $fdisplay(fd, "# columns: cycle subsystem event arg0 arg1 arg2 arg3 flags");
+        cycle_count = 64'd0;
+    end
+
+    always_ff @(posedge clk) begin
+        if (!rst_n) begin
+            cycle_count <= 64'd0;
+        end else begin
+            cycle_count <= cycle_count + 64'd1;
+
+            if (ev_valid) begin
+                if (ev_flags == 32'd0) begin
+                    $fdisplay(fd,
+                              "%0d %0s %0s 0x%016h 0x%016h 0x%016h 0x%016h -",
+                              cycle_count,
+                              subsys_str(ev_subsys),
+                              event_str(ev_event),
+                              ev_arg0, ev_arg1, ev_arg2, ev_arg3);
+                end else begin
+                    $fdisplay(fd,
+                              "%0d %0s %0s 0x%016h 0x%016h 0x%016h 0x%016h 0x%08h",
+                              cycle_count,
+                              subsys_str(ev_subsys),
+                              event_str(ev_event),
+                              ev_arg0, ev_arg1, ev_arg2, ev_arg3,
+                              ev_flags);
+                end
+            end
+        end
+    end
+
+    final begin
+        if (fd != 0) $fclose(fd);
+    end
+
+endmodule : trace_sink_stub