1 files changed, 139 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/docs/38-GSP-EM-API.md b/debug/risc-v-gsp-rm-vm/docs/38-GSP-EM-API.md
new file mode 100644
index 0000000..311e8e1
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/38-GSP-EM-API.md
@@ -0,0 +1,139 @@
+# 38 — GSP-Em API: TLV boundary between the GSP emulator and a full-system simulator
+
+> **Status:** design (2026-10-03). Implementation gated by the standalone
+> GSP simulator's validation gate (handoff-simulator.md §13.5/§14). The
+> bridge build flag `GREENEYE_GSP_EM_BRIDGE` is **OFF by default** until then.
+>
+> **Purpose:** define one stable, documented, TLV-framed protocol so the
+> standalone GSP emulator can be driven by (and drive) any full-system
+> simulator — GPGPU-Sim first, any API-compliant alternative later — without
+> either side depending on the other's internals.
+>
+> **See also:** `35-GREENEYE-SIMULATOR-DESIGN.md` §3.4/§4 (what is and is not
+> in Phase S vs Phase G) and `36-GSP-DEVICE-MODEL.md` (the device model behind
+> this API).
+
+## 1. Roles and boundary
+
+```
+ Standalone GSP emulator (this tool)            Full-system simulator (GPGPU-Sim or alternative)
+ ┌──────────────────────────────┐   GSP-Em API   ┌────────────────────────────────────────┐
+ │ real firmware · device model │◄──(TLV/UDS)───►│ SMs · caches · DRAM · fabric · host    │
+ │ MCUs · cycles · sessions     │                │ consumes/implements the same API       │
+ └──────────────────────────────┘                └────────────────────────────────────────┘
+```
+
+* The GSP emulator is the **authority** for GSP/device/MMIO semantics.
+* The system simulator is the **authority** for SM/memory/fabric timing.
+* Neither side parses the other's logs: all interaction is API messages.
+* Same API is used for A/B replay of captured QEMU/VFIO traffic.
+
+## 2. Transport and framing
+
+* Transport: UNIX `SOCK_SEQPACKET` (ordered, message-preserving) at a path
+  the caller supplies; shared-memory doorbell mode considered later, same
+  framing. Local only (never a network).
+* Every message is one frame: 16-byte header + payload. Little-endian.
+
+```
+header: magic 'G''S''E''1' (4B) | version u16 | flags u16 | seq u32 | type u16 | rsvd u16 | payload_len u32
+payload: repeated TLV fields
+TLV:    tag u16 | len u16 | value[len] (pad to 4B boundary with zeroes)
+```
+
+* Unknown TLVs MUST be ignored (forward compatibility). Unknown message types
+  MUST be answered with `E_UNIMPLEMENTED` unless `NO_REPLY` is set.
+* Version: major in header version; additive minor via `CAPS`. Breaking
+  changes require a new major and a shim.
+
+## 3. Message types
+
+| Type | Name | Direction | Payload essentials |
+|---|---|---|---|
+| 0x01 | HELLO | both | PROTO_MIN, PROTO_MAX, BUILD_HASH, FW_HASH, PROFILE_ID |
+| 0x02 | HELLO_ACK | both | selected version, session ID |
+| 0x03 | CAPS | both | CAP_MASK (bitmask), limits (max frame, max DMA), mode flags |
+| 0x10 | MMIO_READ | system→gsp | ADDR, SIZE, DEADLINE_CYCLE; reply: DATA or error |
+| 0x11 | MMIO_WRITE | system→gsp | ADDR, SIZE, DATA; reply: STATUS |
+| 0x12 | IRQ_RAISE | gsp→system | IRQ_VECTOR, DOMAIN, CYCLE |
+| 0x13 | DMA_READ | both | GSP_ADDR/PA, SYSTEM_ADDR, SIZE, DEADLINE_CYCLE |
+| 0x14 | DMA_WRITE | both | as above |
+| 0x15 | CLOCK_TICK | system→gsp | DOMAIN, CYCLE_DELTA; reply: CYCLE_NOW |
+| 0x16 | CLOCK_SYNC | both | EPOCH, GRANULARITY, MODE (free-run / credited) |
+| 0x17 | RESET | system→gsp | RESET_KIND (cold/warm/domain) |
+| 0x18 | STATE_SNAPSHOT | both | REGION selector; reply: STATE blob TLV (opaque, hashed) |
+| 0x19 | EVENT_SUBSCRIBE | system→gsp | MASK (mmio, dma, irq, mcu, trap, cycle) |
+| 0x1A | EVENT | gsp→system | EVENT_KIND + fields + CYCLE |
+| 0x7F | ERROR | both | STATUS, TEXT, ORIGINAL_TYPE, SEQ |
+| 0x7E | BYE | both | — |
+
+Common TLV tags: `ADDR u64`, `SIZE u32`, `DATA bytes`, `VALUE u64`,
+`STATUS u32`, `ERROR_CODE u32`, `TEXT utf8`, `CYCLE u64`, `DOMAIN u16`,
+`IRQ_VECTOR u32`, `CAP_MASK u64`, `PROFILE utf8`, `FW_HASH bytes32`,
+`BUILD_HASH bytes32`, `SESSION_ID bytes16`.
+
+## 4. Semantics
+
+* **Ordering:** per-domain FIFO; MMIO/DMA replies carry the `seq` of their
+  request. The system simulator may issue in-order per domain only; the GSP
+  emulator may reorder internally but must preserve observable order.
+* **Time:** in `credited` mode the system clock advances only by `CLOCK_TICK`
+  grants; the GSP emulator returns `CYCLE_NOW` so both sides share one
+  timeline. In `free-run` mode the emulator advances by its own modeled
+  cycles and reports them in events. Wall clock never enters a decision.
+* **State:** snapshots are opaque blobs with a hash; format is the emulator's
+  `greeneye-session/1` state section. A system simulator may store them but
+  not parse them.
+* **Determinism:** same inputs + same grants ⇒ byte-identical transcripts.
+  Every conformance run must demonstrate this twice.
+* **Security:** study environment only; no confidentiality claim; no message
+  may be used to defeat a hardware boundary (RUNBOOK P5).
+
+## 5. Error model
+
+`OK=0`, `E_UNIMPLEMENTED=1`, `E_RANGE=2`, `E_SIZE=3`, `E_STATE=4`,
+`E_BUSY=5`, `E_PROTO=6`, `E_TIMEOUT=7`, `E_DENIED=8`. An error never
+terminates the session; `BYE` is graceful. Timeouts are caller-budgeted.
+
+## 6. GPGPU-Sim bridge (first system simulator)
+
+* Build-time: `GREENEYE_GSP_EM_BRIDGE=1` compiles the adapter into the
+  overlay (`gpgpu-sim/overlay/`). Default OFF.
+* Runtime: `--gsp-em-endpoint <path>`; absent endpoint ⇒ GPGPU-Sim runs
+  standalone exactly as upstream (light-touch guarantee).
+* Adapter maps: BAR/MMIO trap → `MMIO_READ/WRITE`; GSP doorbell/IRQ →
+  `IRQ_RAISE`; firmware DMA descriptors → `DMA_*`; simulator clock domains →
+  `CLOCK_TICK/SYNC`.
+* The adapter is additive: no upstream data structure or algorithm is
+  modified; issues go through the existing device-model seam only.
+
+## 7. API-compliant backup (replacing GPGPU-Sim)
+
+The same API must allow a different system simulator (or a purpose-built
+service simulator) to take GPGPU-Sim's place:
+
+1. **Interface contract:** implement the *system side* of §2–§5 (client for
+   MMIO/DMA/IRQ, source for CLOCK_TICK, event consumer).
+2. **Conformance suite:** `gsp-em-conformance` replays golden transcripts
+   (hello/caps, MMIO R/W, IRQ, DMA, clock, snapshot, error paths) and must be
+   byte-identical twice. Any implementation passing it is interchangeable.
+3. **Replacement criteria:** passes conformance; sustains required
+   cycles/s and frame rates; preserves session hashes for the same stimulus;
+   no changes to the GSP emulator.
+4. **Build flag:** the system side selects implementation by
+   `GREENEYE_SYSTEM_SIM=gpgpu-sim|api-compliant-ref` (design; default
+   `gpgpu-sim`).
+
+## 8. Validation plan for this spec
+
+* Unit: frame codec round-trips, unknown-TLV tolerance, error mapping.
+* Integration: emulator ↔ stub system client; credited-clock determinism;
+  snapshot hash stability across runs.
+* Conformance harness is the acceptance gate for both the GPGPU-Sim bridge
+  and any backup implementation.
+
+## 9. Non-goals
+
+No remote/network use; no guest access; no hardware writes; no product
+dependency. This document specifies the boundary only; implementation is
+gated by the standalone simulator's value proof (handoff §14.5).