[dpdk-dev] [PATCH 1/2] doc: Update GSG for uio_pci_generic use
On Wed, Feb 25, 2015 at 12:14:15PM +, Iremonger, Bernard wrote: > > > > -Original Message- > > From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Bruce Richardson > > Sent: Tuesday, February 24, 2015 4:28 PM > > To: dev at 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 > > --- > > 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= 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
[dpdk-dev] [PATCH 1/2] doc: Update GSG for uio_pci_generic use
> -Original Message- > From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Bruce Richardson > Sent: Tuesday, February 24, 2015 4:28 PM > To: dev at 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 > --- > 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= 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
[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 --- 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= 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
