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 2885D4592F; Sat, 7 Sep 2024 16:34:31 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 34F3F4026F; Sat, 7 Sep 2024 16:34:29 +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 5CB6B40269 for ; Sat, 7 Sep 2024 16:34:28 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1725719667; 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=OtTSOwsvp8RprwWjYvy0XPUpEtMiS1G8TJhlSx6TSnw=; b=ItFnQCpCQaQqq2lyOdspLROp5prMcXlmGV6TH2GXE4c7xiliIBDkKDQvA20nBjuI4ujo3b WNfhRRLhnjguJipd0wnY/MU3OuOQnYnS7GDFixJBSlwzlKRGKQqE4jszEtGLBWjXvaYAfi vm75FeKI22p4n6f4USSxb6DtZFwQBow= Received: from mail-lf1-f70.google.com (mail-lf1-f70.google.com [209.85.167.70]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-375-seCFIxCJNbeDfv_k57Aigg-1; Sat, 07 Sep 2024 10:34:26 -0400 X-MC-Unique: seCFIxCJNbeDfv_k57Aigg-1 Received: by mail-lf1-f70.google.com with SMTP id 2adb3069b0e04-53661a13121so147256e87.0 for ; Sat, 07 Sep 2024 07:34:26 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1725719665; x=1726324465; 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=OtTSOwsvp8RprwWjYvy0XPUpEtMiS1G8TJhlSx6TSnw=; b=UMkV4uopL6I3OSFsGL5qmHUDvZBHi4dO2rXyqVNa64lGZAp89wacCFPIOv2smgYl3Q cquPeBKMjeTVbBaiVq4hdghsVr5JqW7b6+5oJxTGwadpfvX3vv77QY+456/FK/W0QCnu mWTJA6lC536pJy8+NyLjuugBTtyazpf1guzzsQ82BDRSR0S2OT3pfNHHS41de+A+0o9g YjZYm/G0femjSusHWt0wBtuAX+HCuKU/OAEtBtgcY3v7EdgwPOhYaK8giKPtKT6t025L /RFHWROuJjZ2h1eVZvc//4K/pROgkk/pg22tPTvdzkqAFq75F/csoCk4UmwBrgG34lLf tjHQ== X-Gm-Message-State: AOJu0YykCk4g/bxrrIsQwFJyAlLu/0xrWQ0drTMf70ZmgXXh+ise82aO FBCRf0K/2mn9AuSsA6XWCihUA2fUAuNnzds6f2+++QvMb/1a6NhpjEKhVu5BpIEZN7UXyaMOQgR jNrz0brBEmzB7B+nBJieZmk3Kqv0zLZgcU/6zzCia9PiPxqSzDgDGQ/ouhW1YC2QrdV/jrRr0pO ycUBmUyBPK9bLAhpg= X-Received: by 2002:a05:6512:3b8c:b0:52d:6663:5cbe with SMTP id 2adb3069b0e04-536587a67cdmr3962101e87.12.1725719664966; Sat, 07 Sep 2024 07:34:24 -0700 (PDT) X-Google-Smtp-Source: AGHT+IGK7DhUH2OBBfez/xEt4Xh0UgX+2dStosk1UB+ArpoEMeDVcURRNidt8HMqkHqv2Ao4O4DnuLcN22VLUDGpJLA= X-Received: by 2002:a05:6512:3b8c:b0:52d:6663:5cbe with SMTP id 2adb3069b0e04-536587a67cdmr3962090e87.12.1725719664252; Sat, 07 Sep 2024 07:34:24 -0700 (PDT) MIME-Version: 1.0 References: <20240906152337.2805036-1-maxime.coquelin@redhat.com> <20240906152337.2805036-2-maxime.coquelin@redhat.com> In-Reply-To: <20240906152337.2805036-2-maxime.coquelin@redhat.com> From: David Marchand Date: Sat, 7 Sep 2024 16:34:12 +0200 Message-ID: Subject: Re: [RFC v2 1/3] uapi: introduce kernel uAPI headers import To: Maxime Coquelin Cc: dev@dpdk.org, techboard@dpdk.org, thomas@monjalon.net, mb@smartsharesystems.com 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 5:23=E2=80=AFPM Maxime Coquelin wrote: [snip] > 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 -e maybe? > +# SPDX-License-Identifier: BSD-3-Clause > +# Copyright (c) 2024 Red Hat, Inc. > + > +# > +# Import Linux Kernel uAPI header file # Check Linux Kernel uAPI headers > +# > + > +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/" > +errors=3D0 > + > +print_usage() > +{ > + echo "Usage: $(basename $0) [-h]" > +} > + > +check_uapi_header() { > + path=3D$1 > + file=3D${1//"$base_path"/} I suspect it is a bashism. https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html ${parameter#[word]} Remove Smallest Prefix Pattern. The word shall be expanded to produce a pattern. The parameter expansion shall then result in parameter, with the smallest portion of the prefix matched by the pattern deleted. If present, word shall not begin with an unquoted '#'. So a POSIX alternative is: file=3D${1#$base_path/} > + version=3D$(git log --format=3D%b -1 $path | sed -ne 's/^uAPI Ver= sion: \(.*\)$/\1/p') I would add a check and raise a warning (error?) if extracting version fails (iow -z "$version"). > + > + url=3D"${base_url}${file}?h=3D${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=3D$((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=3D$(mktemp -t dpdk.checkuapi.XXXXXX) > +trap "rm -f '$tmpinput'" INT > + > +while IFS=3D read -d '' -r filename; do Simpler: for filename in $(find $base_path -name "*.h" -type f); do check_uapi_header "${filename}" + check_uapi_header "${filename}" +done < <(find $base_path -name "*.h" -type f -print0) > + > +echo "$errors error(s) found" > + > +rm -f $tmpinput > +trap - INT > + > +exit $errors [snip] > diff --git a/doc/guides/contributing/linux_uapi.rst b/doc/guides/contribu= ting/linux_uapi.rst > new file mode 100644 > index 0000000000..a3f684013a > --- /dev/null > +++ b/doc/guides/contributing/linux_uapi.rst > @@ -0,0 +1,77 @@ > +.. 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 > + > +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 Kernel uAPI headers enable to build features that are no= t > +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 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 o= nly > +be done on a need basis. > +The commit message should reflect why updating the header is necessary. +1. > + > +Once committed, user can check headers and commit message are valid by u= sing > +the Linux uAPI checker tool: > + > +.. code-block:: console > + > + ./devtools/check-linux-uapi.sh And thanks for adding this check. It will help maintainers. > + > +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 +=3D linux_uapi_inc Now that the uapi headers directory is pushed to global_inc, there is no need for this part in the doc. > + > +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/.gitignor= e > new file mode 100644 > index 0000000000..88829d04e9 > --- /dev/null > +++ b/linux-headers/uapi/.gitignore > @@ -0,0 +1,3 @@ > +** > +!**/ > +!**/*.h Nice trick to solve the per patch build issue :-). --=20 David Marchand