This directory contains a copy of the installed kernel headers
required by several drivers to communicate with the kernel.
Whenever one of those driver needs new definitions for new kernel
APIs, these files should be updated.

These files in upstream Mesa should only be updated once the changes
have landed in the drm-next branch of the drm repository.

The drm repository is currently located at:

 * https://gitlab.freedesktop.org/drm/kernel

 * git url: https://gitlab.freedesktop.org/drm/kernel.git

Tagged Linux kernel releases can also be used.

When using the drm repository, it is recommended that the headers are
generated using a *merge commit* in the drm-next branch. After
checking out the commit in the drm (or tagged Linux release) tree, the
drm-uapi files can be generated by running this from the drm tree:

$ make headers_install INSTALL_HDR_PATH=/path/to/install

This will generate files under /path/to/install/include/drm which can
be copied into the Mesa include/drm-uapi directory. It is not required
to copy/update all kernel header files.

The commit message for the Mesa drm-uapi update should include the
full commit version of the drm kernel tree. An easy way to generate
this is with the following command in the drm tree:

$ git log -1 --pretty=short --no-decorate

Which would produce output similar to this to include in the Mesa
commit:

commit a78313bb206e0c456a989f380c4cbd8af8af7c76
Merge: 365aa9f57399 79655e867ad6
Author: Dave Airlie <[email protected]>

    Merge tag 'drm-intel-gt-next-2024-06-12' of https://gitlab.freedesktop.org/drm/i915/kernel into drm-next