Re: [PATCH] kbuild: add header check facility as a manually run static analyzer

[Thomas Weißschuh]

On 2026-09-16 16:13:19-0700, Nathan Chancellor wrote:
> On Wed, Sep 16, 2026 at 03:24:09PM -0700, Randy Dunlap wrote:
> > On 9/15/26 3:43 AM, Jani Nikula wrote:
> > > There have been various attempts at adding a header test or check
> > > mechanism in the kernel build system. The header check primarily
> > > consists of ensuring headers are self-contained, have include guards,
> > > and, in some cases, pass kernel-doc.
> > > 
> > > The main problems have been:
> > > 
> > > - The dependency tracking creates undesirable artefacts (infamously also
> > >   known as disgusting turds) in the build directory.
> > > 
> > > - Gating the feature behind a kconfig option is complicated due to
> > >   allyesconfig builds. It's possible, but requires a verbose and
> > >   confusing negative proxy config option.
> > > 
> > > - Naming the dependency tracking files with a dot prefix or placing them
> > >   in a dot prefixed subdirectory in the build directory to hide them has
> > >   been exceedingly difficult to achieve. (In part due to some Makefiles
> > >   building files in subdirectory hierarchies.)
> > > 
> > > - The debate which headers, if any, should really be self-contained is
> > >   virtually open-ended.
> > 
> > I would expect that headers in include/uapi/*.h should be self-contained,
> > but apparently that's just a pipe dream on my part, or maybe it's just
> > a maintainer option.
> > 
> > With 'make HEADER_CHECK="include/uapi/" headercheck'
> > I see over 70 errors (mostly typedefs or defined constants, but not only
> > those), such as:
> > 
> > In file included from <command-line>:
> > ./../include/uapi/linux/hdlc/ioctl.h:74:21: error: ‘IFNAMSIZ’ undeclared here (not in a function)
> >    74 |         char master[IFNAMSIZ];  /* Name of master FRAD device */
> >       |                     ^~~~~~~~
> > In file included from <command-line>:
> > ./../include/uapi/linux/input.h:29:6: warning: ‘__BITS_PER_LONG’ is not defined, evaluates to ‘0’ [-Wundef]
> >    29 | #if (__BITS_PER_LONG != 32 || !defined(__USE_TIME_BITS64)) && !defined(__KERNEL__)
> >       |      ^~~~~~~~~~~~~~~
> > ./../include/uapi/linux/input.h:34:9: error: unknown type name ‘__kernel_ulong_t’
> >    34 |         __kernel_ulong_t __sec;
> >       |         ^~~~~~~~~~~~~~~~
> > In file included from ./../include/uapi/linux/papr_pdsm.h:14,
> >                  from <command-line>:
> > ../include/linux/ndctl.h:19:33: error: ‘PAGE_SIZE’ undeclared here (not in a function)
> >    19 |         ND_MIN_NAMESPACE_SIZE = PAGE_SIZE,
> >       |                                 ^~~~~~~~~
> > In file included from <command-line>:
> > ./../include/uapi/linux/patchkey.h:15:2: error: #error "patchkey.h included directly"
> >    15 | #error "patchkey.h included directly"
> >       |  ^~~~~
> > In file included from <command-line>:
> > include/uapi/xen/gntdev.h:159:25: error: unknown type name ‘grant_ref_t’
> >   159 |                         grant_ref_t ref;
> >       |                         ^~~~~~~~~~~
> > include/uapi/xen/gntdev.h:161:25: error: unknown type name ‘domid_t’
> >   161 |                         domid_t domid;
> >       |                         ^~~~~~~
> 
> include/uapi already has its own header checking infrastructure under
> CONFIG_UAPI_HEADER_TEST and usr/include/Makefile, which avoids this with
> a no-header-test list that includes many of the files listed in these
> messages. To be honest, we should probably forbid HEADER_CHECK from
> including 'include/uapi' and refer people to use CONFIG_UAPI_HEADER_TEST
> instead, as there are other differences like being built under a
> different C standard or C++ and such that the existing infrastructure
> handles.

Testing the UAPI headers here too would still be valuable.
CONFIG_UAPI_HEADER_TEST tests the headers from the perspective of
userspace after they have undergone processing. The kernel build
might see the same headers quite differently.

For instance the example from above:

./../include/uapi/linux/input.h:29:6: warning: ‘__BITS_PER_LONG’ is not defined, evaluates to ‘0’ [-Wundef]
   29 | #if (__BITS_PER_LONG != 32 || !defined(__USE_TIME_BITS64)) && !defined(__KERNEL__)
      |      ^~~~~~~~~~~~~~~
./../include/uapi/linux/input.h:34:9: error: unknown type name ‘__kernel_ulong_t’
   34 |         __kernel_ulong_t __sec;
      |         ^~~~~~~~~~~~~~~~

These are legitimate issues, the inclusion of the necessary header is
gated behind #ifndef __KERNEL__ although it should not be.

(...)


Thomas