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

[Stephen Hemminger <stephen@networkplumber.org>]

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