[PATCH v2 05/12] doc: improve Linux uAPI header documentation

Stephen Hemminger
2026-01-16T20:18:23Z

Improve clarity of the Linux uAPI header documentation
- Converting passive voice to active voice
- Simplifying sentence structure
- Making instructions more direct
- Removing redundant wording

No technical content changes.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
doc/guides/contributing/linux_uapi.rst | 40 ++++++++++++--------------
1 file changed, 19 insertions(+), 21 deletions(-)

diff --git a/doc/guides/contributing/linux_uapi.rst b/doc/guides/contributing/linux_uapi.rst
index a1bc0ba604..b28ebc4663 100644
--- a/doc/guides/contributing/linux_uapi.rst
+++ b/doc/guides/contributing/linux_uapi.rst
@@ -7,36 +7,34 @@ 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.
+The build system may run a different kernel version than the deployment target.
+To support features unavailable in the build system's kernel, import Linux kernel uAPI headers.

-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.
+For example, if the build system runs upstream Kernel v5.19, but you need to build a VDUSE application
+that uses the VDUSE_IOTLB_GET_INFO ioctl introduced in Kernel v6.0, importing the relevant uAPI headers enables this.
+
+The Linux kernel's syscall license exception permits the inclusion of unmodified uAPI header files in such cases.

`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.
+enables 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.
+To ensure that imported uAPI headers are unmodified and sourced from an official Linux
+kernel release, a helper script is provided and must be used.
Below is an example to import ``linux/vduse.h`` file from Linux ``v6.10``:

.. code-block:: console

devtools/linux-uapi.sh -i linux/vduse.h -u v6.10

-Once imported, the header files should be committed without any other change.
-Note that all the imported headers will be updated to the requested version.
+Once imported, commit header files without any modifications. Note that all imported
+headers are updated to match the specified kernel version.

-Updating imported headers to a newer released version should only be done on
-a need basis, it can be achieved using the same script:
+Perform updates to a newer released version only when necessary, using
+the same helper script.

.. code-block:: console

@@ -44,8 +42,8 @@ a need basis, it can be achieved using the same script:

The commit message should reflect why updating the headers is necessary.

-Once committed, user can check headers are valid by using the same Linux
-uAPI script using the check option:
+Once committed, check that headers are valid using the same Linux
+uAPI script with the check option:

.. code-block:: console

@@ -60,13 +58,13 @@ Note that all the linux-uapi.sh script options can be combined. For example:
Header inclusion into library or driver
---------------------------------------

-The library or driver willing to make use of imported uAPI headers needs to
-explicitly include the header file with ``uapi/`` prefix in C files.
+Libraries or drivers that rely on imported uAPI headers must explicitly include
+the relevant header using the ``uapi/`` prefix in their C source files.

This inclusion must be done before any header external to DPDK is included,
-to prevent inclusion of this system uAPI header in any of those external headers.
+to prevent inclusion of the system uAPI header in any of those external headers.

-For example to include VDUSE uAPI:
+For example, to include VDUSE uAPI:

.. code-block:: c

--
2.51.0