[TECH TOPIC] Crossing the Semantic Gap: Documenting Design Intent

["Chuck Wolber" <chuck@wolber.net>]

Hi All,

This is a joint topic proposal from Chuck Wolber, Gabriele Paoloni, and Kate
Stewart.

At LPC 2024 the session “Improving kernel design documentation and involving
experts” [1] discussed the need for enhancing and extending documentation of
kernel code. Since then, we have made initial submissions to introduce code
specifications into the TRACING subsystem [2][3], and later proposed a
guideline with a worked example in /drivers/char/mem.c [4], accompanied by
selftests traceable to these specifications. These are not intended as complete
solutions, but as baselines around which automation can be built. Experts from
other domains can develop code specifications within the kernel that will
create maintainable coupling between code, specification, and test.

The motivation is that without code specifications, integrators (i.e. those
making use of the Linux kernel) must guess at expected behavior by reading
code; developers spend longer understanding existing behavior before writing
patches; and testers risk interpreting bugs as features when writing tests. All
of these increase maintainer burden, since only review can catch such
misalignments.

Framed another way: writing code inevitably creates a semantic gap between
developer intent and code. Crossing that gap in the forward direction (intent →
code) is straightforward, but reversing it (code → intent) is lossy and relies
heavily on subsystem familiarity. This is the current practice today, but it
does not scale well, and it limits how tightly tests can be coupled to actual
design intent.

Our proposal is to continue exploring a lightweight adaptation of aerospace and
automotive design techniques, tailored to the Linux kernel development process,
to explicitly couple developer intent to code and test. The expected benefits
are technical debt reduction, long-term retention of semantic clarity, testing
that traces to actual design intent, and less time spent by maintainers
explaining nuanced behavior.

The goal of this discussion is to gather wider maintainer feedback on the value
of such specifications, and to chart possible next steps.


Best Regards,

Chuck Wolber
Gabriele Paoloni
Kate Stewart


[1] https://lpc.events/event/18/contributions/1894/
[2] https://lore.kernel.org/linux-trace-kernel/20250814122141.109076-1-gpaoloni@redhat.com/
[3] https://lore.kernel.org/linux-trace-kernel/20250814122206.109096-1-gpaoloni@redhat.com/
[4] https://lore.kernel.org/all/20250910170000.6475-1-gpaoloni@redhat.com/