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 A81B74591F; Fri, 6 Sep 2024 17:23:55 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A154C42F7A; Fri, 6 Sep 2024 17:23:52 +0200 (CEST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mails.dpdk.org (Postfix) with ESMTP id 59F3642F21 for ; Fri, 6 Sep 2024 17:23:50 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1725636229; 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=+/Fn00ZSAK5U1R6Ku11EvWcFanpyEWI7ddkHBuzFVeo=; b=LNRhUfDOjyAwfc9TlgQhEp7l4JVM5AoawMn7gsAoTFcCc9kfycHUOIRPvpjT73EhF0FpHx SFNNUZc4uB6dZXVnBlrp1oCgi8O8nkPEAJntVeprn3klLWOiQ05xqQnl4GWOq5/UOoCMDo 9tCLTVuRxi3zJBIGJSJ/fkwLkp3I6w4= Received: from mx-prod-mc-01.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-605-camHvkxMOXaFNzMDFz7npA-1; Fri, 06 Sep 2024 11:23:47 -0400 X-MC-Unique: camHvkxMOXaFNzMDFz7npA-1 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8C8D11955D4A; Fri, 6 Sep 2024 15:23:45 +0000 (UTC) Received: from max-p1.redhat.com (unknown [10.39.208.34]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D1E8C195608A; Fri, 6 Sep 2024 15:23:42 +0000 (UTC) From: Maxime Coquelin To: dev@dpdk.org, techboard@dpdk.org, david.marchand@redhat.com, thomas@monjalon.net, mb@smartsharesystems.com Cc: Maxime Coquelin Subject: [RFC v2 1/3] uapi: introduce kernel uAPI headers import Date: Fri, 6 Sep 2024 17:23:35 +0200 Message-ID: <20240906152337.2805036-2-maxime.coquelin@redhat.com> In-Reply-To: <20240906152337.2805036-1-maxime.coquelin@redhat.com> References: <20240906152337.2805036-1-maxime.coquelin@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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, and libraries and drivers have to explicitly enable their inclusion. 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 download and install a given header 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 | 74 +++++++++++++++++++++++++ devtools/import-linux-uapi.sh | 45 +++++++++++++++ doc/guides/contributing/index.rst | 1 + doc/guides/contributing/linux_uapi.rst | 77 ++++++++++++++++++++++++++ linux-headers/uapi/.gitignore | 3 + meson.build | 8 ++- 6 files changed, 206 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 diff --git a/devtools/check-linux-uapi.sh b/devtools/check-linux-uapi.sh new file mode 100755 index 0000000000..76111d78ce --- /dev/null +++ b/devtools/check-linux-uapi.sh @@ -0,0 +1,74 @@ +#!/bin/sh +# 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/" +errors=0 + +print_usage() +{ + echo "Usage: $(basename $0) [-h]" +} + +check_uapi_header() { + path=$1 + file=${1//"$base_path"/} + version=$(git log --format=%b -1 $path | sed -ne 's/^uAPI Version: \(.*\)$/\1/p') + + url="${base_url}${file}?h=${version}" + echo -n "Checking $file for version $version... " + curl -s -f -o $tmpinput $url + if [ $? -ne 0 ]; then + echo "Failed to download $url" + exit 1 + fi + + diff -q $path $tmpinput >/dev/null + if [ $? -ne 0 ]; then + echo "KO" + diff -u $path $tmpinput + 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)/.. + +tmpinput=$(mktemp -t dpdk.checkuapi.XXXXXX) +trap "rm -f '$tmpinput'" INT + +while IFS= read -d '' -r filename; do + check_uapi_header "${filename}" `_ +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 Version:`` tag and title MUST be prefixed with uapi keyword. +For example:: + + uapi: import VDUSE header file + + This patch imports VDUSE uAPI header file for inclusion + into the Vhost library. + + uAPI Version: v6.10 + + Signed-off-by: Alex Smith + +Updating an already imported header to a newer released version should only +be done on a need basis. +The commit message should reflect why updating the header is necessary. + +Once committed, user can check headers and commit message 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..88829d04e9 --- /dev/null +++ b/linux-headers/uapi/.gitignore @@ -0,0 +1,3 @@ +** +!**/ +!**/*.h 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