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 3A91B45963; Wed, 11 Sep 2024 21:55:35 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 232ED40289; Wed, 11 Sep 2024 21:55:35 +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 8704240151 for ; Wed, 11 Sep 2024 21:55:33 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1726084533; 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:autocrypt:autocrypt; bh=290M7EQT8N4W+6jiyCGjHURbOhiuCv52uqxQduhNM4U=; b=ic/7YmPrTGrBVeBHlGzoCCppNsaPUE4lKFd7ppvH88psmdjJKmkPGf8WWorPSCrIuYYe1m Wh5AqkHtaiTkDatg1OlDHmeYTiZ+xKqj4OCulP7SuMZxwIxXZmFBa0R4oRwv3zprx1Yf6R uf5MQszjfZThsVMB2AvEwj3SpfZEk68= Received: from mx-prod-mc-04.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-290-RYEuHOrtM2-IMeQTafvfww-1; Wed, 11 Sep 2024 15:55:29 -0400 X-MC-Unique: RYEuHOrtM2-IMeQTafvfww-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-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 3DE6619560AB; Wed, 11 Sep 2024 19:55:27 +0000 (UTC) Received: from [10.39.208.29] (unknown [10.39.208.29]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 18E141956088; Wed, 11 Sep 2024 19:55:24 +0000 (UTC) Message-ID: <45ed1421-1ad7-4757-9c7a-e49127199bb5@redhat.com> Date: Wed, 11 Sep 2024 21:55:22 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [RFC v2 1/3] uapi: introduce kernel uAPI headers import To: David Marchand , thomas@monjalon.net Cc: dev@dpdk.org, techboard@dpdk.org, mb@smartsharesystems.com References: <20240906152337.2805036-1-maxime.coquelin@redhat.com> <20240906152337.2805036-2-maxime.coquelin@redhat.com> From: Maxime Coquelin Autocrypt: addr=maxime.coquelin@redhat.com; keydata= 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 Mwqu3GQ= In-Reply-To: X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Language: en-US Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit 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 9/7/24 16:34, David Marchand wrote: > On Fri, Sep 6, 2024 at 5:23 PM 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? It will stop on first diff without reporting anything. At least on how it is done for now. >> +# 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="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"/} > > 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=${1#$base_path/} Changed to: file=${1#$base_path} > > >> + version=$(git log --format=%b -1 $path | sed -ne 's/^uAPI Version: \(.*\)$/\1/p') > > I would add a check and raise a warning (error?) if extracting version > fails (iow -z "$version"). It disappears in new version. > >> + >> + 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 > > Simpler: > > for filename in $(find $base_path -name "*.h" -type f); do > check_uapi_header "${filename}" done Done! > >> + 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/contributing/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 >> +======================= >> + >> +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 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. > > +1. > > >> + >> +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 > > And thanks for adding this check. > It will help maintainers. Welcome. Do you think we would need a sub-maintainer for this, or you prefere the main maintainers to take care of this? I'll be happy to help with the maintenance if you feel the need. > >> + >> +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 > > Now that the uapi headers directory is pushed to global_inc, there is > no need for this part in the doc. Right, I'm also adapting the commit message to reflect this. > >> + >> +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 > > Nice trick to solve the per patch build issue :-). :-) > Thanks, Maxime