1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2024 Red Hat, Inc. 3 4Linux uAPI header files 5======================= 6 7Rationale 8--------- 9 10The system a DPDK library or driver is built on is not necessarily running the 11same Kernel version than the system that will run it. 12Importing Linux Kernel uAPI headers enable to build features that are not 13supported yet by the build system. 14 15For example, the build system runs upstream Kernel v5.19 and we would like to 16build a VDUSE application that will use VDUSE_IOTLB_GET_INFO ioctl() introduced 17in Linux Kernel v6.0. 18 19`Linux Kernel licence exception regarding syscalls 20<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/LICENSES/exceptions/Linux-syscall-note>`_ 21enable importing unmodified Linux Kernel uAPI header files. 22 23Importing or updating an uAPI header file 24----------------------------------------- 25 26In order to ensure the imported uAPI headers are both unmodified and from a 27released version of the linux Kernel, a helper script is made available and 28MUST be used. 29Below is an example to import ``linux/vduse.h`` file from Linux ``v6.10``: 30 31.. code-block:: console 32 33 devtools/linux-uapi.sh -i linux/vduse.h -u v6.10 34 35Once imported, the header files should be committed without any other change. 36Note that all the imported headers will be updated to the requested version. 37 38Updating imported headers to a newer released version should only be done on 39a need basis, it can be achieved using the same script: 40 41.. code-block:: console 42 43 devtools/linux-uapi.sh -u v6.10 44 45The commit message should reflect why updating the headers is necessary. 46 47Once committed, user can check headers are valid by using the same Linux 48uAPI script using the check option: 49 50.. code-block:: console 51 52 devtools/linux-uapi.sh -c 53 54Note that all the linux-uapi.sh script options can be combined. For example: 55 56.. code-block:: console 57 58 devtools/linux-uapi.sh -i linux/virtio_net.h -u v6.10 -c 59 60Header inclusion into library or driver 61--------------------------------------- 62 63The library or driver willing to make use of imported uAPI headers needs to 64explicitly include the header file with ``uapi/`` prefix in C files. 65For example to include VDUSE uAPI: 66 67.. code-block:: c 68 69 #include <uapi/linux/vduse.h> 70 71