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 <[email protected]> --- 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
