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