# Code-standards remediation report — 2026-10-08

Branch: `ws/code-standards` (worktree `/tmp/opencode/wt-codestd`, base
`master` @ `3956a2f3`). Source of improvements:
`handoff-code-standards.txt` §4 (prioritized), items 1–5 of the task brief.
Scope limits honoured: no GPU/module/QEMU/guest/ssh operations, no CI
behaviour changes, no non-public-path prose in tracked files.

## Applied

| # | Item | Files | Commit |
|---|---|---|---|
| 1 | `.editorconfig` (root) + `.clang-format` for `kernel/`, `userspace/`, `tools/` | 4 | `c1b99f89` |
| 2 | `docs/07-developers/onboarding-and-standards.md` §3.2: real userspace C style + userspace rules | 1 | `1abab5b6` |
| 4 | Same doc, new §3.4: de facto commit/doc/config/SPDX conventions | (same commit) | `1abab5b6` |
| 3 | SPDX sweep: `userspace/` (ours), `tools/`, `scripts/` | 155 | `8367674c` |

Details:

* **Item 1 (config-only).** Root `.editorconfig` (UTF-8, LF, final newline,
  trim trailing whitespace; tabs for Makefiles and `kernel/**`, 4 spaces for
  `userspace/**` and `tools/**`). `kernel/.clang-format` is Linux kernel
  style (tabs, tab width 8, 80 columns, `BreakBeforeBraces: Linux`).
  `userspace/.clang-format` and `tools/.clang-format` are LLVM base, 4-space
  indent, 100 columns. Headers state that existing files are not to be
  mass-reformatted. All three files parse as YAML (checked; `clang-format`
  itself is not installed on this host).
* **Item 2.** §3.2 previously said "C: same style as the kernel module where
  practical" — contradicted by every userspace source (4-space indent, e.g.
  `libvgpu.c` 523 space-indented lines / 0 tabs). Rewritten to state the
  actual 4-space/~100-column style, naming (`snake_case`, `*_t`,
  `_LIBVGPU_H_` guards, `extern "C"`), status-type error handling
  (`vgpu_error_t`, `map_errno` at the syscall boundary, no `abort()` in
  libraries), the SPDX rule, and the shell `set -e` / `set -euo pipefail`
  practice.
* **Item 4.** New §3.4 records: commit messages
  (`<subsystem>: <description>`, issue refs `(ISSUE-0001)`), doc conventions
  (`> Status:` preamble + `<!-- change (YYYY-MM-DD): ... -->` markers,
  referencing `debug/risc-v-gsp-rm-vm/docs/`), `config/hardware` +
  `config/versions` and `firmware/<SERIES>-GSP/<MAJOR.MINOR>/` layouts, and
  the per-file SPDX enforcement point (BSD-3-Clause vs GPL-2.0).
* **Item 3.** 159 tracked sources under `userspace/`, `tools/`, `scripts/`
  lacked an SPDX identifier (none of the 20 `scripts/` files had one; 12
  were in `userspace/`; the remaining 127 in `tools/`). Added the minimal
  header to the 155
  that are ours — `/* ... */` for `.c`/`.h`, `# ...` for `.py`/`.sh`, after
  any shebang/coding line — plus `Copyright (c) 2026 Open-IOV contributors`,
  matching the existing line in `tools/gen_gsp_bindata.py`. Exactly 2 lines
  added per file, no other content touched (verified: 310 insertions, 0
  deletions). Shell files pass `bash -n`; the 56 Python files compile.
  * Excluded: `userspace/extern/{inc,src}` (4 files, vendored MIT) —
    relicensing third-party code would be wrong.
  * Note on the brief's "(0 in userspace)": the handoff actually reports
    "no SPDX headers at all in userspace/lib or userspace/tests"; live
    verification agreed (12 userspace files missing, 8 of them ours).
* Docs link checker (`scripts/check-docs-links.py`): 62 files, no broken
  relative links after the doc edit.

Changed-file counts: 4 + 1 + 155 + report = 161 files across the branch;
+125 / +48 / +310 lines (report excluded).

## Not applied (with reasons)

* **`kernel/**` SPDX sweep + `MODULE_LICENSE("GPL v2")` normalization** —
  explicitly out of scope for this branch ("do NOT touch kernel/** (record as
  follow-up)"). State at base: SPDX in 17/42 top-level kernel `.c`/`.h`
  files (22 incl. subdirs), 6× `MODULE_LICENSE("GPL")` and 1× `"GPL v2"`.
  Needs a GPL-2.0 pass of its own; recommend it as the next standards task.
* **CI enforcement (drop `|| true` for checkpatch/cppcheck, shellcheck +
  `.shellcheckrc`, SPDX-header check, ruff config)** — improvement #3, but
  the task's hard constraints forbid CI behaviour changes. Reported only
  (below) for a future PR.
* **Formatting `kernel/gsp_emulation.c` and `kernel/dynamic_rpc_dispatcher.c`**
  — improvement #1 allows "convert or record an explicit exemption"; this
  branch is config-only (no mass reformatting), so the configs carry the
  no-mass-reformat note and these two files remain outliers until a
  dedicated, behaviour-neutral formatting commit.
* **Root `CONTRIBUTING.md`** (improvement #8) — not among task items 1–5.
* **`userspace/extern/**`** — vendored MIT (cargs, tomlc99); identifiers
  intentionally left as upstream.
* **Study-material discipline (improvement #9)** — conventions for study
  material are recorded alongside that material, not in this public worktree.
* **greeneye session-format rules in tracked docs** (improvement #6, partial)
  — §3.4 covers commit/doc/config/SPDX conventions; the session-format rules
  already live in `debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md` and
  `26-ARCHITECTURE.md`, so they were not duplicated.

## CI findings (report-only, no changes)

Verified against `.github/workflows/ci.yml` and `kernel/tests/Makefile`.

1. **Kernel test modules built nowhere, insmodded anyway** —
   `.github/workflows/ci.yml:78` `sudo insmod
   gsp_vgpu_comprehensive_test.ko` (and `:81` rmmod); `:87`
   `gsp_vgpu_kunit_test.ko` (and `:90`); `:95` `gsp_vgpu_mock_test.ko` (and
   `:98`). None of these modules is produced: `kernel/tests/Makefile:1` has
   only `obj-m += gsp_emulation_test.o`. The `insmod` invocations fail the
   step (no `|| true`), so the `kernel-test` job cannot be green as written.
2. **Orphaned test source** — `kernel/tests/gsp_rpc_test.c` has no `obj-m`
   entry in `kernel/tests/Makefile`, so it is never compiled.
3. **Legacy guest-driver build** — `.github/workflows/ci.yml:69-70`
   `make -C driver KDIR=...`; there is no `driver/` directory in the
   repository (0 tracked files), so the step fails after `make kernel`
   succeeds.
4. **Advisory static analysis** — `.github/workflows/ci.yml:221`
   checkpatch ends with `|| true` and `:226` cppcheck ends with `|| true`;
   both can never fail the job (matches handoff §2.3).
5. **Note (intentional):** `.github/workflows/ci.yml:249` runs
   `./test_vgpu_userspace ... || true` with the comment "Expected to fail
   without driver, but should run" — documented behaviour, not a defect.

Suggested future PR (out of scope here): reconcile the test-module names or
build the missing modules, drop the `driver/` step, gate checkpatch/cppcheck
on changed files, and add shellcheck/SPDX checks.