[PATCH 1/9] tools/include: Sync uapi/drm/i915_drm.h with the kernel sources

[Jani Nikula]

On Tue, 09 Apr 2024, Ingo Molnar <mingo at kernel.org> wrote:
> * Jani Nikula <jani.nikula at linux.intel.com> wrote:
>
>> On Mon, 08 Apr 2024, Namhyung Kim <namhyung at kernel.org> wrote:
>> > To pick up changes from:
>> >
>> >    b112364867499 ("drm/i915: Add GuC submission interface version query")
>> >    5cf0fbf763741 ("drm/i915: Add some boring kerneldoc")
>> >
>> > This should be used to beautify DRM syscall arguments and it addresses
>> > these tools/perf build warnings:
>> >
>> >   Warning: Kernel ABI header differences:
>> >     diff -u tools/include/uapi/drm/i915_drm.h include/uapi/drm/i915_drm.h
>> 
>> All these years and I never realized there are header copies
>> there. But... why copies?
>
> It's better than all the alternatives we tried so far:
>
>  - Symbolic links and direct #includes: this was the original approach but 
>    was pushed back on from the kernel side, when tooling modified the 
>    headers and broke them accidentally for kernel builds.
>
>  - Duplicate self-defined ABI headers like glibc: double the maintenance 
>    burden, double the chance for mistakes, plus there's no tech-driven 
>    notification mechanism to look at new kernel side changes.
>
> What we are doing now is a third option:
>
>  - A software-enforced copy-on-write mechanism of kernel headers to 
>    tooling, driven by non-fatal warnings on the tooling side build when 
>    kernel headers get modified:
>
>     Warning: Kernel ABI header differences:
>       diff -u tools/include/uapi/drm/i915_drm.h include/uapi/drm/i915_drm.h
>       diff -u tools/include/uapi/linux/fs.h include/uapi/linux/fs.h
>       diff -u tools/include/uapi/linux/kvm.h include/uapi/linux/kvm.h
>       ...
>
>    The tooling policy is to always pick up the kernel side headers as-is, 
>    and integate them into the tooling build. The warnings above serve as a 
>    notification to tooling maintainers that there's changes on the kernel 
>    side.
>
> We've been using this for many years now, and it might seem hacky, but 
> works surprisingly well.
>
> Does this make sense to you?

Yes, although there are probably pieces of the puzzle I'm missing.
Thanks for the explanation! (That might work almost as-is copied to
tools/include/uapi/README. ;)

It's also kind of funny to find this kind of back alleys of the kernel
repo I've never wandered to before.

BR,
Jani.

-- 
Jani Nikula, Intel