Re: [PATCH 4/4] doc: update instructions for running as non-root for MLX5

[Stephen Hemminger <stephen@networkplumber.org>]

On Wed, 8 Jun 2022 02:49:49 +0300
Dmitry Kozlyuk <dkozlyuk@nvidia.com> wrote:

> Reference the common guide for generic setup.
> Remove excessive capabilities from the recommended list.
> 
> Cc: stable@dpdk.org
> 
> Signed-off-by: Dmitry Kozlyuk <dkozlyuk@nvidia.com>
> ---
>  doc/guides/platform/mlx5.rst | 22 ++++++++++------------
>  1 file changed, 10 insertions(+), 12 deletions(-)


This change needs additional changes to make it correct English grammar.

> diff --git a/doc/guides/platform/mlx5.rst b/doc/guides/platform/mlx5.rst
> index 64a4c5e76e..956a72fadf 100644
> --- a/doc/guides/platform/mlx5.rst
> +++ b/doc/guides/platform/mlx5.rst
> @@ -404,25 +404,23 @@ The device can be bound again at this point.
>  Run as Non-Root
>  ^^^^^^^^^^^^^^^
>  
> -In order to run as a non-root user,
> -some capabilities must be granted to the application::
> +Hugepage and resource limit setup is documented

Subject is plural so verb must be plural => are documented

> +in the :ref:`common Linux guide <Running_Without_Root_Privileges>`.
> +This PMD does not require physical addresses,
> +so capability configuration is not needed to access hugepages.

In technical writing "therefore" is preferred over "so"
and you need a preposition. Please reword something like:

"This PMD does can operate without direct physical memory and hugepages
are not required."

Often applications will keep using hugepages (makes them NIC independent)
and in that case they would still need permissions.

> +Note that physical addresses may be required by other drivers.
>  
> -   setcap cap_sys_admin,cap_net_admin,cap_net_raw,cap_ipc_lock+ep <dpdk-app>
> +Additional capabilities must be granted to the application::
>  
> -Below are the reasons for the need of each capability:
> -
> -``cap_sys_admin``
> -   When using physical addresses (PA mode), with Linux >= 4.0,
> -   for access to ``/proc/self/pagemap``.
> +   setcap cap_net_raw,cap_net_admin,cap_sys_rawio+ep <executable>
>  
> -``cap_net_admin``
> -   For device configuration.
> +Below are the reasons for the need of each capability:
>  
>  ``cap_net_raw``
>     For raw ethernet queue allocation through kernel driver.
>  
> -``cap_ipc_lock``
> -   For DMA memory pinning.
> +``cap_net_admin``
> +   For device configuration, like setting link status or MTU.
>  

The most common usage for running as non-root is some container system.
In that case capabilities are managed by the container service (ie systemd, docker, etc)
and not done by setting filesystem capabilities.