[dpdk-dev,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@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(-)
  

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Bruce Richardson
> Sent: Tuesday, February 24, 2015 4:28 PM
> To: dev@dpdk.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@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:


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.
  

On Wed, Feb 25, 2015 at 12:14:15PM +0000, Iremonger, Bernard wrote:
> 
> 
> > -----Original Message-----
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Bruce Richardson
> > Sent: Tuesday, February 24, 2015 4:28 PM
> > To: dev@dpdk.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@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:
> 
> 
> 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