# 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).