doc/guides/tools/devbind.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2016 Canonical Limited. All rights reserved.
   3
   4     Redistribution and use in source and binary forms, with or without
   5     modification, are permitted provided that the following conditions
   6     are met:
   7
   8     * Redistributions of source code must retain the above copyright
   9     notice, this list of conditions and the following disclaimer.
  10     * Redistributions in binary form must reproduce the above copyright
  11     notice, this list of conditions and the following disclaimer in
  12     the documentation and/or other materials provided with the
  13     distribution.
  14     * Neither the name of Intel Corporation nor the names of its
  15     contributors may be used to endorse or promote products derived
  16     from this software without specific prior written permission.
  17
  18     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30
  31 dpdk-devbind Application
  32 ========================
  33
  34 The ``dpdk-devbind`` tool is a Data Plane Development Kit (DPDK) utility
  35 that helps binding and unbinding devices from specific drivers.
  36 As well as checking their status in that regard.
  37
  38
  39 Running the Application
  40 -----------------------
  41
  42 The tool has a number of command line options:
  43
  44 .. code-block:: console
  45
  46    dpdk-devbind [options] DEVICE1 DEVICE2 ....
  47
  48 OPTIONS
  49 -------
  50
  51 * ``--help, --usage``
  52
  53         Display usage information and quit
  54
  55 * ``-s, --status``
  56
  57         Print the current status of all known network interfaces.
  58         For each device, it displays the PCI domain, bus, slot and function,
  59         along with a text description of the device. Depending upon whether the
  60         device is being used by a kernel driver, the ``igb_uio`` driver, or no
  61         driver, other relevant information will be displayed:
  62         - the Linux interface name e.g. ``if=eth0``
  63         - the driver being used e.g. ``drv=igb_uio``
  64         - any suitable drivers not currently using that device e.g. ``unused=igb_uio``
  65         NOTE: if this flag is passed along with a bind/unbind option, the
  66         status display will always occur after the other operations have taken
  67         place.
  68
  69 * ``-b driver, --bind=driver``
  70
  71         Select the driver to use or "none" to unbind the device
  72
  73 * ``-u, --unbind``
  74
  75         Unbind a device (Equivalent to ``-b none``)
  76
  77 * ``--force``
  78
  79         By default, devices which are used by Linux - as indicated by having
  80         routes in the routing table - cannot be modified. Using the ``--force``
  81         flag overrides this behavior, allowing active links to be forcibly
  82         unbound.
  83         WARNING: This can lead to loss of network connection and should be used
  84         with caution.
  85
  86
  87 .. warning::
  88
  89     Due to the way VFIO works, there are certain limitations to which devices can be used with VFIO.
  90     Mainly it comes down to how IOMMU groups work.
  91     Any Virtual Function device can be used with VFIO on its own, but physical devices will require either all ports bound to VFIO,
  92     or some of them bound to VFIO while others not being bound to anything at all.
  93
  94     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.
  95     Therefore, the bridge driver should also be unbound from the bridge PCI device for VFIO to work with devices behind the bridge.
  96
  97 .. warning::
  98
  99     While any user can run the ``dpdk-devbind.py`` script to view the status of the network ports,
 100     binding or unbinding network ports requires root privileges.
 101
 102
 103 Examples
 104 --------
 105
 106 To display current device status::
 107
 108    dpdk-devbind --status
 109
 110 To bind eth1 from the current driver and move to use igb_uio::
 111
 112    dpdk-devbind --bind=igb_uio eth1
 113
 114 To unbind 0000:01:00.0 from using any driver::
 115
 116    dpdk-devbind -u 0000:01:00.0
 117
 118 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver::
 119
 120    dpdk-devbind -b ixgbe 02:00.0 02:00.1
 121
 122 To check status of all network ports, assign one to the igb_uio driver and check status again::
 123
 124    # Check the status of the available devices.
 125    dpdk-devbind --status
 126    Network devices using DPDK-compatible driver
 127    ============================================
 128    <none>
 129
 130    Network devices using kernel driver
 131    ===================================
 132    0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
 133
 134
 135    # Bind the device to igb_uio.
 136    sudo dpdk-devbind -b igb_uio 0000:0a:00.0
 137
 138
 139    # Recheck the status of the devices.
 140    dpdk-devbind --status
 141    Network devices using DPDK-compatible driver
 142    ============================================
 143    0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused=