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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
# 23 — RM 610 port readiness and approval gate
> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00-OVERVIEW for status.
> This document defines the gate, not a claim: readiness is **not** met today
> (2026-10-02). It exists so no one starts the port early.
**The RM 610 port begins only after explicit human approval.** That is a hard
gate, not a scheduling preference: until a named human approves it in writing,
nothing in this repository fetches, downloads, extracts or analyses a 610 GSP
firmware image, and no code or document treats 610 as an anchor or a supported
target. The gate is repeated in the sign-off checklist (§6) and is the first
thing the approval message must acknowledge.
## 1. Hard gate
| Rule | Meaning |
|---|---|
| No acquisition | No 610 runfile, GSP `.fwimage`, driver package or firmware blob is fetched, extracted, copied or mirrored before approval. |
| No analysis | No decompilation, symbol export, probe, corpus diff or pairing comparison against a 610 image before approval. |
| No emulation edits | No version-keyed handler, signature entry or profile edit justified by "610" before approval; changes require current-version evidence. |
| No physical-GPU work | No unsupervised physical-GPU cycle, mdev claim or driver bind/unbind for 610; the project rule is no unattended physical-GPU cycles (GREEN-EYE-ROADMAP H7). |
| No support claims | 610 is not entered in the hardware/software matrix or the version matrix until it passes the docs/22 port checklists with evidence. |
Precision notes:
* The pinned `nvidia-open-gpu-kernel-modules` checkout used as build glue
(recorded in `SBOM.md`) is **not** a GSP firmware image and is **not** a 610
port; it neither authorises acquisition nor counts as analysis.
* This document, docs/22 and the current-version test runs are the only
610-adjacent work permitted today. Everything else waits for approval.
* Approval is scoped and revocable: it covers named inputs and named
activities, on a named date, by a named approver.
### 1.1 What approval does and does not cover
| Approval covers | Approval does not cover |
|---|---|
| Acquiring the named 610 inputs through the named channel | Any other 610 artifact or channel not listed in the approval message |
| Analysis, probing, diffing and evidence capture on the 610 inputs | Merging an emulation change without the docs/22 A/B evidence |
| Running the docs/22 port workflow and the pipeline dry-run | Physical-GPU execution without a separate supervised plan |
| Publishing 610 evidence into the port log | Entering 610 as "Supported" in the matrix before validation |
| Re-asking for a scope extension | Retroactively blessing work done before approval |
An approval with an open-ended scope is invalid; ask again with the specific
inputs and activities. A denied or expired approval leaves the repo in the
state described in §5.
## 2. Readiness criteria (all must be true)
Every row must pass on the **current anchor** (570.144) before approval is even
requested. "All must be true" is literal: a single open item keeps the gate
closed.
| # | Criterion | How it is verified | Evidence | Status today |
|---|---|---|---|---|
| C1 | All tools implemented and tested on the current driver/firmware | full test suites green (documents/demo/probe/inject/Ghidra/harness) | test logs attached to the request | partial (MCP/CI missing) |
| C2 | Tests green | `make test` and the harness/rmharness suites pass | transcript with date and commit | green at v0.1 (55 tests) |
| C3 | Demo, probe, inject, Ghidra work | `./greeneye.sh demo`, `probe`, `inject`, `ghidra` all demonstrated | session dirs + transcript | working per docs/00 |
| C4 | MCP monitoring works | MCP plugin implemented and exercised (roadmap R3, docs/08; docs/15) | tool list + a monitored run | **not implemented (planned R3)** |
| C5 | CI pipeline works | release/CI pipeline implemented and exercised (planned docs/21) | pipeline run with artifacts | **not implemented (planned docs/21)** |
| C6 | Docs complete and accurate | doc review checklist (§3.2) signed | review record | to complete |
| C7 | Discovery/version-diff/CI exercised on the current version | control discovery (planned docs/19) + `harness/portability_matrix.py` + `compare` + pipeline dry-run on 570.144 | report + session hashes | partial (matrix/compare exist; docs/19 planned) |
| C8 | Harness produces a full evidence bundle | docs/07 checklist + docs/14 §6 pack produced end to end for a current-version port rehearsal | bundle directory with SHA-256 inventory | to complete |
| C9 | Human has approved | signed message (§6) | approval ID recorded in the request thread | pending |
C4 and C5 are the long poles. Do not silently downgrade them: if the human
chooses to waive a criterion, the waiver is written into the approval message
with its risk and the affected scope.
## 3. What "ready" looks like concretely
### 3.1 Exact commands that must pass
Run from `open-iov/debug/risc-v-gsp-rm-vm/` (docs/02 §8 has the make targets):
```bash
make demo
make test
python3 -m unittest tests.test_harness -v
python3 rmharness/tests/test_rmharness_plugin.py
./greeneye.sh info
./greeneye.sh demo
./greeneye.sh demo --backend native
./greeneye.sh probe
./greeneye.sh inject
./greeneye.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json
./greeneye.sh analyze dumps/<run> --symbols symbols-<ver>.json
./greeneye.sh compare dumps/<a> dumps/<b> --symbols
```
Plus, on the current version:
```bash
python3 harness/portability_matrix.py \
--target firmware/uproc_demo/build/uproc_demo.elf \
--target firmware/uproc_demo/build/uproc_demo.elf \
--out dumps/matrix-selfcheck
python3 harness/mutation_harness.py --out dumps/mutation-selfcheck \
--iterations 12 --seed 7
python3 harness/mutation_harness.py --out dumps/mutation-replay \
--iterations 12 --seed 7
```
Required results:
* every suite green, with installed QEMU; skips are explained, not ignored;
* `portability_matrix` self-comparison reports **zero deltas** (`all_zero`);
* mutation `findings.jsonl` is byte-identical between the two seeded runs;
* `greeneye compare` on two identical runs is empty;
* `analyze` renders a coherent session (hook/watch/breakpoint events, UART
banner liveness per docs/06 §7).
### 3.2 Doc review checklist
* [ ] 00–18 match the code on the current commit (commands, flags, status
tables, test counts);
* [ ] `docs/22` porting guide is accurate for the current tools; planned items
are labelled `planned (docs/xx)`;
* [ ] `docs/19-CONTROL-DISCOVERY.md` (planned) exists and has been run once on
the current version, or C7 is explicitly waived;
* [ ] `docs/21-CI-RELEASE-PIPELINE.md` (planned) exists and has run once on the
current version, or C5 is explicitly waived;
* [ ] `GREEN-EYE-ROADMAP.md` and `docs/08` status claims match reality;
* [ ] no local source paths, no invented command names, no unsupported
"supported/accurate" claims.
### 3.3 Golden sessions and regression data in place
* [ ] golden demo session(s) checked in or reproducible by a documented seed;
* [ ] matrix self-comparison zero-delta output archived;
* [ ] mutation replay corpus archived with its seed and budget;
* [ ] rmharness host-oracle captures for the current anchor archived
(`rmtool engine list --format=json`, `mem stats --format=json`);
* [ ] a full current-version evidence bundle (docs/07 checklist + docs/14 §6)
produced once, as the rehearsal for the 610 run.
## 4. Dry-run plan for the day of approval (no execution today)
Executed only after the approval in §6 exists. Steps 1–2 are acquisition and
must not happen beforehand.
1. **Confirm the approval.** Record approval ID, approver, date, scope and any
waived criterion in the port log.
2. **Obtain the 610 inputs through the approved channel.** The 610 driver
runfile and matching GSP `.fwimage` (or the approved firmware source) are
fetched through the channel named in the approval. Record the runfile
version, firmware hash (MD5/SHA-256), version string and image family
immediately; extract the `.fwimage` per docs/05-operations §4.1 step 1.
3. **Lay down versioned directories.** `firmware/<SERIES>-GSP/610/`,
`userspace/cuda/610/` (copied skeleton), `config/versions/610.yaml`
(documentation until the load path reads it). Never overwrite a working
version; keep 570.144 untouched.
4. **Pair and probe.** Build the 610 symbol DB (`analyze_fwimage.py`,
`symbols export --bias 0`), probe the 610 image and the 570.144 reference
with the same bounded settings, and diff the first-touch maps. Pairing
mismatch stops the run here.
5. **Baseline vs candidate orchestration.** Run
`harness/portability_matrix.py` with the 610 and 570.144 targets and
identical scenario options; run the mutation harness once per version with
the same seed; archive both reports and every session.
6. **Pipeline dry-run, then real.** Run the release pipeline (planned
docs/21-CI-RELEASE-PIPELINE.md) in its dry-run mode first; inspect the
planned artifact list without publishing. Only after the dry-run is clean,
run the real pipeline on the 610 evidence bundle.
7. **Expected artifacts.**
* approval record and input hashes;
* 610 symbol DB + Ghidra export provenance;
* probe reports (610 and reference) and the first-touch diff;
* `portability-report.json`/`.md`, per-pair compare reports, sessions;
* mutation `findings.jsonl` + summary for both versions;
* M1–M6 table with reference-capture method and L2/L3 limits;
* doc updates per docs/22 §3.5/§4 and the matrix entry (if and only if the
support claim is earned).
8. **Decision points.** Stop and keep the current anchor if: pairing is
ambiguous; any unexplained probe delta remains; the engine/RPC inventory
diff is not fully explained; M1–M6 regress on the current workload; the
evidence bundle is incomplete. Forward only when every delta has a decided
response.
9. **Rollback / keep-old-version rules.** The 570.144 directories,
configuration and guest driver stay untouched; rollback = return to the old
anchor commit/tag and the old guest driver (docs/05-operations §4.1 step 6).
A forward attempt never destroys the working setup; do not delete the old
version tree and do not reuse 570.144-derived addresses for 610.
## 5. What must NOT happen before approval
| Prohibited action | Why it is prohibited |
|---|---|
| Download/fetch 610 blobs or runfiles | Version discipline and evidence integrity: an unapproved input hash cannot anchor a later claim; acquisition is the act the gate exists to control. |
| Probe or decompile a 610 image | Analysis before readiness contaminates the evidence chain and tempts ad-hoc emulation edits. |
| Edit emulation code "for 610" | No current-version evidence justifies it; version-keyed handlers must be driven by a measured inventory diff (docs/05-operations §4.1 step 4). |
| Touch the physical GPU for 610 | Project hard rule: no unattended physical-GPU cycles; physical validation is a supervised step after approval. |
| Try the 610 driver in a guest | The guest never contains Open-IOV code and the anchor is fixed; an unpaired driver failure looks like an emulation bug (docs/07 P2.2). |
| Record 610 in the support/version matrix | Support means tested and documented; an untested entry violates the matrix contract (hardware-software-matrix §1/§6). |
| Treat the pinned open-module tag as approval | Build glue is not a GSP image and not an authorised port input (SBOM.md). |
Permitted before approval: reading this document and docs/22, running all
current-version tests, producing and archiving the current evidence bundle,
and preparing the approval request.
## 6. Sign-off checklist and approval message
### 6.1 Human sign-off (one page)
* [ ] **The RM 610 port begins only after explicit human approval.**
* [ ] C1–C9 all true, or each waiver is listed with its scope and risk.
* [ ] Test transcript attached (date, commit, `make test` green).
* [ ] `portability_matrix` self-comparison zero deltas; mutation replay
byte-identical.
* [ ] Doc review checklist (§3.2) complete.
* [ ] Current-version evidence bundle complete with SHA-256 inventory.
* [ ] Golden sessions/regression data in place (§3.3).
* [ ] Approval message (§6.2) sent and answered with an approval ID.
* [ ] Named approver accepts the acquisition scope and the permitted channel.
```
Approver: ______________________ Role: ______________________
Approval ID: ____________________ Date: ______________________
Scope limits / waivers: ________________________________________
Signature: ______________________
```
### 6.2 Approval request message (exact format)
Send exactly this shape; fill every `<...>` and leave "Waivers" as "none" if
empty:
```
RM 610 PORT APPROVAL REQUEST
Anchor today: 570.144 (firmware <sha256>; guest driver <md5>)
Target: RM 610 (requested input: <runfile version / approved source>)
Requested scope: acquire the 610 driver + GSP firmware through <approved
channel>; lay down versioned dirs; analyse, probe, diff, and run the docs/22
port workflow; no product change before A/B evidence.
Readiness, docs/23 §2:
C1 tools tested .......... <pass / waived>
C2 tests green ........... <pass / waived>
C3 demo/probe/inject/Ghidra <pass / waived>
C4 MCP monitoring ........ <pass / waived>
C5 CI pipeline ........... <pass / waived>
C6 docs complete ......... <pass / waived>
C7 discovery/diff/CI ..... <pass / waived>
C8 evidence bundle ....... <pass / waived>
C9 human approval ........ requested by this message
Waivers: <none / list with reason>
Evidence bundle: <path>
Commit: <git rev>; transcripts: <paths>
Signed: <name/role>, <date>
Decision (human): APPROVED / DENIED
Approval ID: <id>; Date: <date>; Scope limits: <text>
```
After approval, the 610 port proceeds only through the docs/22 workflow and
the docs/05-operations §4.1 version discipline. Until that message exists,
this repository is a 610 no-fly zone.
|
