doc/guides/tools/devbind.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2016 Canonical Limited. All rights reserved.
   3
   4 dpdk-devbind Application
   5 ========================
   6
   7 The ``dpdk-devbind`` tool is a Data Plane Development Kit (DPDK) utility
   8 that helps binding and unbinding devices from specific drivers.
   9 As well as checking their status in that regard.
  10
  11
  12 Running the Application
  13 -----------------------
  14
  15 The tool has a number of command line options:
  16
  17 .. code-block:: console
  18
  19    dpdk-devbind [options] DEVICE1 DEVICE2 ....
  20
  21 OPTIONS
  22 -------
  23
  24 * ``--help, --usage``
  25
  26         Display usage information and quit
  27
  28 * ``-s, --status``
  29
  30         Print the current status of all known network interfaces.
  31         For each device, it displays the PCI domain, bus, slot and function,
  32         along with a text description of the device. Depending upon whether the
  33         device is being used by a kernel driver, the ``vfio-pci`` driver, or no
  34         driver, other relevant information will be displayed:
  35         - the Linux interface name e.g. ``if=eth0``
  36         - the driver being used e.g. ``drv=vfio-pci``
  37         - any suitable drivers not currently using that device e.g. ``unused=vfio-pci``
  38         NOTE: if this flag is passed along with a bind/unbind option, the
  39         status display will always occur after the other operations have taken
  40         place.
  41
  42 * ``-b driver, --bind=driver``
  43
  44         Select the driver to use or "none" to unbind the device
  45
  46 * ``-u, --unbind``
  47
  48         Unbind a device (Equivalent to ``-b none``)
  49
  50 * ``--force``
  51
  52         By default, devices which are used by Linux - as indicated by having
  53         routes in the routing table - cannot be modified. Using the ``--force``
  54         flag overrides this behavior, allowing active links to be forcibly
  55         unbound.
  56         WARNING: This can lead to loss of network connection and should be used
  57         with caution.
  58
  59
  60 .. warning::
  61
  62     Due to the way VFIO works, there are certain limitations to which devices can be used with VFIO.
  63     Mainly it comes down to how IOMMU groups work.
  64     Any Virtual Function device can be used with VFIO on its own, but physical devices will require either all ports bound to VFIO,
  65     or some of them bound to VFIO while others not being bound to anything at all.
  66
  67     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.
  68     Therefore, the bridge driver should also be unbound from the bridge PCI device for VFIO to work with devices behind the bridge.
  69
  70 .. warning::
  71
  72     While any user can run the ``dpdk-devbind.py`` script to view the status of the network ports,
  73     binding or unbinding network ports requires root privileges.
  74
  75
  76 Examples
  77 --------
  78
  79 To display current device status::
  80
  81    dpdk-devbind --status
  82
  83 To bind eth1 from the current driver and move to use vfio-pci::
  84
  85    dpdk-devbind --bind=vfio-pci eth1
  86
  87 To unbind 0000:01:00.0 from using any driver::
  88
  89    dpdk-devbind -u 0000:01:00.0
  90
  91 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver::
  92
  93    dpdk-devbind -b ixgbe 02:00.0 02:00.1
  94
  95 To check status of all network ports, assign one to the vfio-pci driver and check status again::
  96
  97    # Check the status of the available devices.
  98    dpdk-devbind --status
  99    Network devices using DPDK-compatible driver
 100    ============================================
 101    <none>
 102
 103    Network devices using kernel driver
 104    ===================================
 105    0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
 106
 107
 108    # Bind the device to vfio-pci.
 109    sudo dpdk-devbind -b vfio-pci 0000:0a:00.0
 110
 111
 112    # Recheck the status of the devices.
 113    dpdk-devbind --status
 114    Network devices using DPDK-compatible driver
 115    ============================================
 116    0000:0a:00.0 '82599ES 10-Gigabit' drv=vfio-pci unused=