device-driver-development

Device Driver Development

Core Rule

Treat every driver task as hardware contract engineering: identify the kernel version, hardware bus, subsystem owner, execution context, lifetime model, and userspace ABI before writing code.

Knowledge Grounding

• Use references/knowledge-map.md for the driver domain map and conceptual model.
• Treat API details as version-sensitive; verify callback signatures, helpers, and bindings against the active kernel tree or current kernel docs.

First Pass

1. Classify the device: char, platform, I2C, SPI, regmap, IIO, GPIO, IRQ controller, input, RTC, PWM, regulator, framebuffer, or NIC.
2. Identify interface surfaces: /dev, sysfs, debugfs, ioctl, mmap, netdev, IIO buffers, input events, DT binding, or kernel consumer API.
3. Choose probe/remove lifetime: prefer devm_*, explicit unwind only when ordering or shared state requires it.
4. Decide concurrency boundaries: process context, atomic context, IRQ top half, threaded IRQ, workqueue, timer, DMA callback.
5. Define evidence needed: datasheet registers, bus transaction examples, DT node, logs, scope/logic-analyzer traces, and test plan.

Required Reads By Task

• New driver or hardware bring-up: tasks/bringup-workflow.md.
• Implementing subsystem callbacks: tasks/implementation-patterns.md and references/subsystem-matrix.md.
• Memory, MMIO, mmap, DMA, IRQ, locking: references/kernel-engineering-principles.md.
• Debugging, validation, or intermittent behavior: tasks/debugging-testing.md.
• Toolchain, QEMU, KGDB, bpftrace, Smatch, Coccinelle, Syzkaller, Bootlin: references/tooling-matrix.md.
• Auditable engineering flow: tasks/step-verify-workflow.md.
• Upstream-ready patches or long-term maintenance: tasks/upstream-maintenance.md.
• Final review before handoff: references/review-checklist.md.

Design Heuristics

• Prefer an existing kernel subsystem over a private char driver when the device matches a framework.
• Keep policy in userspace and mechanism in kernel; avoid inventing ABI without necessity.
• Never sleep in atomic context; never hold spinlocks across bus calls that may sleep.
• Use copy_{to,from}_user() only at ABI boundaries and handle partial copy/error paths.
• For MMIO use devm_ioremap_resource() plus accessor APIs; do not dereference __iomem.
• For register devices on I2C/SPI, consider regmap before custom read/write helpers.
• For DT, model hardware, not Linux driver internals; document compatibles and supplies/clocks/IRQs/GPIOs.

Script Helpers

• Run scripts/driver_static_scan.py <path> for heuristic review of C, Kconfig, Makefile, DTS, and binding files.
• Run scripts/module_smoke_build.sh <module-dir> [kernel-build-dir] for out-of-tree build smoke checks.
• Run scripts/tooling_probe.sh to inspect local build, static-analysis, tracing, fuzzing, QEMU, and KGDB tool availability.

Verification Gate

• Build with warnings enabled and, when available, sparse, Smatch, Coccinelle, checkpatch.pl, dt_binding_check, and subsystem selftests.
• Test load/unload, probe/remove failure paths, hot/unplug or unbind where applicable, suspend/resume if resources are power-managed.
• Capture runtime evidence: dmesg, /proc/interrupts, sysfs state, tracepoints/ftrace/bpftrace, bus transactions, and userspace API results.
• Use QEMU/KGDB for isolated crash reproduction and Syzkaller for fuzzable ABI surfaces when practical.
• Do not claim correctness from compilation alone; tie each claim to a code path, runtime observation, or documented subsystem contract.

Output Standard

When answering, name assumptions, selected subsystem, key APIs, file layout, validation commands, and residual hardware risks. If source evidence is missing, say what must be measured or read next.