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 DE10C45914; Fri, 6 Sep 2024 00:15:44 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7D1D942DDC; Fri, 6 Sep 2024 00:15:43 +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 5A7C542E69 for ; Fri, 6 Sep 2024 00:15:41 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1725574540; 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=zaY0u/qyb4UOLFWUc7JVxwkx4DHLJ7WgfLlwl4sCFl8=; b=A+eYWU+2fS+FDFIt83ZzAr4+llrlFjGKQ2N6rJe2q85RCxxr2b0mQap71SrYD8f7aUlSy/ z2vJ0dDTbQMMI1Z1mFKZkAGjxGV5ple4AQl8mkGfayCgZn2O56kOE31B4OrUP03jOo/wCN 87LoubWydAaI3jn//ZgGl0NdjlkK9ek= Received: from mx-prod-mc-05.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-53-k6GvF7OnMnOyyBXf9J4iKw-1; Thu, 05 Sep 2024 18:15:37 -0400 X-MC-Unique: k6GvF7OnMnOyyBXf9J4iKw-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-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B8F891956088; Thu, 5 Sep 2024 22:15:36 +0000 (UTC) Received: from max-p1.redhat.com (unknown [10.39.208.34]) by mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id EEAC21955F45; Thu, 5 Sep 2024 22:15:34 +0000 (UTC) From: Maxime Coquelin To: dev@dpdk.org, techboard@dpdk.org, david.marchand@redhat.com, thomas@monjalon.net Cc: Maxime Coquelin Subject: [RFC 1/3] uapi: introduce kernel uAPI headers importation Date: Fri, 6 Sep 2024 00:15:26 +0200 Message-ID: <20240905221528.1861323-2-maxime.coquelin@redhat.com> In-Reply-To: <20240905221528.1861323-1-maxime.coquelin@redhat.com> References: <20240905221528.1861323-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 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 --- 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 +`_ +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 + +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/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