From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 42B5E45963; Wed, 11 Sep 2024 21:32:42 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id B18834060F; Wed, 11 Sep 2024 21:32:39 +0200 (CEST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mails.dpdk.org (Postfix) with ESMTP id 2371240609 for ; Wed, 11 Sep 2024 21:32:38 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1726083157; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ZzzzR8rzwVq3pelqA8b0ykb9eDcFvE+pHUINOw4Ht1A=; b=MjreB5H9t6R6psXZzF96m3fNVhvCZIIjzh2oChZuBLbmJKC7p84aNPk56CfpF0kNS5aLJy r+dTTFv/gifYu++z02qPOYqpzPw38YS5CsJNP/0Oa3urK65Rs2t0yK3N1BscAzGt+8IO2D HpYRvyePwzsg2CVU41Y3yF4+LKm1LYI= Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-460-COOZ82VhN5amcJtUBFYK5w-1; Wed, 11 Sep 2024 15:32:36 -0400 X-MC-Unique: COOZ82VhN5amcJtUBFYK5w-1 Received: from mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.40]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 5292E1944DE6; Wed, 11 Sep 2024 19:32:34 +0000 (UTC) Received: from max-p1.redhat.com (unknown [10.39.208.29]) by mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 59BB019560AD; Wed, 11 Sep 2024 19:32:31 +0000 (UTC) From: Maxime Coquelin To: dev@dpdk.org, techboard@dpdk.org, david.marchand@redhat.com, thomas@monjalon.net, mb@smartsharesystems.com, stephen@networkplumber.org Cc: Maxime Coquelin Subject: [RFC v3 1/3] uapi: introduce kernel uAPI headers import Date: Wed, 11 Sep 2024 21:32:22 +0200 Message-ID: <20240911193224.1966122-2-maxime.coquelin@redhat.com> In-Reply-To: <20240911193224.1966122-1-maxime.coquelin@redhat.com> References: <20240911193224.1966122-1-maxime.coquelin@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.40 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="US-ASCII"; x-default=true X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org This patch introduces uAPI headers import 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. Guidelines are provided in the documentation, and helper scripts are also provided to ensure proper importation of the header (unmodified content from a released Kernel version): - import-linux-uapi.sh: used to add and update headers and their dependencies to linux-headers/uapi/ - check-linux-uapi.sh: used to check all headers are valid Signed-off-by: Maxime Coquelin --- devtools/check-linux-uapi.sh | 85 ++++++++++++++++++ devtools/import-linux-uapi.sh | 119 +++++++++++++++++++++++++ doc/guides/contributing/index.rst | 1 + doc/guides/contributing/linux_uapi.rst | 71 +++++++++++++++ linux-headers/uapi/.gitignore | 4 + linux-headers/uapi/version | 1 + meson.build | 8 +- 7 files changed, 287 insertions(+), 2 deletions(-) create mode 100755 devtools/check-linux-uapi.sh create mode 100755 devtools/import-linux-uapi.sh create mode 100644 doc/guides/contributing/linux_uapi.rst create mode 100644 linux-headers/uapi/.gitignore create mode 100644 linux-headers/uapi/version diff --git a/devtools/check-linux-uapi.sh b/devtools/check-linux-uapi.sh new file mode 100755 index 0000000000..fc42c03169 --- /dev/null +++ b/devtools/check-linux-uapi.sh @@ -0,0 +1,85 @@ +#!/bin/sh +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2024 Red Hat, Inc. + +# +# Check Linux Kernel uAPI header files +# + +base_url="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/include/uapi/" +base_path="linux-headers/uapi/" +errors=0 +version="" + +print_usage() +{ + echo "Usage: $(basename $0) [-h]" +} + +check_uapi_header() { + path=$1 + file=${1#$base_path} + + cp -f $path $tmpinput1 + + # Restore includes fixups done by import-linux-uapi.sh + sed -i "s|//#include |#include |g" $tmpinput1 + sed -i "s|#include /dev/null + if [ $? -ne 0 ]; then + echo "KO" + diff -u $tmpinput1 $tmpinput2 + errors=$((errors+1)) + else + echo "OK" + fi +} + +while getopts hv ARG ; do + case $ARG in + 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)/.. + +tmpinput1=$(mktemp -t dpdk.checkuapi.XXXXXX) +tmpinput2=$(mktemp -t dpdk.checkuapi.XXXXXX) +trap "rm -f '$tmpinput1 $tmpinput2'" INT + +version=$(< ${base_path}/version) + +echo "Checking imported headers for version ${version}" + +for filename in $(find $base_path -name "*.h" -type f); do + check_uapi_header "${filename}" $/\1/p' $path); do + if [ ! -f "${base_path}${include}" ]; then + read -p "Import $include (y/n): " import < /dev/tty && [ "$import" = 'y' ] || continue + echo "Importing $include for $path" + import_header "$include" + fi + done +} + +fixup_includes() +{ + local path=$1 + + # Do not include linux/compiler.h as done by make headers + sed -i "s|^#include |//#include |g" $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 +} + +while getopts a:u:hv opt ; do + case ${opt} in + a ) + file=$OPTARG + ;; + u ) + version=$OPTARG + ;; + h ) + print_usage + exit 0 + ;; + ? ) + print_usage + exit 1 + ;; + esac +done + +cd $(dirname $0)/.. + +current_version=$(< ${base_path}/version) + +if [ -n "${version}" ]; then + version_valid "$version" "$current_version" + if [ $? -eq 0 ]; then + echo "Headers already up to date ($current_version >= $version)" + version=$current_version + else + update_headers + fi +else + echo "Version not specified, using current version ($current_version)" + version=$current_version +fi + +if [ -n "${file}" ]; then + import_header $file +fi + +for filename in $(find $base_path -name "*.h" -type f); do + fixup_includes "${filename}" ${base_path}/version 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..d4255eb22e --- /dev/null +++ b/doc/guides/contributing/linux_uapi.rst @@ -0,0 +1,71 @@ +.. 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 +`_ +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 -a 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/import-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 Linux uAPI +checker tool: + +.. code-block:: console + + ./devtools/check-linux-uapi.sh + +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 + diff --git a/linux-headers/uapi/.gitignore b/linux-headers/uapi/.gitignore new file mode 100644 index 0000000000..558ba597d6 --- /dev/null +++ b/linux-headers/uapi/.gitignore @@ -0,0 +1,4 @@ +** +!**/ +!**/*.h +!version diff --git a/linux-headers/uapi/version b/linux-headers/uapi/version new file mode 100644 index 0000000000..2b256fd48f --- /dev/null +++ b/linux-headers/uapi/version @@ -0,0 +1 @@ +v0.0 diff --git a/meson.build b/meson.build index 8b248d4505..aca47334ab 100644 --- a/meson.build +++ b/meson.build @@ -67,16 +67,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('linux-headers') +endif + # build libs and drivers subdir('lib') subdir('drivers') -- 2.46.0