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 AA2634591A; Fri, 6 Sep 2024 09:13:18 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 6A04F42EBD; Fri, 6 Sep 2024 09:13:18 +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 8755A4025D for ; Fri, 6 Sep 2024 09:13:17 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1725606797; 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=ay6folMfLaYyCOiGDqlhf0HWl3EKUbr3iJGULiVlqsI=; b=BSsGX7wudVg9Xa7IOIHk0kqTCvm5fIT330LGs4Uw4Sc5/tMwQZuP/ymSXQYf2E2FCbtVZP WPJsoxAU46InxpKb85RO3O65jZ3jBOBdnl3zNsYxghLz75fEbF5UqeuAtMBPCm4mupEpSw 2CxHB9DgcWEvZHS6B8nudSLNdS1H9fY= Received: from mail-lj1-f199.google.com (mail-lj1-f199.google.com [209.85.208.199]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-349-xe4-C7RMOFi5-eE-kSapIg-1; Fri, 06 Sep 2024 03:13:15 -0400 X-MC-Unique: xe4-C7RMOFi5-eE-kSapIg-1 Received: by mail-lj1-f199.google.com with SMTP id 38308e7fff4ca-2f3eda3d1cfso15882471fa.1 for ; Fri, 06 Sep 2024 00:13:15 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1725606794; x=1726211594; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=ay6folMfLaYyCOiGDqlhf0HWl3EKUbr3iJGULiVlqsI=; b=qMZxTFKP3KH2+WkfPDbecASeGNmNONYVYEDQg13QAJNfJUGGDue7E2x+S46lj/smSe TrMq0PboDavx3T7A9I/m2Rk9GH1soWBUFmzjNByRDIm7tGBaU4Sqkxrpq7V+E1NihXm0 CposLWAI/macv92qU1IA4fys51PnPDx5uPU5LYYyTiuTiWkL8vL4oqVmsKxmEcC6jIJ6 CwFH04tz5oy/4ZynfUZJ7Ubi2a4Qpfti6FIX+Usm5Yyt6dvByMTj7PK/G/yOUIgmpy4I fjikebnWQb6/8hSuSL6BQI0QBV0lp4zlj6pr/bMn8LUFl64NN/MMn6aLkAnNKB231Lam BDAA== X-Gm-Message-State: AOJu0YyEiR4liUUNM2pAMG/8bARYhXvBuwax0mJgm64sEKQDONkgS6nW /T3I7f9rEn4YVHkQf7zTW2aJBSTFn8AEoVvKZVCbM1Ha4OJHtck5FC+klVaRPLf/E0QaQJw+vzg SEivXChyJNN+LXd2BDJC+yff25goql55Ar+S80Mnlw4dupb2m9cmA8CkWTje5OboelZaIy8KY8M jf3HhOI6Vs6x5SAwc= X-Received: by 2002:a05:651c:541:b0:2ee:847f:9e9b with SMTP id 38308e7fff4ca-2f751f69e12mr9183111fa.28.1725606794069; Fri, 06 Sep 2024 00:13:14 -0700 (PDT) X-Google-Smtp-Source: AGHT+IF98c6An2YSjsQUswDYRictK4iMxTHGn/hGt0oAP96y4uYNNY+soRIxad3XtF4u63juoM3AU5Yxn8A4vHm7ry0= X-Received: by 2002:a05:651c:541:b0:2ee:847f:9e9b with SMTP id 38308e7fff4ca-2f751f69e12mr9182771fa.28.1725606793362; Fri, 06 Sep 2024 00:13:13 -0700 (PDT) MIME-Version: 1.0 References: <20240905221528.1861323-1-maxime.coquelin@redhat.com> <20240905221528.1861323-2-maxime.coquelin@redhat.com> In-Reply-To: <20240905221528.1861323-2-maxime.coquelin@redhat.com> From: David Marchand Date: Fri, 6 Sep 2024 09:13:01 +0200 Message-ID: Subject: Re: [RFC 1/3] uapi: introduce kernel uAPI headers importation To: Maxime Coquelin Cc: dev@dpdk.org, techboard@dpdk.org, thomas@monjalon.net X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 On Fri, Sep 6, 2024 at 12:15=E2=80=AFAM Maxime Coquelin wrote: > > 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/L= ICENSES/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.s= h > 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=3D"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin= ux.git/plain/include/uapi/" > +base_path=3D"linux-headers/uapi/" > + > +print_usage() > +{ > + echo "Usage: $(basename $0) [-h] [file] [version]" file and version are not optional. So they should not be surrounded with []. > + 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; For consistency with the rest of the script, don't use ; > +fi > + > +file=3D$1 > +version=3D$2 > + > +url=3D"${base_url}${file}?h=3D${version}" > +path=3D"${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" Can we rely on curl to report such errors? -f is probably the right option. @@ -37,12 +37,9 @@ path=3D"${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 +curl -s -f -o $path $url $ ./devtools/import-linux-uapi.sh linux/vdplop.h v6.10; echo $? 22 > + > +# Create path if needed > +mkdir -p $(dirname $path) > + > +# Download the file > +curl -s -o $path $url > + No need for a blank line at the end of the file. > 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/contribu= ting/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 > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > + Single empty line. > +Rationale > +--------- > + > +The system a DPDK library or driver is built on is not necessarily runni= ng the > +same Kernel version than the system that will run it. Importing Linux Ke= rnel Please start sentences on a new line. It won't affect the generated documentation and it slightly enhance readability, code churn when updating another sentence etc... > +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 li= ke to > +build a VDUSE application that will use VDUSE_IOTLB_GET_INFO ioctl() int= roduced > +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 fro= m 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 ch= ange, > +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 For the very first import of header lambda.h, ok. But can we make sure people will do better titles? Importing such headers must be done only when needed (maybe put some guidelines on this topic in the doc too?), and so the commit title should reflect the reason why DPDK needs an update. uapi: import awesome VDUSE feature definitions > + > + This patch imports VDUSE uAPI header file. > + > + uAPI Version: v6.10 uAPI ID ? > + > + 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 Missing an empty line here. > + includes +=3D linux_uapi_inc I would rather have this hidden in global_inc meson.build. > + > +Then, it can be included with ``uapi/`` prefix in C files. For example t= o > +include VDUSE uAPI: > + > +.. code-block:: c Missing an empty line here. > + #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 =3D include_directories('.', 'config', > subdir('buildtools') > subdir('config') > > +if is_linux > + linux_uapi_inc =3D include_directories('linux-headers') > +endif s/linux_uapi_inc/global_inc/. > + > # build libs and drivers > subdir('lib') > subdir('drivers') > -- > 2.46.0 > --=20 David Marchand