[PATCH 0/2] update docs for uio_pci_generic

[PATCH 0/2] update docs for uio_pci_generic

[Bruce Richardson]

Since we now have support for using uio_pci_generic instead of the DPDK-specific
igb_uio kernel module, update the documentation to reflect this fact.
The doc update includes presenting the uio_pci_generic as the primary uio module
over igb_uio, since in-tree drivers should be generally preferred over DPDK
specific ones.

Bruce Richardson (2):
  doc: Update GSG for uio_pci_generic use
  doc: update programmers guide for uio_pci_generic

 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 +
 doc/guides/prog_guide/env_abstraction_layer.rst    |  8 +--
 .../intel_dpdk_xen_based_packet_switch_sol.rst     |  6 +--
 doc/guides/prog_guide/kernel_nic_interface.rst     |  2 +-
 .../poll_mode_drv_emulated_virtio_nic.rst          |  8 +--
 .../poll_mode_drv_paravirtual_vmxnets_nic.rst      |  2 +-
 8 files changed, 53 insertions(+), 43 deletions(-)

-- 
2.1.0

[PATCH 1/2] doc: Update GSG for uio_pci_generic use

[Bruce Richardson]

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-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
 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@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@host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio 04:00.1
+    root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=uio_pci_generic 04:00.1
 
 or, alternatively,
 
 .. code-block:: console
 
-    root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio eth1
+    root@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

Re: [PATCH 1/2] doc: Update GSG for uio_pci_generic use

[Iremonger, Bernard]

> -----Original Message-----
> From: dev [mailto:dev-bounces-VfR2kkLFssw@public.gmane.org] On Behalf Of Bruce Richardson
> Sent: Tuesday, February 24, 2015 4:28 PM
> To: dev-VfR2kkLFssw@public.gmane.org
> Subject: [dpdk-dev] [PATCH 1/2] doc: Update GSG for uio_pci_generic use
> 
> 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-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> ---
>  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:


Hi Bruce,

Should the information about igb_uio be retained alongside the new information about uio_pci_generic?
 
> +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

Should the information about igb_uio be retained alongside the new information about uio_pci_generic?

> +    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@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

Should the information about igb_uio be retained alongside the new information about uio_pci_generic?

> +    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

Should the information about igb_uio be retained alongside the new information about uio_pci_generic?

> +    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:

Should the information about igb_uio be retained alongside the new information about uio_pci_generic?

> +To bind device eth1, 04:00.1, to the uio_pci_generic driver:
> 
>  .. code-block:: console
> 
> -    root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio 04:00.1

Should the information about igb_uio be retained alongside the new information about uio_pci_generic?

> +    root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=uio_pci_generic
> + 04:00.1
> 
>  or, alternatively,
> 
>  .. code-block:: console
> 
> -    root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio eth1

Should the information about igb_uio be retained alongside the new information about uio_pci_generic?

> +    root@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

Regards,

Bernard.

Re: [PATCH 1/2] doc: Update GSG for uio_pci_generic use

[Bruce Richardson]

On Wed, Feb 25, 2015 at 12:14:15PM +0000, Iremonger, Bernard wrote:
> 
> 
> > -----Original Message-----
> > From: dev [mailto:dev-bounces-VfR2kkLFssw@public.gmane.org] On Behalf Of Bruce Richardson
> > Sent: Tuesday, February 24, 2015 4:28 PM
> > To: dev-VfR2kkLFssw@public.gmane.org
> > Subject: [dpdk-dev] [PATCH 1/2] doc: Update GSG for uio_pci_generic use
> > 
> > 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-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> > ---
> >  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:
> 
> 
> Hi Bruce,
> 
> Should the information about igb_uio be retained alongside the new information about uio_pci_generic?
>  

This is obviously a matter of opinion, but: "no".
This doc is a Getting Started Guide, and therefore meant to cover just the minimum
needed to get up and running and ignoring advanced details. 
"uio_pci_generic" is the simplest path to getting up and running quickly, and
maintaining mention of igb_uio just adds to the complexity of the documentation.

Since uio_pci_generic also works on most linux distro's I'd also be tempted to
move the vfio details out of the main GSG body - perhaps to the extra chapter
covering KNI and running as non-root, again with the objective of simplifying
things for the beginner. VFIO and igb_uio are provided for those who want something
extra above what uio_pci_generic provides, e.g. security, or ability to create
VF devices on all kernels while having the PF in use by DPDK.

Regards,
/Bruce

[PATCH 2/2] doc: update programmers guide for uio_pci_generic

[Bruce Richardson]

Since DPDK now has support for the in-tree uio_pci_generic driver,
update the programmers guide 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-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
 doc/guides/prog_guide/env_abstraction_layer.rst                  | 8 ++++----
 doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst | 6 +++---
 doc/guides/prog_guide/kernel_nic_interface.rst                   | 2 +-
 doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst      | 8 ++++----
 doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst  | 2 +-
 5 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
index 231e266..b5321c3 100644
--- a/doc/guides/prog_guide/env_abstraction_layer.rst
+++ b/doc/guides/prog_guide/env_abstraction_layer.rst
@@ -66,7 +66,7 @@ EAL in a Linux-userland Execution Environment
 ---------------------------------------------
 
 In a Linux user space environment, the DPDK application runs as a user-space application using the pthread library.
-PCI information about devices and address space is discovered through the /sys kernel interface and through a module called igb_uio.
+PCI information about devices and address space is discovered through the /sys kernel interface and through kernel modules such as uio_pci_generic, or igb_uio.
 Refer to the UIO: User-space drivers documentation in the Linux kernel. This memory is mmap'd in the application.
 
 The EAL performs physical memory allocation using mmap() in hugetlbfs (using huge page sizes to increase performance).
@@ -134,10 +134,10 @@ PCI Access
 ~~~~~~~~~~
 
 The EAL uses the /sys/bus/pci utilities provided by the kernel to scan the content on the PCI bus.
-
-To access PCI memory, a kernel module called igb_uio provides a /dev/uioX device file
+To access PCI memory, a kernel module called uio_pci_generic provides a /dev/uioX device file
+and resource files in /sys
 that can be mmap'd to obtain access to PCI address space from the application.
-It uses the uio kernel feature (userland driver).
+The DPDK-specific igb_uio module can also be used for this. Both drivers use the uio kernel feature (userland driver).
 
 Per-lcore and Shared Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
index 1f1e04f..a0dd959 100644
--- a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
+++ b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
@@ -306,12 +306,12 @@ Building and Running the Switching Backend
         Refer to the *DPDK Getting Started Guide* for more information on memory management in the DPDK.
         In the above command, 4 GB memory is reserved (2048 of 2 MB pages) for DPDK.
 
-#.  Load igb_uio and bind one Intel NIC controller to igb_uio:
+#.  Load uio_pci_generic and bind one Intel NIC controller to it:
 
     .. code-block:: console
 
-        insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
-        python tools/dpdk_nic_bind.py -b igb_uio 0000:09:00:00.0
+        modprobe uio_pci_generic
+        python tools/dpdk_nic_bind.py -b uio_pci_generic 0000:09:00:00.0
 
     In this case, 0000:09:00.0 is the PCI address for the NIC controller.
 
diff --git a/doc/guides/prog_guide/kernel_nic_interface.rst b/doc/guides/prog_guide/kernel_nic_interface.rst
index 0276019..9ed7688 100644
--- a/doc/guides/prog_guide/kernel_nic_interface.rst
+++ b/doc/guides/prog_guide/kernel_nic_interface.rst
@@ -224,7 +224,7 @@ Otherwise, by default, KNI will not enable its backend support capability.
 
 Of course, as a prerequisite, the vhost/vhost-net kernel CONFIG should be chosen before compiling the kernel.
 
-#.  Compile the DPDK and insert igb_uio as normal.
+#.  Compile the DPDK and insert uio_pci_generic/igb_uio kernel modules as normal.
 
 #.  Insert the KNI kernel module:
 
diff --git a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst b/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
index 86f4f60..b0a6250 100644
--- a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
+++ b/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
@@ -113,7 +113,7 @@ Host2VM communication example
 
         insmod rte_kni.ko
 
-    Other basic DPDK preparations like hugepage enabling, igb_uio port binding are not listed here.
+    Other basic DPDK preparations like hugepage enabling, uio port binding are not listed here.
     Please refer to the *DPDK Getting Started Guide* for detailed instructions.
 
 #.  Launch the kni user application:
@@ -154,7 +154,7 @@ Host2VM communication example
     In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns corresponds to a physical port,
     which means received packets come from vEth0, and transmitted packets is sent to vEth0.
 
-#.  In the guest, bind the virtio device to the igb_uio kernel module and start the forwarding application.
+#.  In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding application.
     When the virtio port in guest bursts rx, it is getting packets from the raw socket's receive queue.
     When the virtio port bursts tx, it is sending packet to the tx_q.
 
@@ -162,8 +162,8 @@ Host2VM communication example
 
         modprobe uio
         echo 512 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
-        insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
-        python tools/dpdk_nic_bind.py -b igb_uio 00:03.0
+        modprobe uio_pci_generic
+        python tools/dpdk_nic_bind.py -b uio_pci_generic 00:03.0
 
     We use testpmd as the forwarding application in this example.
 
diff --git a/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst b/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
index e48bc13..769723e 100644
--- a/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
+++ b/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
@@ -150,7 +150,7 @@ This section describes an example setup for Phy-vSwitch-VM-Phy communication.
 
 .. note::
 
-    Other instructions on preparing to use DPDK such as, hugepage enabling, igb_uio port binding are not listed here.
+    Other instructions on preparing to use DPDK such as, hugepage enabling, uio port binding are not listed here.
     Please refer to *DPDK Getting Started Guide and DPDK Sample Application's User Guide* for detailed instructions.
 
 The packet reception and transmission flow path is:
-- 
2.1.0

Re: [PATCH 2/2] doc: update programmers guide for uio_pci_generic

[Iremonger, Bernard]

> -----Original Message-----
> From: dev [mailto:dev-bounces-VfR2kkLFssw@public.gmane.org] On Behalf Of Bruce Richardson
> Sent: Tuesday, February 24, 2015 4:28 PM
> To: dev-VfR2kkLFssw@public.gmane.org
> Subject: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for uio_pci_generic
> 
> Since DPDK now has support for the in-tree uio_pci_generic driver, update the programmers guide
> 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-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> ---
>  doc/guides/prog_guide/env_abstraction_layer.rst                  | 8 ++++----
>  doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst | 6 +++---
>  doc/guides/prog_guide/kernel_nic_interface.rst                   | 2 +-
>  doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst      | 8 ++++----
>  doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst  | 2 +-
>  5 files changed, 13 insertions(+), 13 deletions(-)
> 
> diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst
> b/doc/guides/prog_guide/env_abstraction_layer.rst
> index 231e266..b5321c3 100644
> --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> @@ -66,7 +66,7 @@ EAL in a Linux-userland Execution Environment
>  ---------------------------------------------
> 
>  In a Linux user space environment, the DPDK application runs as a user-space application using the
> pthread library.
> -PCI information about devices and address space is discovered through the /sys kernel interface and
> through a module called igb_uio.
> +PCI information about devices and address space is discovered through the /sys kernel interface and
> through kernel modules such as uio_pci_generic, or igb_uio.
>  Refer to the UIO: User-space drivers documentation in the Linux kernel. This memory is mmap'd in
> the application.
> 
>  The EAL performs physical memory allocation using mmap() in hugetlbfs (using huge page sizes to
> increase performance).
> @@ -134,10 +134,10 @@ PCI Access
>  ~~~~~~~~~~
> 
>  The EAL uses the /sys/bus/pci utilities provided by the kernel to scan the content on the PCI bus.
> -
> -To access PCI memory, a kernel module called igb_uio provides a /dev/uioX device file
> +To access PCI memory, a kernel module called uio_pci_generic provides a
> +/dev/uioX device file and resource files in /sys
>  that can be mmap'd to obtain access to PCI address space from the application.
> -It uses the uio kernel feature (userland driver).
> +The DPDK-specific igb_uio module can also be used for this. Both drivers use the uio kernel feature
> (userland driver).
> 
>  Per-lcore and Shared Variables
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> diff --git a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> index 1f1e04f..a0dd959 100644
> --- a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> +++ b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> @@ -306,12 +306,12 @@ Building and Running the Switching Backend
>          Refer to the *DPDK Getting Started Guide* for more information on memory management in the
> DPDK.
>          In the above command, 4 GB memory is reserved (2048 of 2 MB pages) for DPDK.
> 
> -#.  Load igb_uio and bind one Intel NIC controller to igb_uio:
> +#.  Load uio_pci_generic and bind one Intel NIC controller to it:
> 
>      .. code-block:: console
> 
> -        insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
> -        python tools/dpdk_nic_bind.py -b igb_uio 0000:09:00:00.0


Hi Bruce,

Should the information about igb_uio be retained alongside the new information about uio_pci_generic?

> +        modprobe uio_pci_generic
> +        python tools/dpdk_nic_bind.py -b uio_pci_generic
> + 0000:09:00:00.0
> 
>      In this case, 0000:09:00.0 is the PCI address for the NIC controller.
> 
> diff --git a/doc/guides/prog_guide/kernel_nic_interface.rst
> b/doc/guides/prog_guide/kernel_nic_interface.rst
> index 0276019..9ed7688 100644
> --- a/doc/guides/prog_guide/kernel_nic_interface.rst
> +++ b/doc/guides/prog_guide/kernel_nic_interface.rst
> @@ -224,7 +224,7 @@ Otherwise, by default, KNI will not enable its backend support capability.
> 
>  Of course, as a prerequisite, the vhost/vhost-net kernel CONFIG should be chosen before compiling
> the kernel.
> 
> -#.  Compile the DPDK and insert igb_uio as normal.
> +#.  Compile the DPDK and insert uio_pci_generic/igb_uio kernel modules as normal.
> 
>  #.  Insert the KNI kernel module:
> 
> diff --git a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> b/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> index 86f4f60..b0a6250 100644
> --- a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> +++ b/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> @@ -113,7 +113,7 @@ Host2VM communication example
> 
>          insmod rte_kni.ko
> 
> -    Other basic DPDK preparations like hugepage enabling, igb_uio port binding are not listed here.
> +    Other basic DPDK preparations like hugepage enabling, uio port binding are not listed here.
>      Please refer to the *DPDK Getting Started Guide* for detailed instructions.
> 
>  #.  Launch the kni user application:
> @@ -154,7 +154,7 @@ Host2VM communication example
>      In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns
> corresponds to a physical port,
>      which means received packets come from vEth0, and transmitted packets is sent to vEth0.
> 
> -#.  In the guest, bind the virtio device to the igb_uio kernel module and start the forwarding
> application.
> +#.  In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding
> application.
>      When the virtio port in guest bursts rx, it is getting packets from the raw socket's receive queue.
>      When the virtio port bursts tx, it is sending packet to the tx_q.
> 
> @@ -162,8 +162,8 @@ Host2VM communication example
> 
>          modprobe uio
>          echo 512 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
> -        insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
> -        python tools/dpdk_nic_bind.py -b igb_uio 00:03.0

Should the information about igb_uio be retained alongside the new information about uio_pci_generic?

> +        modprobe uio_pci_generic
> +        python tools/dpdk_nic_bind.py -b uio_pci_generic 00:03.0
> 
>      We use testpmd as the forwarding application in this example.
> 
> diff --git a/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> b/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> index e48bc13..769723e 100644
> --- a/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> +++ b/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> @@ -150,7 +150,7 @@ This section describes an example setup for Phy-vSwitch-VM-Phy
> communication.
> 
>  .. note::
> 
> -    Other instructions on preparing to use DPDK such as, hugepage enabling, igb_uio port binding are
> not listed here.
> +    Other instructions on preparing to use DPDK such as, hugepage enabling, uio port binding are not
> listed here.
>      Please refer to *DPDK Getting Started Guide and DPDK Sample Application's User Guide* for
> detailed instructions.
> 
>  The packet reception and transmission flow path is:
> --
> 2.1.0

Regards,

Bernard.

Re: [PATCH 2/2] doc: update programmers guide for uio_pci_generic

[Bruce Richardson]

On Wed, Feb 25, 2015 at 12:19:10PM +0000, Iremonger, Bernard wrote:
> 
> 
> > -----Original Message-----
> > From: dev [mailto:dev-bounces-VfR2kkLFssw@public.gmane.org] On Behalf Of Bruce Richardson
> > Sent: Tuesday, February 24, 2015 4:28 PM
> > To: dev-VfR2kkLFssw@public.gmane.org
> > Subject: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for uio_pci_generic
> > 
> > Since DPDK now has support for the in-tree uio_pci_generic driver, update the programmers guide
> > 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-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> > ---
> >  doc/guides/prog_guide/env_abstraction_layer.rst                  | 8 ++++----
> >  doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst | 6 +++---
> >  doc/guides/prog_guide/kernel_nic_interface.rst                   | 2 +-
> >  doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst      | 8 ++++----
> >  doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst  | 2 +-
> >  5 files changed, 13 insertions(+), 13 deletions(-)
> > 
> > diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst
> > b/doc/guides/prog_guide/env_abstraction_layer.rst
> > index 231e266..b5321c3 100644
> > --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> > +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> > @@ -66,7 +66,7 @@ EAL in a Linux-userland Execution Environment
> >  ---------------------------------------------
> > 
> >  In a Linux user space environment, the DPDK application runs as a user-space application using the
> > pthread library.
> > -PCI information about devices and address space is discovered through the /sys kernel interface and
> > through a module called igb_uio.
> > +PCI information about devices and address space is discovered through the /sys kernel interface and
> > through kernel modules such as uio_pci_generic, or igb_uio.
> >  Refer to the UIO: User-space drivers documentation in the Linux kernel. This memory is mmap'd in
> > the application.
> > 
> >  The EAL performs physical memory allocation using mmap() in hugetlbfs (using huge page sizes to
> > increase performance).
> > @@ -134,10 +134,10 @@ PCI Access
> >  ~~~~~~~~~~
> > 
> >  The EAL uses the /sys/bus/pci utilities provided by the kernel to scan the content on the PCI bus.
> > -
> > -To access PCI memory, a kernel module called igb_uio provides a /dev/uioX device file
> > +To access PCI memory, a kernel module called uio_pci_generic provides a
> > +/dev/uioX device file and resource files in /sys
> >  that can be mmap'd to obtain access to PCI address space from the application.
> > -It uses the uio kernel feature (userland driver).
> > +The DPDK-specific igb_uio module can also be used for this. Both drivers use the uio kernel feature
> > (userland driver).
> > 
> >  Per-lcore and Shared Variables
> >  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > diff --git a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > index 1f1e04f..a0dd959 100644
> > --- a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > +++ b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > @@ -306,12 +306,12 @@ Building and Running the Switching Backend
> >          Refer to the *DPDK Getting Started Guide* for more information on memory management in the
> > DPDK.
> >          In the above command, 4 GB memory is reserved (2048 of 2 MB pages) for DPDK.
> > 
> > -#.  Load igb_uio and bind one Intel NIC controller to igb_uio:
> > +#.  Load uio_pci_generic and bind one Intel NIC controller to it:
> > 
> >      .. code-block:: console
> > 
> > -        insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
> > -        python tools/dpdk_nic_bind.py -b igb_uio 0000:09:00:00.0
> 
> 
> Hi Bruce,
> 
> Should the information about igb_uio be retained alongside the new information about uio_pci_generic?
>
While the answer may not be as clear-cut as with the GSG, why would be bother
covering both here. We already ignore VFIO in these examples.

/Bruce

Re: [PATCH 2/2] doc: update programmers guide for uio_pci_generic

[Iremonger, Bernard]

> -----Original Message-----
> From: Richardson, Bruce
> Sent: Wednesday, February 25, 2015 12:28 PM
> To: Iremonger, Bernard
> Cc: dev-VfR2kkLFssw@public.gmane.org
> Subject: Re: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for uio_pci_generic
> 
> On Wed, Feb 25, 2015 at 12:19:10PM +0000, Iremonger, Bernard wrote:
> >
> >
> > > -----Original Message-----
> > > From: dev [mailto:dev-bounces-VfR2kkLFssw@public.gmane.org] On Behalf Of Bruce
> > > Richardson
> > > Sent: Tuesday, February 24, 2015 4:28 PM
> > > To: dev-VfR2kkLFssw@public.gmane.org
> > > Subject: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for
> > > uio_pci_generic
> > >
> > > Since DPDK now has support for the in-tree uio_pci_generic driver,
> > > update the programmers guide 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-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> > > ---
> > >  doc/guides/prog_guide/env_abstraction_layer.rst                  | 8 ++++----
> > >  doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst | 6 +++---
> > >  doc/guides/prog_guide/kernel_nic_interface.rst                   | 2 +-
> > >  doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst      | 8 ++++----
> > >  doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst  |
> > > 2 +-
> > >  5 files changed, 13 insertions(+), 13 deletions(-)
> > >
> > > diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst
> > > b/doc/guides/prog_guide/env_abstraction_layer.rst
> > > index 231e266..b5321c3 100644
> > > --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> > > +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> > > @@ -66,7 +66,7 @@ EAL in a Linux-userland Execution Environment
> > >  ---------------------------------------------
> > >
> > >  In a Linux user space environment, the DPDK application runs as a
> > > user-space application using the pthread library.
> > > -PCI information about devices and address space is discovered
> > > through the /sys kernel interface and through a module called igb_uio.
> > > +PCI information about devices and address space is discovered
> > > +through the /sys kernel interface and
> > > through kernel modules such as uio_pci_generic, or igb_uio.
> > >  Refer to the UIO: User-space drivers documentation in the Linux
> > > kernel. This memory is mmap'd in the application.
> > >
> > >  The EAL performs physical memory allocation using mmap() in
> > > hugetlbfs (using huge page sizes to increase performance).
> > > @@ -134,10 +134,10 @@ PCI Access
> > >  ~~~~~~~~~~
> > >
> > >  The EAL uses the /sys/bus/pci utilities provided by the kernel to scan the content on the PCI bus.
> > > -
> > > -To access PCI memory, a kernel module called igb_uio provides a
> > > /dev/uioX device file
> > > +To access PCI memory, a kernel module called uio_pci_generic
> > > +provides a /dev/uioX device file and resource files in /sys
> > >  that can be mmap'd to obtain access to PCI address space from the application.
> > > -It uses the uio kernel feature (userland driver).
> > > +The DPDK-specific igb_uio module can also be used for this. Both
> > > +drivers use the uio kernel feature
> > > (userland driver).
> > >
> > >  Per-lcore and Shared Variables
> > >  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > diff --git
> > > a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > index 1f1e04f..a0dd959 100644
> > > ---
> > > a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > +++ b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.r
> > > +++ st
> > > @@ -306,12 +306,12 @@ Building and Running the Switching Backend
> > >          Refer to the *DPDK Getting Started Guide* for more
> > > information on memory management in the DPDK.
> > >          In the above command, 4 GB memory is reserved (2048 of 2 MB pages) for DPDK.
> > >
> > > -#.  Load igb_uio and bind one Intel NIC controller to igb_uio:
> > > +#.  Load uio_pci_generic and bind one Intel NIC controller to it:
> > >
> > >      .. code-block:: console
> > >
> > > -        insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
> > > -        python tools/dpdk_nic_bind.py -b igb_uio 0000:09:00:00.0
> >
> >
> > Hi Bruce,
> >
> > Should the information about igb_uio be retained alongside the new information about
> uio_pci_generic?
> >
> While the answer may not be as clear-cut as with the GSG, why would be bother covering both here.
> We already ignore VFIO in these examples.
> 
> /Bruce

Hi Bruce,

The method of loading is different for both modules, igb_uio uses insmod and uio_pci_generic uses modprobe.
It would be useful to retain this igb_uio information. Maybe vfio information should be added too.
This comment also applies to the GSG,  the differences need to be documented.

Regards,

Bernard.

Re: [PATCH 2/2] doc: update programmers guide for uio_pci_generic

[Bruce Richardson]

On Wed, Feb 25, 2015 at 01:12:43PM +0000, Iremonger, Bernard wrote:
> 
> 
> > -----Original Message-----
> > From: Richardson, Bruce
> > Sent: Wednesday, February 25, 2015 12:28 PM
> > To: Iremonger, Bernard
> > Cc: dev-VfR2kkLFssw@public.gmane.org
> > Subject: Re: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for uio_pci_generic
> > 
> > On Wed, Feb 25, 2015 at 12:19:10PM +0000, Iremonger, Bernard wrote:
> > >
> > >
> > > > -----Original Message-----
> > > > From: dev [mailto:dev-bounces-VfR2kkLFssw@public.gmane.org] On Behalf Of Bruce
> > > > Richardson
> > > > Sent: Tuesday, February 24, 2015 4:28 PM
> > > > To: dev-VfR2kkLFssw@public.gmane.org
> > > > Subject: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for
> > > > uio_pci_generic
> > > >
> > > > Since DPDK now has support for the in-tree uio_pci_generic driver,
> > > > update the programmers guide 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-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> > > > ---
> > > >  doc/guides/prog_guide/env_abstraction_layer.rst                  | 8 ++++----
> > > >  doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst | 6 +++---
> > > >  doc/guides/prog_guide/kernel_nic_interface.rst                   | 2 +-
> > > >  doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst      | 8 ++++----
> > > >  doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst  |
> > > > 2 +-
> > > >  5 files changed, 13 insertions(+), 13 deletions(-)
> > > >
> > > > diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > b/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > index 231e266..b5321c3 100644
> > > > --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > @@ -66,7 +66,7 @@ EAL in a Linux-userland Execution Environment
> > > >  ---------------------------------------------
> > > >
> > > >  In a Linux user space environment, the DPDK application runs as a
> > > > user-space application using the pthread library.
> > > > -PCI information about devices and address space is discovered
> > > > through the /sys kernel interface and through a module called igb_uio.
> > > > +PCI information about devices and address space is discovered
> > > > +through the /sys kernel interface and
> > > > through kernel modules such as uio_pci_generic, or igb_uio.
> > > >  Refer to the UIO: User-space drivers documentation in the Linux
> > > > kernel. This memory is mmap'd in the application.
> > > >
> > > >  The EAL performs physical memory allocation using mmap() in
> > > > hugetlbfs (using huge page sizes to increase performance).
> > > > @@ -134,10 +134,10 @@ PCI Access
> > > >  ~~~~~~~~~~
> > > >
> > > >  The EAL uses the /sys/bus/pci utilities provided by the kernel to scan the content on the PCI bus.
> > > > -
> > > > -To access PCI memory, a kernel module called igb_uio provides a
> > > > /dev/uioX device file
> > > > +To access PCI memory, a kernel module called uio_pci_generic
> > > > +provides a /dev/uioX device file and resource files in /sys
> > > >  that can be mmap'd to obtain access to PCI address space from the application.
> > > > -It uses the uio kernel feature (userland driver).
> > > > +The DPDK-specific igb_uio module can also be used for this. Both
> > > > +drivers use the uio kernel feature
> > > > (userland driver).
> > > >
> > > >  Per-lcore and Shared Variables
> > > >  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > > diff --git
> > > > a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > > b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > > index 1f1e04f..a0dd959 100644
> > > > ---
> > > > a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > > +++ b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.r
> > > > +++ st
> > > > @@ -306,12 +306,12 @@ Building and Running the Switching Backend
> > > >          Refer to the *DPDK Getting Started Guide* for more
> > > > information on memory management in the DPDK.
> > > >          In the above command, 4 GB memory is reserved (2048 of 2 MB pages) for DPDK.
> > > >
> > > > -#.  Load igb_uio and bind one Intel NIC controller to igb_uio:
> > > > +#.  Load uio_pci_generic and bind one Intel NIC controller to it:
> > > >
> > > >      .. code-block:: console
> > > >
> > > > -        insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
> > > > -        python tools/dpdk_nic_bind.py -b igb_uio 0000:09:00:00.0
> > >
> > >
> > > Hi Bruce,
> > >
> > > Should the information about igb_uio be retained alongside the new information about
> > uio_pci_generic?
> > >
> > While the answer may not be as clear-cut as with the GSG, why would be bother covering both here.
> > We already ignore VFIO in these examples.
> > 
> > /Bruce
> 
> Hi Bruce,
> 
> The method of loading is different for both modules, igb_uio uses insmod and uio_pci_generic uses modprobe.
> It would be useful to retain this igb_uio information. Maybe vfio information should be added too.
> This comment also applies to the GSG,  the differences need to be documented.
>
Yes, the differences between the different modules needs to be documented, 
including limitations of each one and when and why you might choose one over
the other. This probably belongs as a section in programmers guide. However, IMHO
it definitely does not belong in the GSG guide, except as a reference to the
programmers guide section. [I think section 3.1 is the best place for such
documentation].

Regards,
/Bruce

Re: [PATCH 2/2] doc: update programmers guide for uio_pci_generic

[Bruce Richardson]

On Wed, Feb 25, 2015 at 01:20:43PM +0000, Bruce Richardson wrote:
> On Wed, Feb 25, 2015 at 01:12:43PM +0000, Iremonger, Bernard wrote:
> > 
> > 
> > > -----Original Message-----
> > > From: Richardson, Bruce
> > > Sent: Wednesday, February 25, 2015 12:28 PM
> > > To: Iremonger, Bernard
> > > Cc: dev-VfR2kkLFssw@public.gmane.org
> > > Subject: Re: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for uio_pci_generic
> > > 
> > > On Wed, Feb 25, 2015 at 12:19:10PM +0000, Iremonger, Bernard wrote:
> > > >
> > > >
> > > > > -----Original Message-----
> > > > > From: dev [mailto:dev-bounces-VfR2kkLFssw@public.gmane.org] On Behalf Of Bruce
> > > > > Richardson
> > > > > Sent: Tuesday, February 24, 2015 4:28 PM
> > > > > To: dev-VfR2kkLFssw@public.gmane.org
> > > > > Subject: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for
> > > > > uio_pci_generic
> > > > >
> > > > > Since DPDK now has support for the in-tree uio_pci_generic driver,
> > > > > update the programmers guide 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-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> > > > > ---
> > > > >  doc/guides/prog_guide/env_abstraction_layer.rst                  | 8 ++++----
> > > > >  doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst | 6 +++---
> > > > >  doc/guides/prog_guide/kernel_nic_interface.rst                   | 2 +-
> > > > >  doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst      | 8 ++++----
> > > > >  doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst  |
> > > > > 2 +-
> > > > >  5 files changed, 13 insertions(+), 13 deletions(-)
> > > > >
> > > > > diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > > b/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > > index 231e266..b5321c3 100644
> > > > > --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > > +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > > @@ -66,7 +66,7 @@ EAL in a Linux-userland Execution Environment
> > > > >  ---------------------------------------------
> > > > >
> > > > >  In a Linux user space environment, the DPDK application runs as a
> > > > > user-space application using the pthread library.
> > > > > -PCI information about devices and address space is discovered
> > > > > through the /sys kernel interface and through a module called igb_uio.
> > > > > +PCI information about devices and address space is discovered
> > > > > +through the /sys kernel interface and
> > > > > through kernel modules such as uio_pci_generic, or igb_uio.
> > > > >  Refer to the UIO: User-space drivers documentation in the Linux
> > > > > kernel. This memory is mmap'd in the application.
> > > > >
> > > > >  The EAL performs physical memory allocation using mmap() in
> > > > > hugetlbfs (using huge page sizes to increase performance).
> > > > > @@ -134,10 +134,10 @@ PCI Access
> > > > >  ~~~~~~~~~~
> > > > >
> > > > >  The EAL uses the /sys/bus/pci utilities provided by the kernel to scan the content on the PCI bus.
> > > > > -
> > > > > -To access PCI memory, a kernel module called igb_uio provides a
> > > > > /dev/uioX device file
> > > > > +To access PCI memory, a kernel module called uio_pci_generic
> > > > > +provides a /dev/uioX device file and resource files in /sys
> > > > >  that can be mmap'd to obtain access to PCI address space from the application.
> > > > > -It uses the uio kernel feature (userland driver).
> > > > > +The DPDK-specific igb_uio module can also be used for this. Both
> > > > > +drivers use the uio kernel feature
> > > > > (userland driver).
> > > > >
> > > > >  Per-lcore and Shared Variables
> > > > >  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > > > diff --git
> > > > > a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > > > b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > > > index 1f1e04f..a0dd959 100644
> > > > > ---
> > > > > a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > > > +++ b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.r
> > > > > +++ st
> > > > > @@ -306,12 +306,12 @@ Building and Running the Switching Backend
> > > > >          Refer to the *DPDK Getting Started Guide* for more
> > > > > information on memory management in the DPDK.
> > > > >          In the above command, 4 GB memory is reserved (2048 of 2 MB pages) for DPDK.
> > > > >
> > > > > -#.  Load igb_uio and bind one Intel NIC controller to igb_uio:
> > > > > +#.  Load uio_pci_generic and bind one Intel NIC controller to it:
> > > > >
> > > > >      .. code-block:: console
> > > > >
> > > > > -        insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
> > > > > -        python tools/dpdk_nic_bind.py -b igb_uio 0000:09:00:00.0
> > > >
> > > >
> > > > Hi Bruce,
> > > >
> > > > Should the information about igb_uio be retained alongside the new information about
> > > uio_pci_generic?
> > > >
> > > While the answer may not be as clear-cut as with the GSG, why would be bother covering both here.
> > > We already ignore VFIO in these examples.
> > > 
> > > /Bruce
> > 
> > Hi Bruce,
> > 
> > The method of loading is different for both modules, igb_uio uses insmod and uio_pci_generic uses modprobe.
> > It would be useful to retain this igb_uio information. Maybe vfio information should be added too.
> > This comment also applies to the GSG,  the differences need to be documented.
> >
> Yes, the differences between the different modules needs to be documented, 
> including limitations of each one and when and why you might choose one over
> the other. This probably belongs as a section in programmers guide. However, IMHO
> it definitely does not belong in the GSG guide, except as a reference to the
> programmers guide section. [I think section 3.1 is the best place for such
> documentation].
> 
> Regards,
> /Bruce

>From further testing, it appears that uio_pci_generic does not work with VF
devices due to the fact that it doesn't allow MSI/MSI-X interrupts and requires
than any device has a (legacy) interrupt available to it. Therefore, I'll do 
a suitable update to the docs to reflect this (perhaps a partial rollback of this
patch). Investigation is continuing...

Regards,
/Bruce

Re: [PATCH 0/2] update docs for uio_pci_generic

[Thomas Monjalon]

2015-02-24 16:27, Bruce Richardson:
> Since we now have support for using uio_pci_generic instead of the DPDK-specific
> igb_uio kernel module, update the documentation to reflect this fact.
> The doc update includes presenting the uio_pci_generic as the primary uio module
> over igb_uio, since in-tree drivers should be generally preferred over DPDK
> specific ones.
> 
> Bruce Richardson (2):
>   doc: Update GSG for uio_pci_generic use
>   doc: update programmers guide for uio_pci_generic

Applied, thanks