Torvalds rejects in-kernel API specification for Linux 7.4
He says structured comments next to kernel interfaces would pollute the source, and that any contract belongs outside the tree for tools rather than humans.
Linus Torvalds has refused a framework that would have written the contract of kernel interfaces into the Linux source itself, telling maintainer Sasha Levin that the in-kernel side is actively detrimental.
Levin asked Torvalds to take the work for the 7.4 merge window after more than a year of review, five early drafts from June 2025, and five further revisions this year. The series had sat in linux-next since early October. After it missed the first release candidate, Levin pinged twice and asked what, if anything, should change rather than sending the same request next cycle.
The proposal treated an interface's contract as something tools can check, not only as prose in man pages and comments. A structured comment next to the code would record valid arguments, error returns, calling context, locking, signals, capabilities, and side effects. The build would turn that into data embedded in the kernel image. From there a debug-only option could check system-call arguments and return values at runtime on some architectures, and a debug filesystem interface would expose the specs. Levin's case was that today's contracts exist only as text that nothing can verify.
Torvalds rejected that placement outright. He wrote that he does not think any of it should be inside the kernel, that the comments are too big, that nobody will read them, and that "the whole - and only - real use of them would be outside validation, not at run-time." He called huge comments that are not for humans pollution, and worse because the work is framed as a first step that would grow those comments further.
He was equally blunt about exposing the specs from a running kernel. A debug interface, he said, has no upside: nobody will read and compare specifications, and designing any of this around human checking is pointless. He also rejected the idea that the interface should be easy to update later, calling that the opposite of a stable API and something he does not want to make easier.
What he said can work is a specification kept outside the C sources, in a tools directory, in documentation, or in a separate repository, with scripts that validate it. He argued that the kernel API was never designed from a spec and has only grown over time, so the spec must match reality rather than the other way around. An initial spec, he suggested, should probably be generated by tools, including AI, then used to check later changes and to drive automated tests. Competent humans, he wrote, have better things to do than either phase.