[4/4] doc: update instructions for running as non-root for MLX5
Checks
Commit Message
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(-)
Comments
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.
> From: Stephen Hemminger <stephen@networkplumber.org>
> Sent: Wednesday, June 8, 2022 3:14 AM
> [...]
> This change needs additional changes to make it correct English
> grammar.
Thank you for the useful comments to this and other patches.
I hope you don't mind that I took some sentences almost verbatim for v2.
> [...]
> > +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.
MLX5 PMD uses hugepages but does not use physical addresses
unlike most other HW drivers.
I tried to make it more clear in v2.
@@ -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
+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.
+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.
Windows Environment