Since DPDK now has support for the in-tree uio_pci_generic driver,
update the GSG document to reference this module, and to use it
in preference to the igb_uio driver, which is DPDK-specific.
Signed-off-by: Bruce Richardson <bruce.richardson at intel.com>
---
doc/guides/linux_gsg/build_dpdk.rst | 63 +++++++++++++++++-------------
doc/guides/linux_gsg/build_sample_apps.rst | 5 ++-
doc/guides/linux_gsg/enable_func.rst | 2 +
3 files changed, 40 insertions(+), 30 deletions(-)
diff --git a/doc/guides/linux_gsg/build_dpdk.rst
b/doc/guides/linux_gsg/build_dpdk.rst
index d09c69d..255d6dc 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -133,7 +133,8 @@ use the make config T=<target> command:
.. warning::
- The igb_uio module must be compiled with the same kernel as the one
running on the target.
+ Any kernel modules to be used, e.g. igb_uio, kni, must be compiled with the
+ same kernel as the one running on the target.
If the DPDK is not being built on the target machine,
the RTE_KERNELDIR environment variable should be used to point the
compilation at a copy of the kernel version to be used on the target machine.
@@ -154,28 +155,29 @@ Browsing the Installed DPDK Environment Target
Once a target is created it contains all libraries and header files for the
DPDK environment that are required to build customer applications.
In addition, the test and testpmd applications are built under the build/app
directory, which may be used for testing.
-In the case of Linux, a kmod directory is also present that contains a module
to install:
+A kmod directory is also present that contains kernel modules which may be
loaded if needed:
.. code-block:: console
$ ls x86_64-native-linuxapp-gcc
app build hostapp include kmod lib Makefile
-Loading the DPDK igb_uio Module
--------------------------------
+Loading Modules to Enable Userspace IO for DPDK
+-----------------------------------------------
-To run any DPDK application, the igb_uio module can be loaded into the running
kernel.
-The module is found in the kmod sub-directory of the DPDK target directory.
-This module should be loaded using the insmod command as shown below (assuming
that the current directory is the DPDK target directory).
-In many cases, the uio support in the Linux* kernel is compiled as a module
rather than as part of the kernel,
-so it is often necessary to load the uio module first:
+To run any DPDK application, a suitable uio module can be loaded into the
running kernel.
+In most cases, the standard uio_pci_generic module included in the linux kernel
+can provide the uio capability. This module can be loaded using the command
.. code-block:: console
- sudo modprobe uio
- sudo insmod kmod/igb_uio.ko
+ sudo modprobe uio_pci_generic
-Since DPDK release 1.7 provides VFIO support, compilation and use of igb_uio
module has become optional for platforms that support using VFIO.
+As an alternative to the uio_pci_generic, the DPDK also includes the igb_uio
+module which can be found in the kmod subdirectory referred to above.
+
+Since DPDK release 1.7 onward provides VFIO support, use of UIO is optional
+for platforms that support using VFIO.
Loading VFIO Module
-------------------
@@ -195,24 +197,29 @@ Also, to use VFIO, both kernel and BIOS must support and
be configured to use IO
For proper operation of VFIO when running DPDK applications as a
non-privileged user, correct permissions should also be set up.
This can be done by using the DPDK setup script (called setup.sh and located
in the tools directory).
-Binding and Unbinding Network Ports to/from the igb_uioor VFIO Modules
+Binding and Unbinding Network Ports to/from the Kernel Modules
----------------------------------------------------------------------
As of release 1.4, DPDK applications no longer automatically unbind all
supported network ports from the kernel driver in use.
-Instead, all ports that are to be used by an DPDK application must be bound to
the igb_uio or vfio-pci module before the application is run.
+Instead, all ports that are to be used by an DPDK application must be bound to
the
+uio_pci_generic, igb_uio or vfio-pci module before the application is run.
Any network ports under Linux* control will be ignored by the DPDK poll-mode
drivers and cannot be used by the application.
.. warning::
The DPDK will, by default, no longer automatically unbind network ports
from the kernel driver at startup.
- Any ports to be used by an DPDK application must be unbound from Linux*
control and bound to the igb_uio or vfio-pci module before the application is
run.
+ Any ports to be used by an DPDK application must be unbound from Linux*
control and
+ bound to the uio_pci_generic, igb_uio or vfio-pci module before the
application is run.
-To bind ports to the igb_uio or vfio-pci module for DPDK use, and then
subsequently return ports to Linux* control,
+To bind ports to the uio_pci_generic, igb_uio or vfio-pci module for DPDK use,
+and then subsequently return ports to Linux* control,
a utility script called dpdk_nic _bind.py is provided in the tools
subdirectory.
This utility can be used to provide a view of the current state of the network
ports on the system,
-and to bind and unbind those ports from the different kernel modules,
including igb_uio and vfio-pci.
+and to bind and unbind those ports from the different kernel modules,
including the uio and vfio modules.
The following are some examples of how the script can be used.
A full description of the script and its parameters can be obtained by calling
the script with the --help or --usage options.
+Note that the uio or vfio kernel modules to be used, should be loaded into the
kernel before
+running the dpdk_nic_bind.py script.
.. warning::
@@ -235,33 +242,33 @@ To see the status of all network ports on the system:
root at host:DPDK# ./tools/dpdk_nic_bind.py --status
- Network devices using IGB_UIO driver
- ====================================
- 0000:82:00.0 '82599EB 10-Gigabit SFI/SFP+ Network Connection' drv=igb_uio
unused=ixgbe
- 0000:82:00.1 '82599EB 10-Gigabit SFI/SFP+ Network Connection' drv=igb_uio
unused=ixgbe
+ Network devices using DPDK-compatible driver
+ ============================================
+ 0000:82:00.0 '82599EB 10-Gigabit SFI/SFP+ Network Connection'
drv=uio_pci_generic unused=ixgbe
+ 0000:82:00.1 '82599EB 10-Gigabit SFI/SFP+ Network Connection'
drv=uio_pci_generic unused=ixgbe
Network devices using kernel driver
===================================
- 0000:04:00.0 'I350 Gigabit Network Connection' if=em0 drv=igb
unused=igb_uio *Active*
- 0000:04:00.1 'I350 Gigabit Network Connection' if=eth1 drv=igb
unused=igb_uio
- 0000:04:00.2 'I350 Gigabit Network Connection' if=eth2 drv=igb
unused=igb_uio
- 0000:04:00.3 'I350 Gigabit Network Connection' if=eth3 drv=igb
unused=igb_uio
+ 0000:04:00.0 'I350 Gigabit Network Connection' if=em0 drv=igb
unused=uio_pci_generic *Active*
+ 0000:04:00.1 'I350 Gigabit Network Connection' if=eth1 drv=igb
unused=uio_pci_generic
+ 0000:04:00.2 'I350 Gigabit Network Connection' if=eth2 drv=igb
unused=uio_pci_generic
+ 0000:04:00.3 'I350 Gigabit Network Connection' if=eth3 drv=igb
unused=uio_pci_generic
Other network devices
=====================
<none>
-To bind device eth1, 04:00.1, to the igb_uio driver:
+To bind device eth1, 04:00.1, to the uio_pci_generic driver:
.. code-block:: console
- root at host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio 04:00.1
+ root at host:DPDK# ./tools/dpdk_nic_bind.py --bind=uio_pci_generic 04:00.1
or, alternatively,
.. code-block:: console
- root at host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio eth1
+ root at host:DPDK# ./tools/dpdk_nic_bind.py --bind=uio_pci_generic eth1
To restore device 82:00.0 to its original kernel binding:
diff --git a/doc/guides/linux_gsg/build_sample_apps.rst
b/doc/guides/linux_gsg/build_sample_apps.rst
index 40d1eb7..1abe99c 100644
--- a/doc/guides/linux_gsg/build_sample_apps.rst
+++ b/doc/guides/linux_gsg/build_sample_apps.rst
@@ -99,7 +99,8 @@ Running a Sample Application
.. warning::
- Any ports to be used by the application must be already bound to the
igb_uio module, as described in Section 3.5, prior to running the application.
+ Any ports to be used by the application must be already bound to an
appropriate kernel
+ module, as described in Section 3.5, prior to running the application.
The application is linked with the DPDK target environment's Environmental
Abstraction Layer (EAL) library,
which provides some options that are generic to every DPDK application.
@@ -174,7 +175,7 @@ This can be useful when using other processors to
understand the mapping of the
.. note::
A more graphical view of the logical core layout may be obtained using the
lstopo Linux utility.
- On Fedora* 18, this may be installed and run using the following command:
+ On Fedora* Linux, this may be installed and run using the following
command:
.. code-block:: console
diff --git a/doc/guides/linux_gsg/enable_func.rst
b/doc/guides/linux_gsg/enable_func.rst
index 3590000..9db3b5a 100644
--- a/doc/guides/linux_gsg/enable_func.rst
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -98,6 +98,8 @@ the Linux user account being used to run the DPDK application
has access to them
* The userspace-io device files in /dev, for example, /dev/uio0,
/dev/uio1, and so on
+* The userspace-io sysfs config and resource files, for example for uio0:
/sys/class/uio/uio0/device/config /sys/class/uio/uio0/device/resource*
+
* If the HPET is to be used, /dev/hpet
.. note::
--
2.1.0
