radres-sens1

A tiny piece of designed-from-scratch virtual hardware and its Linux kernel driver, built end-to-end:

1. Hardware design — SPEC.md: the RADRES SENS-1, a PCI card with a temperature sensor, an RNG, a DMA engine and one interrupt (INTx/MSI).
2. Hardware implementation — qemu/radres-sens.c: a QEMU device model of the card (the "silicon").
3. Driver — driver/radres-sens1.c: a Linux PCI driver exposing the sensor via hwmon (temp1_input) and the RNG via hwrng (/dev/hwrng), using the DMA engine + completion interrupt for bulk entropy reads.
4. Proof — a self-testing guest: Alpine linux-virt kernel + busybox initramfs that probes the driver and exercises every feature, booted on a virt aarch64 machine under the patched QEMU.

Build & run

# 1. hardware: patch + build QEMU (any recent release; tested with 11.0.2)
./qemu/install-into-qemu.sh /path/to/qemu-src
# configure --target-list=aarch64-softmmu && make

# 2. driver + guest image (needs Docker)
docker run --rm -v "$PWD:/work" alpine:latest sh /work/guest/build-in-alpine.sh

# 3. boot the self-test
./run-test.sh

Expected tail of output: === ALL TESTS PASSED ===.

Register map (short version)

Off	Reg		Off	Reg
0x00	ID (0x52530100)		0x18	RNG32
0x04	CTRL (EN/IRQ_EN/RESET)		0x1c	SAMPLE_PERIOD_MS
0x08	STATUS		0x20/24	DMA_ADDR lo/hi
0x0c	IRQ_STATUS		0x28	DMA_LEN
0x10	IRQ_ACK (W1C)		0x2c	DMA_CMD (START)
0x14	TEMP (m°C)

Full semantics in SPEC.md.

The path to upstream (read this before dreaming)

Mainline Linux only merges drivers for hardware that actually exists for users — and for virtual hardware that means the device model must be upstream in QEMU first. That is a real, well-trodden path (this is how edu-style and various QEMU test devices came to be), and this repo is structured for it:

1. QEMU side first: get a device ID formally reserved in docs/specs/pci-ids.rst (ours, 1b36:0e51, is squatted and must be allocated properly), add a spec under docs/specs/, post the device model to qemu-devel. QEMU explicitly welcomes educational/test devices — but expect review to question what SENS-1 offers over edu.
2. Kernel side second: once the device exists in an upstream QEMU release, the driver can be proposed to the hwmon and char/hw_random maintainers (get_maintainer.pl, one patch per subsystem, checkpatch clean — the driver here follows kernel style for that reason).

Realistically, the highest-value kernel contribution from this exercise is the skills: the same register/IRQ/DMA/hwmon/hwrng patterns apply directly to fixing and extending real in-tree drivers.

License

GPL-2.0-or-later (both the device model and the driver).