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
|
# Developer Onboarding, Standards, and Tools
> Everything a new contributor needs: what to read, how to build and test, how
> we write code, and how to land a change.
## 1. Your first day
### 1.1 Reading order (about 3 hours)
1. [`../README.md`](../README.md) — the project front door (20 min).
2. [`../01-orientation/01-purpose-and-scope.md`](../01-orientation/01-purpose-and-scope.md)
and [`../01-orientation/02-the-ai-edge-and-ecosystem.md`](../01-orientation/02-the-ai-edge-and-ecosystem.md)
— why the project exists (30 min).
3. [`../03-architecture/01-system-overview.md`](../03-architecture/01-system-overview.md)
— the architecture in one document (30 min).
4. [`../03-architecture/06-host-module-and-hybrid-model.md`](../03-architecture/06-host-module-and-hybrid-model.md)
— where the code lives (30 min).
5. [`../04-implementation/01-known-knowns-and-unknowns.md`](../04-implementation/01-known-knowns-and-unknowns.md)
— what to work on and what is hard (30 min).
6. The subsystem doc for whatever you plan to touch.
### 1.2 Environment
```bash
git clone https://git.vgpu.io/open-iov.git
cd open-iov
./install.sh deps nvidia firmware build # full setup
./scripts/stack_manager.sh up # + load + create mdev
./scripts/stack_manager.sh test # host test suite
```
You will need: a supported NVIDIA GPU, IOMMU-enabled host, hugepages, kernel
headers, QEMU, and (for guest work) a Linux guest with the stock driver.
### 1.3 The daily loop
```bash
make kernel # kernel module (generates Module.symvers)
./scripts/stack_manager.sh build-kernel
./scripts/stack_manager.sh load-open-iov
./scripts/stack_manager.sh mdev-create
./scripts/vgpu_vm.py start vgpu-linux
# guest work ...
./scripts/stack_manager.sh dmesg # live trace
```
When you change kernel code, remember: reload requires removing the mdev and
the VM holding it. The stack manager enforces the order.
## 2. Repository map
```
open-iov/
├── kernel/ host module (GSP emulation, device model, memory model)
├── userspace/ management library + examples
├── tools/ debugging and analysis tools (guest-diag, rmq,
│ firmware analysis wrappers)
├── scripts/ build/load/test automation, VM harness
├── config/ hardware/version profiles (the portability surface)
├── firmware/ versioned firmware images + decompilation artifacts
├── (private) reverse-engineering study notes live untracked;
│ see the maintainers' study index
├── docs/ THIS documentation tree (start at docs/README.md)
└── wiki/ long-form firmware/protocol deep dives
```
## 3. Coding standards
### 3.1 Kernel module (`kernel/`)
* Linux kernel C style (tabs, 80-column-ish, `checkpatch` clean where
practical).
* **No comments explaining *what* the code does — comments explain *why*,
especially protocol quirks.** Our code encodes observations from hardware;
the observation must be recorded next to the code that depends on it.
* Every handler logs its request/reply in a reconstructible form (the
trace-first policy). A handler that silently succeeds is an anti-pattern.
* Never trust guest input: validate sizes, handles, indices, and sequences.
A malformed element must not be able to steer a write outside guest memory.
* Memory: `kmalloc`/`vzalloc` per the use; DMA access through the hypervisor
interface only.
* Error paths: fail closed, log once with context, and give up the device
cleanly.
### 3.2 Userspace and tools (`userspace/`, `tools/`, `scripts/`)
* C: same style as the kernel module where practical.
* Python/shell: `shellcheck` clean shell, `python3` with no exotic
dependencies; scripts must be re-runnable and idempotent.
* Tools must live **in-tree** (never in `/tmp`) so they survive reboots and
are reviewable.
### 3.3 Documentation
* Every behaviour change updates the doc that describes it. Docs are part of
the definition of done.
* Prefer a table or a decision tree over prose for anything an operator will
follow under pressure.
* Protocol facts (IDs, offsets, structures) must cite their source
(the decompiled study notes, or a live trace).
## 4. Tooling
| Tool | Purpose |
|---|---|
| `scripts/stack_manager.sh` | build/load/status/test/unload with correct ordering |
| `scripts/vgpu_vm.py` | VM lifecycle incl. guest-agent exec/shell |
| `tools/guest-diag/` | guest-side diagnostics (ptrace tracer, engines, probes, push helper) |
| `tools/firmware_analyzer.py` + Ghidra scripts | firmware analysis pipeline |
| module debug parameters | guest-memory scanning/poking, VRAM inspection |
| QEMU gdbstub workflow | guest virtual-memory inspection/writing |
| `wiki/` documents | protocol and firmware deep dives |
## 5. Landing a change
1. **Pick from the known-unknowns list** or a bug with a reproduction.
2. **Reproduce** with the standard captures; write the decision tree if new.
3. **Implement** with tests: host-side unit tests where possible; a scripted
guest scenario where not.
4. **Evidence**: attach the rung-ladder result (see the evaluation doc) and
the before/after trace excerpt.
5. **Docs**: update the affected documents (including the known-unknowns entry
if you closed one).
6. **Review**: a reviewer must be able to reproduce your evidence from the
PR description alone.
## 6. Makefile targets
```bash
make kernel # open-iov-vfio.ko (first!)
make nvidia # NVIDIA OpenRM modules with KBUILD_EXTRA_SYMBOLS
make userspace # libiov.so, examples
make all # in the correct order
make clean
```
## 7. Testing discipline
* Kernel changes: at minimum, load/unload cycle ×3, mdev create/destroy, and a
guest boot + `nvidia-smi`.
* Protocol changes: diff the RPC inventory before/after; attach both.
* Memory-model changes: re-run the VA↔PA discovery tooling and a guest CUDA
start-up; attach the trace.
* Never land a change that makes a rung regress, even "temporarily".
## 8. Security hygiene for contributors
* Do not add code paths that map or copy memory outside the hypervisor-provided
DMA interface.
* Treat guest input as hostile; treat debug parameters as privileged.
* If you add a debug surface, document it in the debugging doc and gate it.
* If you discover a protocol fact that implies a security-relevant assumption
(e.g. "the guest can ask us to write anywhere"), stop and escalate: it is a
design issue, not a code issue.
## 9. Getting unstuck
* Start with the guest's own diagnostics (it is the oracle).
* Then the host trace; the answer is almost always in the last RPC before the
failure.
* Then memory observation (scan/poke) — but write down what you learn; the
next person needs it.
* Ask in the project channels with a *reproduction*, not a summary.
|
