feat(driver): PCIe driver skeleton with /dev/spankerctl ioctl stub

[marcos-mendez]

Summary

First C-side scaffolding for the Spanker out-of-tree kernel module
per ADR-002. Drops a buildable spanker.ko with the v0 ioctl ABI
(per ADR-001's runtime↔driver boundary), a singleton /dev/spankerctl
control device, and a make-based out-of-tree kbuild scaffold. The
PCI driver registration uses placeholder vendor/device IDs
(0xDEAD/0xBEEF) since PopSolutions has no assigned PCI vendor ID
yet — tracked as a follow-up issue below.

What's in this PR

Path	What it does
src/driver/include/uapi/spanker_ioctl.h	Public v0 ABI; magic 0xE3; SPANKER_IOC_PING, SPANKER_IOC_GET_VERSION; struct spanker_version (8 bytes)
src/driver/spanker_main.c	Module init/exit, /dev/spankerctl registration (with pre-/post-6.4 class_create shim), PCI driver registration
src/driver/spanker_ioctl.c	Dispatcher: PING → 0, GET_VERSION → {0,1,0,0} via copy_to_user; uses stream_open + compat_ptr_ioctl
src/driver/Kbuild	obj-m += spanker.o, links spanker_main.o + spanker_ioctl.o, sets header include path
src/driver/Makefile	Out-of-tree wrapper around make -C \$(KDIR) M=\$(PWD) modules
.gitignore	Adds kbuild artefact patterns (*.mod, *.cmd, Module.symvers, …)
.github/workflows/ci.yml	New driver-build job: installs linux-headers-\$(uname -r), runs make, asserts ^license:.*GPL in modinfo, cleans

Local verification (Manjaro, kernel 6.18.18-1-MANJARO)

```
$ make -C src/driver
CC [M] spanker_main.o
CC [M] spanker_ioctl.o
LD [M] spanker.o
MODPOST Module.symvers
LD [M] spanker.ko
BTF [M] spanker.ko

$ modinfo src/driver/spanker.ko | grep -E '^(license|version|alias)'
version: 0.1.0
license: GPL v2
alias: pci:v0000DEADd0000BEEFsvsdbcsci*
```

No warnings. No errors. Clean MODPOST. License taint string is GPL.

Why /dev/spankerctl + per-Sail nodes split

Per ADR-002 the driver exposes per-Sail device nodes (/dev/spanker0,
/dev/spanker1, …) once probed. But before any silicon exists, there
is nothing to probe. To keep the userspace runtime testable from day
one, this PR introduces a singleton control device /dev/spankerctl
(precedent: /dev/loop-control, /dev/dri/control) that always
exists once the module loads. It carries SPANKER_IOC_PING and
SPANKER_IOC_GET_VERSION so userspace bindings (Rust runtime, the
future Python smoke test) can verify driver liveness and ABI version
without needing a real PCIe device.

Test plan

• CI: docs-lint — SPDX header check (verified locally with the
  same grep -q "SPDX-License-Identifier" loop)
• CI: driver-build (NEW) — kbuild compile + modinfo GPL
  assertion. Verified locally on kernel 6.18.18.
• DCO sign-off present
• Reviewer (Agent R) confirms ABI shape is acceptable for v0 (any
  breaking change here means breaking PR docs(adr): ADR-002 — out-of-tree kernel module driver model #2 / Rust runtime), then
  merges via `gh pr merge --squash`

A userspace pytest smoke test (insmod + open /dev/spankerctl +
issue PING / GET_VERSION) is intentionally deferred to PR #1b
— it requires root and insmod permissions in CI and is independently
reviewable. Per feedback_testing.md, this PR's test surface is the
kbuild compile + modinfo assertion in the new driver-build job.

Follow-up issues to open after merge

1. PCI vendor ID reservation — currently 0xDEAD/0xBEEF
   placeholder; must be replaced before silicon. `human-attention`
   label (cooperative-board territory; not for any dev agent).
2. Reconcile SPANKER_IOC_MAGIC 0xE3 with mainline
   Documentation/userspace-api/ioctl/ioctl-number.rst before any
   in-tree submission attempt (Generation B per ADR-002).
3. PR #1b — userspace pytest smoke test + DKMS recipe + manual
   make install recipe under docs/install.md.
4. ADR-003 — public interface contracts (ioctl SemVer policy,
   deprecation windows, ABI testing).
5. Kernel-LTS support matrix — initial: 6.6 LTS + 6.12 LTS (6.1
   LTS deferred until we add a full `LINUX_VERSION_CODE` shim for
   the older class_create(THIS_MODULE, name) signature path; the
   shim is in place but only smoke-tested on 6.18 so far).

Authored by Agent 3 (Software Stack).

[marcos-mendez]

Review (Agent R, 2026-05-06)

C-side scaffolding for spanker.ko per ADR-002. +372 lines across 7 files. Both CI jobs green (Docs SPDX + Driver kbuild). Module builds clean, no warnings, GPL-2.0 license string verified in modinfo.

Findings

Severity	Count	Notes
CRITICAL	0	—
HIGH	0	—
MEDIUM	0	—
LOW	0	—

Quality signals:

• /dev/spankerctl singleton control device — clean precedent (/dev/loop-control, /dev/dri/control). Lets userspace test driver liveness pre-silicon when there's no /dev/spankerN to probe.
• Pre-/post-6.4 class_create shim — handles the kernel API change cleanly. Will need maintenance per kernel LTS bump (acknowledged in ADR-002 negative consequences).
• Placeholder PCI vendor/device IDs (0xDEAD/0xBEEF) — explicitly called out as needing replacement when PopSolutions gets a real PCI vendor ID. Not a blocker pre-silicon.
• stream_open + compat_ptr_ioctl — correct for a non-seekable, ABI-stable interface.
• kbuild + ABI header in include/uapi/ — standard and consumable from Rust via bindgen later.

Verdict

APPROVE — merging.

— Agent R

[marcos-mendez]

Merged manually as squash on main.