[RFC,1/3] uapi: introduce kernel uAPI headers importation

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 <maxime.coquelin@redhat.com>
---
 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
  

> From: Maxime Coquelin [mailto:maxime.coquelin@redhat.com]
> Sent: Friday, 6 September 2024 00.15
> 
> 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/LICENS
> ES/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 <maxime.coquelin@redhat.com>
> ---

Excellent solution, Maxime.

Minor suggestions and typos mentioned below.

Acked-by: Morten Brørup <mb@smartsharesystems.com>


> +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"

Suggest:
+	echo "Example of valid file: linux/vfio.h"
+	echo "Example of valid version: 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 ID:" -> "uAPI Version"
"keywork" -> "keyword"
  

On 9/6/24 08:46, Morten Brørup wrote:
>> From: Maxime Coquelin [mailto:maxime.coquelin@redhat.com]
>> Sent: Friday, 6 September 2024 00.15
>>
>> 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/LICENS
>> ES/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 <maxime.coquelin@redhat.com>
>> ---
> 
> Excellent solution, Maxime.
> 
> Minor suggestions and typos mentioned below.
> 
> Acked-by: Morten Brørup <mb@smartsharesystems.com>
> 

Thanks Morten, I'll fix below typos and several build failures caught by
CI in next revision.

>> +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"
> 
> Suggest:
> +	echo "Example of valid file: linux/vfio.h"
> +	echo "Example of valid version: 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 ID:" -> "uAPI Version"
> "keywork" -> "keyword"
>
  

On Fri, Sep 6, 2024 at 12:15 AM Maxime Coquelin
<maxime.coquelin@redhat.com> 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/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 <maxime.coquelin@redhat.com>
> ---
>  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]"

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=$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"

Can we rely on curl to report such errors?
-f is probably the right option.

@@ -37,12 +37,9 @@ 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
+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/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
> +=======================
> +
> +

Single empty line.


> +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

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 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
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/LICENSES/exceptions/Linux-syscall-note>`_
> +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

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 <alex.smith@example.com>
> +
> +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 += 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 to
> +include VDUSE uAPI:
> +
> +.. code-block:: c

Missing an empty line here.


> +   #include <uapi/linux/vduse.h>
> +
> 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

s/linux_uapi_inc/global_inc/.


> +
>  # build libs and drivers
>  subdir('lib')
>  subdir('drivers')
> --
> 2.46.0
>
  

On 9/6/24 09:13, David Marchand wrote:
> On Fri, Sep 6, 2024 at 12:15 AM Maxime Coquelin
> <maxime.coquelin@redhat.com> 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/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 <maxime.coquelin@redhat.com>
>> ---
>>   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]"
> 
> file and version are not optional.
> So they should not be surrounded with [].

Ok

> 
> 
>> +       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 ;

Ok

> 
>> +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"
> 
> Can we rely on curl to report such errors?
> -f is probably the right option.
> 
> @@ -37,12 +37,9 @@ 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
> +curl -s -f -o $path $url
> 
> $ ./devtools/import-linux-uapi.sh linux/vdplop.h v6.10; echo $?
> 22

OK, what about this to get rid of the mkdir?

diff --git a/devtools/import-linux-uapi.sh b/devtools/import-linux-uapi.sh
index efeffdd332..3769da80bb 100755
--- a/devtools/import-linux-uapi.sh
+++ b/devtools/import-linux-uapi.sh
@@ -37,12 +37,6 @@ 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
+curl -s -f --create-dirs -o $path $url


The only downside in both your version and this one is that versus 
initial one is that the directory gets created if curl failed.

We can though combine the best of both worlds:

$ git diff
diff --git a/devtools/import-linux-uapi.sh b/devtools/import-linux-uapi.sh
index efeffdd332..857d3dd33b 100755
--- a/devtools/import-linux-uapi.sh
+++ b/devtools/import-linux-uapi.sh
@@ -34,15 +34,9 @@ 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)
+# Check URL is valid
+curl -s -f -o /dev/null $url

  # Download the file
-curl -s -o $path $url
+curl -s -f --create-dirs -o $path $url

$ ./devtools/import-linux-uapi.sh linux/vduse.h v6.10
$ ./devtools/import-linux-uapi.sh linuxxx/vduse.h v6.10
$ find linux-headers/
linux-headers/
linux-headers/uapi
linux-headers/uapi/.gitignore
linux-headers/uapi/linux
linux-headers/uapi/linux/vduse.h


What do you prefer?

> 
> 
>> +
>> +# 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.

Ack

> 
>> 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
>> +=======================
>> +
>> +
> 
> Single empty line.

Ack

> 
>> +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
> 
> 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 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
>> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/LICENSES/exceptions/Linux-syscall-note>`_
>> +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
> 
> 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

I agree, I will update the guidelines to reflect this.

> 
> 
>> +
>> +  This patch imports VDUSE uAPI header file.
>> +
>> +  uAPI Version: v6.10
> 
> uAPI ID ?

Will fix. Prefer version than ID.

> 
>> +
>> +  Signed-off-by: Alex Smith <alex.smith@example.com>
>> +
>> +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.

OK, I think CI reported it.

> 
> 
>> +   includes += linux_uapi_inc
> 
> I would rather have this hidden in global_inc meson.build.

Ok, so to make it clear, you would be in favor of having these uAPI 
available to all libs and drivers as soon as it is a Linux build.

I'm fine with it, but wanted to make sure other reviewers are aware and
agree. Note that the includes will have to be prefixed with uapi/, so it
will not change the default behaviour for existing linux/ includes

>> +
>> +Then, it can be included with ``uapi/`` prefix in C files. For example to
>> +include VDUSE uAPI:
>> +
>> +.. code-block:: c
> 
> Missing an empty line here.

Ack

> 
>> +   #include <uapi/linux/vduse.h>
>> +
>> 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
> 
> s/linux_uapi_inc/global_inc/.

Ok.

I think I have some materials to post a second revision of the RFC, so 
that build failures are fixed.

Thanks,
Maxime

> 
>> +
>>   # build libs and drivers
>>   subdir('lib')
>>   subdir('drivers')
>> --
>> 2.46.0
>>
> 
>
  

On Fri,  6 Sep 2024 00:15:26 +0200
Maxime Coquelin <maxime.coquelin@redhat.com> 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/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 <maxime.coquelin@redhat.com>
> ---
>  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/"

Sorry, not a fan of this.

This must be optional. Most other projects don't do this and it risks
incompatibilities with the C library.



Did you make sure the headers are exactly the same as the distro uses (for the same kernel version).
Worried that this is not the exact same process that "make headers_install" might use.

Also, ideally the tool would be selective.
  

On 9/9/24 02:02, Stephen Hemminger wrote:
> On Fri,  6 Sep 2024 00:15:26 +0200
> Maxime Coquelin <maxime.coquelin@redhat.com> 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/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 <maxime.coquelin@redhat.com>
>> ---
>>   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/"
> 
> Sorry, not a fan of this.
> 
> This must be optional. Most other projects don't do this and it risks
> incompatibilities with the C library.

QEMU, libgpio at least do this.

Supporting new features is quite a mess in lib Vhost currently, because 
we cannot know what is and what is not defined in the build OS headers.
For example:
https://github.com/DPDK/dpdk/blob/main/lib/vhost/vhost.h#L369

> 
> 
> Did you make sure the headers are exactly the same as the distro uses (for the same kernel version).
> Worried that this is not the exact same process that "make headers_install" might use.

We could have them picked from make headers_install. It would be heavier
to do, but could be done if you see any difference.

> 
> Also, ideally the tool would be selective.
> 
Selective about what?

Note that this current RFC is too simplistic, it misses nested headers
import. Will try to cover this in nect revision.

Thanks,
Maxime