1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
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).
|
