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

[Maxime Coquelin <maxime.coquelin@redhat.com>]

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]"
+	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
+<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
+
+  This patch imports VDUSE uAPI header file.
+
+  uAPI Version: v6.10
+
+  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
+   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 <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
+
 # build libs and drivers
 subdir('lib')
 subdir('drivers')
-- 
2.46.0