X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Flinux_gsg%2Fbuild_dpdk.rst;h=e32afd5f8af849b2c56321d0a5125f35dee0aa7a;hb=b9b21e0eecfd48983253ee7c7f7a406356e1650b;hp=eadade2763f35959599fcf0e4285f7e875633e6c;hpb=c6dab2a873f65c5a4ea9735aa24d9539426adba4;p=dpdk.git diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst index eadade2763..e32afd5f8a 100644 --- a/doc/guides/linux_gsg/build_dpdk.rst +++ b/doc/guides/linux_gsg/build_dpdk.rst @@ -143,130 +143,3 @@ Browsing the Installed DPDK Environment Target Once a target is created it contains all libraries, including poll-mode drivers, 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. A kmod directory is also present that contains kernel modules which may be loaded if needed. - -Loading Modules to Enable Userspace IO for DPDK ------------------------------------------------ - -To run any DPDK application, a suitable uio module can be loaded into the running kernel. -In many 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_pci_generic - -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. It can -be loaded as shown below: - -.. code-block:: console - - sudo modprobe uio - sudo insmod kmod/igb_uio.ko - -.. note:: - - For some devices which lack support for legacy interrupts, e.g. virtual function - (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``. - -Since DPDK release 1.7 onward provides VFIO support, use of UIO is optional -for platforms that support using VFIO. - -Loading VFIO Module -------------------- - -To run an DPDK application and make use of VFIO, the ``vfio-pci`` module must be loaded: - -.. code-block:: console - - sudo modprobe vfio-pci - -Note that in order to use VFIO, your kernel must support it. -VFIO kernel modules have been included in the Linux kernel since version 3.6.0 and are usually present by default, -however please consult your distributions documentation to make sure that is the case. - -Also, to use VFIO, both kernel and BIOS must support and be configured to use IO virtualization (such as Intel® VT-d). - -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 dpdk-setup.sh and located in the usertools directory). - -.. _linux_gsg_binding_kernel: - -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 -``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 ``uio_pci_generic``, ``igb_uio`` or ``vfio-pci`` module before the application is run. - -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 usertools 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 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-devbind.py`` script. - -.. warning:: - - Due to the way VFIO works, there are certain limitations to which devices can be used with VFIO. - Mainly it comes down to how IOMMU groups work. - Any Virtual Function device can be used with VFIO on its own, but physical devices will require either all ports bound to VFIO, - or some of them bound to VFIO while others not being bound to anything at all. - - If your device is behind a PCI-to-PCI bridge, the bridge will then be part of the IOMMU group in which your device is in. - Therefore, the bridge driver should also be unbound from the bridge PCI device for VFIO to work with devices behind the bridge. - -.. warning:: - - While any user can run the dpdk-devbind.py script to view the status of the network ports, - binding or unbinding network ports requires root privileges. - -To see the status of all network ports on the system: - -.. code-block:: console - - ./usertools/dpdk-devbind.py --status - - Network devices using DPDK-compatible driver - ============================================ - 0000:82:00.0 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe - 0000:82:00.1 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe - - Network devices using kernel driver - =================================== - 0000:04:00.0 'I350 1-GbE NIC' if=em0 drv=igb unused=uio_pci_generic *Active* - 0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=uio_pci_generic - 0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=uio_pci_generic - 0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=uio_pci_generic - - Other network devices - ===================== - - -To bind device ``eth1``,``04:00.1``, to the ``uio_pci_generic`` driver: - -.. code-block:: console - - ./usertools/dpdk-devbind.py --bind=uio_pci_generic 04:00.1 - -or, alternatively, - -.. code-block:: console - - ./usertools/dpdk-devbind.py --bind=uio_pci_generic eth1 - -To restore device ``82:00.0`` to its original kernel binding: - -.. code-block:: console - - ./usertools/dpdk-devbind.py --bind=ixgbe 82:00.0