From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <bernard.iremonger@intel.com>
Received: from mga02.intel.com (mga02.intel.com [134.134.136.20])
 by dpdk.org (Postfix) with ESMTP id 3CD3F9AA3
 for <dev@dpdk.org>; Wed, 25 Feb 2015 13:14:24 +0100 (CET)
Received: from orsmga001.jf.intel.com ([10.7.209.18])
 by orsmga101.jf.intel.com with ESMTP; 25 Feb 2015 04:14:23 -0800
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.09,644,1418112000"; d="scan'208";a="656965706"
Received: from irsmsx153.ger.corp.intel.com ([163.33.192.75])
 by orsmga001.jf.intel.com with ESMTP; 25 Feb 2015 04:14:22 -0800
Received: from irsmsx108.ger.corp.intel.com ([169.254.11.218]) by
 IRSMSX153.ger.corp.intel.com ([169.254.9.234]) with mapi id 14.03.0195.001;
 Wed, 25 Feb 2015 12:14:16 +0000
From: "Iremonger, Bernard" <bernard.iremonger@intel.com>
To: "Richardson, Bruce" <bruce.richardson@intel.com>, "dev@dpdk.org"
 <dev@dpdk.org>
Thread-Topic: [dpdk-dev] [PATCH 1/2] doc: Update GSG for uio_pci_generic use
Thread-Index: AQHQUE79wbJABRiz0kuymIYmmpgaC50BRbdw
Date: Wed, 25 Feb 2015 12:14:15 +0000
Message-ID: <8CEF83825BEC744B83065625E567D7C2049ED862@IRSMSX108.ger.corp.intel.com>
References: <1424795260-13793-1-git-send-email-bruce.richardson@intel.com>
 <1424795260-13793-2-git-send-email-bruce.richardson@intel.com>
In-Reply-To: <1424795260-13793-2-git-send-email-bruce.richardson@intel.com>
Accept-Language: en-GB, en-US
Content-Language: en-US
X-MS-Has-Attach: 
X-MS-TNEF-Correlator: 
x-originating-ip: [163.33.239.181]
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
Subject: Re: [dpdk-dev] [PATCH 1/2] doc: Update GSG for uio_pci_generic use
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: patches and discussions about DPDK <dev.dpdk.org>
List-Unsubscribe: <http://dpdk.org/ml/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <http://dpdk.org/ml/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Wed, 25 Feb 2015 12:14:24 -0000



> -----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
>=20
> 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.
>=20
> 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(-)
>=20
> diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/b=
uild_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=3D<target> command:
>=20
>  .. warning::
>=20
> -    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 w=
ith 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 c=
ompilation at a copy of the
> kernel version to be used on the target machine.
>=20
> @@ -154,28 +155,29 @@ Browsing the Installed DPDK Environment Target
>=20
>  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:
>=20
>  .. code-block:: console
>=20
>      $ ls x86_64-native-linuxapp-gcc
>      app build hostapp include kmod lib Makefile
>=20
> -Loading the DPDK igb_uio Module
> --------------------------------
> +Loading Modules to Enable Userspace IO for DPDK
> +-----------------------------------------------
>=20
> -To run any DPDK application, the igb_uio module can be loaded into the r=
unning kernel.
> -The module is found in the kmod sub-directory of the DPDK target directo=
ry.
> -This module should be loaded using the insmod command as shown below (as=
suming that the
> current directory is the DPDK target directory).
> -In many cases, the uio support in the Linux* kernel is compiled as a mod=
ule 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 informat=
ion about uio_pci_generic?
=20
> +To run any DPDK application, a suitable uio module can be loaded into th=
e 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
>=20
>  .. code-block:: console
>=20
> -    sudo modprobe uio
> -    sudo insmod kmod/igb_uio.ko

Should the information about igb_uio be retained alongside the new informat=
ion about uio_pci_generic?

> +    sudo modprobe uio_pci_generic
>=20
> -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 a=
bove.
> +
> +Since DPDK release 1.7 onward provides VFIO support, use of UIO is
> +optional for platforms that support using VFIO.
>=20
>  Loading VFIO Module
>  -------------------
> @@ -195,24 +197,29 @@ Also, to use VFIO, both kernel and BIOS must suppor=
t 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 loc=
ated in the tools directory).
>=20
> -Binding and Unbinding Network Ports to/from the igb_uioor VFIO Modules
> +Binding and Unbinding Network Ports to/from the Kernel Modules
>  ----------------------------------------------------------------------
>=20
>  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 bo=
und 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 appl=
ication is run.
>  Any network ports under Linux* control will be ignored by the DPDK poll-=
mode drivers and cannot be
> used by the application.
>=20
>  .. warning::
>=20
>      The DPDK will, by default, no longer automatically unbind network po=
rts from the kernel driver at
> startup.
> -    Any ports to be used by an DPDK application must be unbound from Lin=
ux* 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 Lin=
ux* control and
> +    bound to the uio_pci_generic, igb_uio or vfio-pci module before the =
application is run.
>=20
> -To bind ports to the igb_uio or vfio-pci module for DPDK use, and then s=
ubsequently 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 subdi=
rectory.
>  This utility can be used to provide a view of the current state of the n=
etwork ports on the system, -
> and to bind and unbind those ports from the different kernel modules, inc=
luding igb_uio and vfio-pci.
> +and to bind and unbind those ports from the different kernel modules, in=
cluding 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 c=
alling 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.
>=20
>  .. warning::
>=20
> @@ -235,33 +242,33 @@ To see the status of all network ports on the syste=
m:
>=20
>      root@host:DPDK# ./tools/dpdk_nic_bind.py --status
>=20
> -    Network devices using IGB_UIO driver
> -    =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> -    0000:82:00.0 '82599EB 10-Gigabit SFI/SFP+ Network Connection' drv=3D=
igb_uio unused=3Dixgbe
> -    0000:82:00.1 '82599EB 10-Gigabit SFI/SFP+ Network Connection' drv=3D=
igb_uio unused=3Dixgbe

Should the information about igb_uio be retained alongside the new informat=
ion about uio_pci_generic?

> +    Network devices using DPDK-compatible driver
> +    =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +    0000:82:00.0 '82599EB 10-Gigabit SFI/SFP+ Network Connection' drv=3D=
uio_pci_generic
> unused=3Dixgbe
> +    0000:82:00.1 '82599EB 10-Gigabit SFI/SFP+ Network Connection'
> + drv=3Duio_pci_generic unused=3Dixgbe
>=20
>      Network devices using kernel driver
>      =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> -    0000:04:00.0 'I350 Gigabit Network Connection' if=3Dem0 drv=3Digb un=
used=3Digb_uio *Active*
> -    0000:04:00.1 'I350 Gigabit Network Connection' if=3Deth1 drv=3Digb u=
nused=3Digb_uio
> -    0000:04:00.2 'I350 Gigabit Network Connection' if=3Deth2 drv=3Digb u=
nused=3Digb_uio
> -    0000:04:00.3 'I350 Gigabit Network Connection' if=3Deth3 drv=3Digb u=
nused=3Digb_uio

Should the information about igb_uio be retained alongside the new informat=
ion about uio_pci_generic?

> +    0000:04:00.0 'I350 Gigabit Network Connection' if=3Dem0 drv=3Digb un=
used=3Duio_pci_generic *Active*
> +    0000:04:00.1 'I350 Gigabit Network Connection' if=3Deth1 drv=3Digb u=
nused=3Duio_pci_generic
> +    0000:04:00.2 'I350 Gigabit Network Connection' if=3Deth2 drv=3Digb u=
nused=3Duio_pci_generic
> +    0000:04:00.3 'I350 Gigabit Network Connection' if=3Deth3 drv=3Digb
> + unused=3Duio_pci_generic
>=20
>      Other network devices
>      =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>      <none>
>=20
> -To bind device eth1, 04:00.1, to the igb_uio driver:

Should the information about igb_uio be retained alongside the new informat=
ion about uio_pci_generic?

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

Should the information about igb_uio be retained alongside the new informat=
ion about uio_pci_generic?

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

Should the information about igb_uio be retained alongside the new informat=
ion about uio_pci_generic?

> +    root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=3Duio_pci_generic
> + eth1
>=20
>  To restore device 82:00.0 to its original kernel binding:
>=20
> 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
>=20
>  .. warning::
>=20
> -    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 applicatio=
n.
>=20
>  The application is linked with the DPDK target environment's Environment=
al Abstraction Layer (EAL)
> library,  which provides some options that are generic to every DPDK appl=
ication.
> @@ -174,7 +175,7 @@ This can be useful when using other processors to und=
erstand the mapping of
> the  .. note::
>=20
>      A more graphical view of the logical core layout may be obtained usi=
ng the lstopo Linux utility.
> -    On Fedora* 18, this may be installed and run using the following com=
mand:
> +    On Fedora* Linux, this may be installed and run using the following =
command:
>=20
>  .. code-block:: console
>=20
> 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 appli=
cation has access to them
>=20
>  *   The userspace-io device files in  /dev, for example,  /dev/uio0, /de=
v/uio1, and so on
>=20
> +*   The userspace-io sysfs config and resource files, for example for ui=
o0:
> /sys/class/uio/uio0/device/config /sys/class/uio/uio0/device/resource*
> +
>  *   If the HPET is to be used,  /dev/hpet
>=20
>  .. note::
> --
> 2.1.0

Regards,

Bernard.