diff options
| -rw-r--r-- | MAINTAINERS | 6 | ||||
| -rwxr-xr-x | devtools/check-spdx-tag.sh | 1 | ||||
| -rwxr-xr-x | devtools/linux-uapi.sh | 171 | ||||
| -rw-r--r-- | devtools/words-case.txt | 1 | ||||
| -rw-r--r-- | doc/guides/contributing/index.rst | 1 | ||||
| -rw-r--r-- | doc/guides/contributing/linux_uapi.rst | 70 | ||||
| -rw-r--r-- | kernel/linux/uapi/.gitignore | 4 | ||||
| -rw-r--r-- | kernel/linux/uapi/version | 1 | ||||
| -rw-r--r-- | meson.build | 8 |
9 files changed, 261 insertions, 2 deletions
diff --git a/MAINTAINERS b/MAINTAINERS index e25e9465b5..8919d78919 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -113,6 +113,12 @@ F: license/ F: .editorconfig F: .mailmap +Linux kernel uAPI headers +M: Maxime Coquelin <[email protected]> +F: devtools/linux-uapi.sh +F: doc/guides/contributing/linux_uapi.rst +F: kernel/linux/uapi/ + Build System M: Bruce Richardson <[email protected]> F: Makefile diff --git a/devtools/check-spdx-tag.sh b/devtools/check-spdx-tag.sh index 1ffccdaecc..b983268b1e 100755 --- a/devtools/check-spdx-tag.sh +++ b/devtools/check-spdx-tag.sh @@ -24,6 +24,7 @@ check_spdx() { ':^README' ':^MAINTAINERS' ':^VERSION' ':^ABI_VERSION' \ ':^*/Kbuild' ':^*/README*' \ ':^license/' ':^config/' ':^buildtools/' ':^*/poetry.lock' \ + ':^kernel/linux/uapi/.gitignore' ':^kernel/linux/uapi/version' \ ':^*.cocci' ':^*.abignore' \ ':^*.map' ':^*.ini' ':^*.data' ':^*.json' ':^*.cfg' ':^*.txt' \ ':^*.svg' ':^*.png' \ diff --git a/devtools/linux-uapi.sh b/devtools/linux-uapi.sh new file mode 100755 index 0000000000..ccd8b6816e --- /dev/null +++ b/devtools/linux-uapi.sh @@ -0,0 +1,171 @@ +#!/bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2024 Red Hat, Inc. + +# +# Import and check Linux Kernel uAPI headers +# + +base_url="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/include/uapi/" +base_path="kernel/linux/uapi/" +version="" +file="" +check_headers=0 +errors=0 + +print_usage() +{ + echo "Usage: $(basename $0) [-h] [-i FILE] [-u VERSION] [-c]" + echo "-i FILE import Linux header file. E.g. linux/vfio.h" + echo "-u VERSION update imported list of Linux headers to a given version. E.g. v6.10" + echo "-c check headers are valid" +} + +version_older_than() { + printf '%s\n%s' "$1" "$2" | sort -C -V +} + +download_header() +{ + local header=$1 + local path=$2 + + local url="${base_url}${header}?h=${version}" + + if ! curl -s -f --create-dirs -o $path $url; then + echo "Failed to download $url" + return 1 + fi + + return 0 +} + +update_headers() +{ + local header + local url + local path + + echo "Updating to $version" + for filename in $(find $base_path -name "*.h" -type f); do + header=${filename#$base_path} + download_header $header $filename || return 1 + done + + return 0 +} + +import_header() +{ + local include + local import + local header=$1 + + local path="${base_path}${header}" + + download_header $header $path || return 1 + + for include in $(sed -ne 's/^#include <\(.*\)>$/\1/p' $path); do + if [ ! -f "${base_path}${include}" ]; then + read -p "Import $include (y/n): " import && [ "$import" = 'y' ] || continue + echo "Importing $include for $path" + import_header "$include" || return 1 + fi + done + + return 0 +} + +fixup_includes() +{ + local path=$1 + + sed -i "s|^#include <linux/compiler.h>||g" $path + sed -i "s|\<__user[[:space:]]||" $path + + # Prepend include path with "uapi/" if the header is imported + for include in $(sed -ne 's/^#include <\(.*\)>$/\1/p' $path); do + if [ -f "${base_path}${include}" ]; then + sed -i "s|${include}|uapi/${include}|g" $path + fi + done +} + +check_header() { + echo -n "Checking $1... " + + if ! diff -q $1 $2 >/dev/null; then + echo "KO" + diff -u $1 $2 + return 1 + else + echo "OK" + fi + + return 0 +} + +while getopts i:u:ch opt ; do + case ${opt} in + i ) file=$OPTARG ;; + u ) version=$OPTARG ;; + c ) check_headers=1 ;; + h ) print_usage ; exit 0 ;; + ? ) print_usage ; exit 1 ;; + esac +done + +shift $(($OPTIND - 1)) +if [ $# -ne 0 ]; then + print_usage + exit 1 +fi + +cd $(dirname $0)/.. + +current_version=$(< ${base_path}/version) + +if [ -n "${version}" ]; then + if version_older_than "$version" "$current_version"; then + echo "Headers already up to date ($current_version >= $version)" + version=$current_version + else + update_headers || exit 1 + fi +else + echo "Version not specified, using current version ($current_version)" + version=$current_version +fi + +if [ -n "${file}" ]; then + import_header $file || exit 1 +fi + +for filename in $(find $base_path -name "*.h" -type f); do + fixup_includes $filename || exit 1 +done + +echo $version > ${base_path}/version + +if [ $check_headers -eq 0 ]; then + exit 0 +fi + +tmpheader="$(mktemp -t dpdk.checkuapi.XXXXXX)" +trap "rm -f '$tmpheader'" INT + +echo "Checking imported headers for version ${version}" + +for filename in $(find $base_path -name "*.h" -type f); do + header=${filename#$base_path} + download_header $header $tmpheader || exit 1 + fixup_includes $tmpheader || exit 1 + check_header $filename $tmpheader || errors=$((errors+1)) +done + +echo "$errors error(s) found" + +rm -f $tmpheader +trap - INT + +exit $errors diff --git a/devtools/words-case.txt b/devtools/words-case.txt index 2257ce6201..bc35c160ba 100644 --- a/devtools/words-case.txt +++ b/devtools/words-case.txt @@ -104,6 +104,7 @@ TPID TSO TTL Tx +uAPI UDM UDP ULP diff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst index 7fc6511361..7dc89b9afc 100644 --- a/doc/guides/contributing/index.rst +++ b/doc/guides/contributing/index.rst @@ -17,6 +17,7 @@ Contributor's Guidelines new_library new_driver patches + linux_uapi vulnerability stable cheatsheet diff --git a/doc/guides/contributing/linux_uapi.rst b/doc/guides/contributing/linux_uapi.rst new file mode 100644 index 0000000000..79bedb478e --- /dev/null +++ b/doc/guides/contributing/linux_uapi.rst @@ -0,0 +1,70 @@ +.. 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/linux-uapi.sh -i linux/vduse.h -u v6.10 + +Once imported, the header files should be committed without any other change. +Note that all the imported headers will be updated to the requested version. + +Updating imported headers to a newer released version should only be done on +a need basis, it can be achieved using the same script: + +.. code-block:: console + + devtools/linux-uapi.sh -u v6.10 + +The commit message should reflect why updating the headers is necessary. + +Once committed, user can check headers are valid by using the same Linux +uAPI script using the check option: + +.. code-block:: console + + devtools/linux-uapi.sh -c + +Note that all the linux-uapi.sh script options can be combined. For example: + +.. code-block:: console + + devtools/linux-uapi.sh -i linux/virtio_net.h -u v6.10 -c + +Header inclusion into library or driver +--------------------------------------- + +The library or driver willing to make use of imported uAPI headers needs to +explicitly include the header file with ``uapi/`` prefix in C files. +For example to include VDUSE uAPI: + +.. code-block:: c + + #include <uapi/linux/vduse.h> + diff --git a/kernel/linux/uapi/.gitignore b/kernel/linux/uapi/.gitignore new file mode 100644 index 0000000000..558ba597d6 --- /dev/null +++ b/kernel/linux/uapi/.gitignore @@ -0,0 +1,4 @@ +** +!**/ +!**/*.h +!version diff --git a/kernel/linux/uapi/version b/kernel/linux/uapi/version new file mode 100644 index 0000000000..2b256fd48f --- /dev/null +++ b/kernel/linux/uapi/version @@ -0,0 +1 @@ +v0.0 diff --git a/meson.build b/meson.build index fe9040369a..c59ab7430a 100644 --- a/meson.build +++ b/meson.build @@ -64,16 +64,20 @@ endif # configure the build, and make sure configs here and in config folder are # able to be included in any file. We also store a global array of include dirs # for passing to pmdinfogen scripts -global_inc = include_directories('.', 'config', +global_inc = [include_directories('.', 'config', 'lib/eal/include', 'lib/eal/@0@/include'.format(host_machine.system()), 'lib/eal/@0@/include'.format(arch_subdir), -) +)] # do configuration and get tool paths subdir('buildtools') subdir('config') +if is_linux + global_inc += include_directories('kernel/linux') +endif + # build libs and drivers subdir('lib') subdir('drivers') |