This patch introduces uAPI headers importation into the DPDK repository. This import is possible thanks to Linux Kernel licence exception for syscalls:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/LICENSES/exceptions/Linux-syscall-note Header files are have to be explicitly imported, and libraries and drivers have to explicitly enable their inclusion. Guidelines are provided in the documentation, and a helper script is also provided to ensure proper importation of the header (unmodified content from a released Kernel version). Next version will introduce a script to check headers are valids. Signed-off-by: Maxime Coquelin <maxime.coque...@redhat.com> --- devtools/import-linux-uapi.sh | 48 ++++++++++++++++++++ doc/guides/contributing/index.rst | 1 + doc/guides/contributing/linux_uapi.rst | 63 ++++++++++++++++++++++++++ meson.build | 4 ++ 4 files changed, 116 insertions(+) create mode 100755 devtools/import-linux-uapi.sh create mode 100644 doc/guides/contributing/linux_uapi.rst diff --git a/devtools/import-linux-uapi.sh b/devtools/import-linux-uapi.sh new file mode 100755 index 0000000000..efeffdd332 --- /dev/null +++ b/devtools/import-linux-uapi.sh @@ -0,0 +1,48 @@ +#!/bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2024 Red Hat, Inc. + +# +# Import Linux Kernel uAPI header file +# + +base_url="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/include/uapi/"; +base_path="linux-headers/uapi/" + +print_usage() +{ + echo "Usage: $(basename $0) [-h] [file] [version]" + echo "Example of valid file is linux/vfio.h" + echo "Example of valid version is v6.10" +} + +while getopts hv ARG ; do + case $ARG in + h ) print_usage; exit 0 ;; + ? ) print_usage; exit 1 ;; + esac +done +shift $(($OPTIND - 1)) + +if [ $# -ne 2 ]; then + print_usage; exit 1; +fi + +file=$1 +version=$2 + +url="${base_url}${file}?h=${version}" +path="${base_path}${file}" + +# Move to the root of the DPDK tree +cd $(dirname $0)/.. + +# Check file and version are valid +curl -s -o /dev/null -w "%{http_code}" $url | grep -q "200" + +# Create path if needed +mkdir -p $(dirname $path) + +# Download the file +curl -s -o $path $url + diff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst index dcb9b1fbf0..603dc72654 100644 --- a/doc/guides/contributing/index.rst +++ b/doc/guides/contributing/index.rst @@ -19,3 +19,4 @@ Contributor's Guidelines vulnerability stable cheatsheet + linux_uapi diff --git a/doc/guides/contributing/linux_uapi.rst b/doc/guides/contributing/linux_uapi.rst new file mode 100644 index 0000000000..3bfd05eb62 --- /dev/null +++ b/doc/guides/contributing/linux_uapi.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2024 Red Hat, Inc. + +Linux uAPI header files +======================= + + +Rationale +--------- + +The system a DPDK library or driver is built on is not necessarily running the +same Kernel version than the system that will run it. Importing Linux Kernel +uAPI headers enable to build features that are not supported yet by the build +system. + +For example, the build system runs upstream Kernel v5.19 and we would like to +build a VDUSE application that will use VDUSE_IOTLB_GET_INFO ioctl() introduced +in Linux Kernel v6.0. + +`Linux Kernel licence exception regarding syscalls +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/LICENSES/exceptions/Linux-syscall-note>`_ +enable importing unmodified Linux Kernel uAPI header files. + +Importing or updating an uAPI header file +----------------------------------------- + +In order to ensure the imported uAPI headers are both unmodified and from a +released version of the linux Kernel, a helper script is made available and +MUST be used. Below is an example to import ``linux/vduse.h`` file from Linux +``v6.10``: + +.. code-block:: console + + ./devtools/import-linux-uapi.sh linux/vduse.h v6.10 + +Once imported, the header files should be committed without any other change, +and the commit message MUST specify the imported version using ``uAPI ID:`` +tag and title MUST be prefixed with uapi keywork. For example:: + + uapi: import VDUSE header file + + This patch imports VDUSE uAPI header file. + + uAPI Version: v6.10 + + Signed-off-by: Alex Smith <alex.sm...@example.com> + +Header inclusion into library or driver +--------------------------------------- + +The library or driver willing to make use of imported uAPI headers needs to +explicitly add uAPI headers path to the ``includes`` var in its ``meson.build`` +file: + +.. code-block:: python + includes += linux_uapi_inc + +Then, it can be included with ``uapi/`` prefix in C files. For example to +include VDUSE uAPI: + +.. code-block:: c + #include <uapi/linux/vduse.h> + diff --git a/meson.build b/meson.build index 8b248d4505..53cdaef558 100644 --- a/meson.build +++ b/meson.build @@ -77,6 +77,10 @@ global_inc = include_directories('.', 'config', subdir('buildtools') subdir('config') +if is_linux + linux_uapi_inc = include_directories('linux-headers') +endif + # build libs and drivers subdir('lib') subdir('drivers') -- 2.46.0
