[dpdk-stable] patch 'doc: clarify instructions on running as non-root' has been queued to LTS release 18.11.11

[Kevin Traynor]

Hi,

FYI, your patch has been queued to LTS release 18.11.11

Note it hasn't been pushed to http://dpdk.org/browse/dpdk-stable yet.
It will be pushed if I get no objections before 12/16/20. So please
shout if anyone has objections.

Also note that after the patch there's a diff of the upstream commit vs the
patch applied to the branch. This will indicate if there was any rebasing
needed to apply to the stable branch. If there were code changes for rebasing
(ie: not only metadata diffs), please double check that the rebase was
correctly done.

Queued patches are on a temporary branch at:
https://github.com/kevintraynor/dpdk-stable-queue

This queued commit can be viewed at:
https://github.com/kevintraynor/dpdk-stable-queue/commit/05a0668483cbdf5ef15ee65078cc8fb9c83eabff

Thanks.

Kevin.

---
>From 05a0668483cbdf5ef15ee65078cc8fb9c83eabff Mon Sep 17 00:00:00 2001
From: Anatoly Burakov <anatoly.burakov at intel.com>
Date: Thu, 19 Nov 2020 10:52:44 +0000
Subject: [PATCH] doc: clarify instructions on running as non-root

[ upstream commit 3c3a861ce07e507dadda56091bc39cb92c3ae928 ]

The current instructions are slightly out of date when it comes to
providing information about setting up the system for using DPDK as
non-root, so update them.

Signed-off-by: Anatoly Burakov <anatoly.burakov at intel.com>
Reviewed-by: Ferruh Yigit <ferruh.yigit at intel.com>
Acked-by: Bruce Richardson <bruce.richardson at intel.com>
---
 doc/guides/linux_gsg/enable_func.rst | 58 ++++++++++++++++++++--------
 1 file changed, 41 insertions(+), 17 deletions(-)

diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/enable_func.rst
index ad11bc9e4e..459a952ce3 100644
--- a/doc/guides/linux_gsg/enable_func.rst
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -59,20 +59,49 @@ The application can then determine what action to take, if any, if the HPET is n
 
 Running DPDK Applications Without Root Privileges
---------------------------------------------------------
+-------------------------------------------------
+
+In order to run DPDK as non-root, the following Linux filesystem objects'
+permissions should be adjusted to ensure that the Linux account being used to
+run the DPDK application has access to them:
+
+*   All directories which serve as hugepage mount points, for example, ``/dev/hugepages``
+
+*   If the HPET is to be used,  ``/dev/hpet``
+
+When running as non-root user, there may be some additional resource limits
+that are imposed by the system. Specifically, the following resource limits may
+need to be adjusted in order to ensure normal DPDK operation:
+
+* RLIMIT_LOCKS (number of file locks that can be held by a process)
+
+* RLIMIT_NOFILE (number of open file descriptors that can be held open by a process)
+
+* RLIMIT_MEMLOCK (amount of pinned pages the process is allowed to have)
+
+The above limits can usually be adjusted by editing
+``/etc/security/limits.conf`` file, and rebooting.
+
+Additionally, depending on which kernel driver is in use, the relevant
+resources also should be accessible by the user running the DPDK application.
+
+For ``vfio-pci`` kernel driver, the following Linux file system objects'
+permissions should be adjusted:
+
+* The VFIO device file, ``/dev/vfio/vfio``
+
+* The directories under ``/dev/vfio`` that correspond to IOMMU group numbers of
+  devices intended to be used by DPDK, for example, ``/dev/vfio/50``
 
 .. note::
 
-    The instructions below will allow running DPDK as non-root with older
-    Linux kernel versions. However, since version 4.0, the kernel does not allow
-    unprivileged processes to read the physical address information from
-    the pagemaps file, making it impossible for those processes to use HW
-    devices which require physical addresses
+    The instructions below will allow running DPDK with ``igb_uio`` or
+    ``uio_pci_generic`` drivers as non-root with older Linux kernel versions.
+    However, since version 4.0, the kernel does not allow unprivileged processes
+    to read the physical address information from the pagemaps file, making it
+    impossible for those processes to be used by non-privileged users. In such
+    cases, using the VFIO driver is recommended.
 
-Although applications using the DPDK use network ports and other hardware resources directly,
-with a number of small permission adjustments it is possible to run these applications as a user other than "root".
-To do so, the ownership, or permissions, on the following Linux file system objects should be adjusted to ensure that
-the Linux user account being used to run the DPDK application has access to them:
-
-*   All directories which serve as hugepage mount points, for example,   ``/mnt/huge``
+For ``igb_uio`` or ``uio_pci_generic`` kernel drivers, the following Linux file
+system objects' permissions should be adjusted:
 
 *   The userspace-io device files in  ``/dev``, for example,  ``/dev/uio0``, ``/dev/uio1``, and so on
@@ -83,9 +112,4 @@ the Linux user account being used to run the DPDK application has access to them
        /sys/class/uio/uio0/device/resource*
 
-*   If the HPET is to be used,  ``/dev/hpet``
-
-.. note::
-
-    On some Linux installations, ``/dev/hugepages``  is also a hugepage mount point created by default.
 
 Power Management and Power Saving Functionality
-- 
2.26.2

---
  Diff of the applied patch vs upstream commit (please double-check if non-empty:
---
--- -	2020-12-15 12:52:22.066581852 +0000
+++ 0004-doc-clarify-instructions-on-running-as-non-root.patch	2020-12-15 12:52:21.952978730 +0000
@@ -1 +1 @@
-From 3c3a861ce07e507dadda56091bc39cb92c3ae928 Mon Sep 17 00:00:00 2001
+From 05a0668483cbdf5ef15ee65078cc8fb9c83eabff Mon Sep 17 00:00:00 2001
@@ -5,0 +6,2 @@
+[ upstream commit 3c3a861ce07e507dadda56091bc39cb92c3ae928 ]
+
@@ -10,2 +11,0 @@
-Cc: stable at dpdk.org
-
@@ -20 +20 @@
-index a2339a877b..45fd53ba36 100644
+index ad11bc9e4e..459a952ce3 100644
@@ -23 +23 @@
-@@ -61,20 +61,49 @@ The application can then determine what action to take, if any, if the HPET is n
+@@ -59,20 +59,49 @@ The application can then determine what action to take, if any, if the HPET is n
@@ -85 +85 @@
-@@ -85,9 +114,4 @@ the Linux user account being used to run the DPDK application has access to them
+@@ -83,9 +112,4 @@ the Linux user account being used to run the DPDK application has access to them