1 --- a/doc/guides/conf.py
2 +++ b/doc/guides/conf.py
4 ("tools/proc_info", "dpdk-procinfo",
5 "access dpdk port stats and memory info", "", 1),
6 ("tools/pmdinfo", "dpdk-pmdinfo",
7 - "dump a PMDs hardware support info", "", 1)]
8 + "dump a PMDs hardware support info", "", 1),
9 + ("tools/devbind", "dpdk-devbind",
10 + "check device status and bind/unbind them from drivers", "", 8)]
12 ######## :numref: fallback ########
13 # The following hook functions add some simple handling for the :numref:
15 +++ b/doc/guides/tools/devbind.rst
19 + Copyright(c) 2016 Canonical Limited. All rights reserved.
21 + Redistribution and use in source and binary forms, with or without
22 + modification, are permitted provided that the following conditions
25 + * Redistributions of source code must retain the above copyright
26 + notice, this list of conditions and the following disclaimer.
27 + * Redistributions in binary form must reproduce the above copyright
28 + notice, this list of conditions and the following disclaimer in
29 + the documentation and/or other materials provided with the
31 + * Neither the name of Intel Corporation nor the names of its
32 + contributors may be used to endorse or promote products derived
33 + from this software without specific prior written permission.
35 + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
36 + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
37 + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
38 + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
39 + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40 + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41 + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
42 + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
43 + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
44 + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
45 + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
48 +dpdk-devbind Application
49 +========================
51 +The ``dpdk-devbind`` tool is a Data Plane Development Kit (DPDK) tool that helps binding and unbinding devices from specific drivers.
52 +As well as checking their status in that regard.
55 +Running the Application
56 +-----------------------
58 +The tool has a number of command line options:
60 +.. code-block:: console
62 + dpdk-devbind [options] DEVICE1 DEVICE2 ....
67 +* ``--help, --usage``
69 + Display usage information and quit
73 + Print the current status of all known network interfaces.
74 + For each device, it displays the PCI domain, bus, slot and function,
75 + along with a text description of the device. Depending upon whether the
76 + device is being used by a kernel driver, the ``igb_uio`` driver, or no
77 + driver, other relevant information will be displayed:
78 + - the Linux interface name e.g. ``if=eth0``
79 + - the driver being used e.g. ``drv=igb_uio``
80 + - any suitable drivers not currently using that device e.g. ``unused=igb_uio``
81 + NOTE: if this flag is passed along with a bind/unbind option, the
82 + status display will always occur after the other operations have taken
85 +* ``-b driver, --bind=driver``
87 + Select the driver to use or "none" to unbind the device
91 + Unbind a device (Equivalent to ``-b none``)
95 + By default, devices which are used by Linux - as indicated by having
96 + routes in the routing table - cannot be modified. Using the ``--force``
97 + flag overrides this behavior, allowing active links to be forcibly
99 + WARNING: This can lead to loss of network connection and should be used
105 + Due to the way VFIO works, there are certain limitations to which devices can be used with VFIO.
106 + Mainly it comes down to how IOMMU groups work.
107 + Any Virtual Function device can be used with VFIO on its own, but physical devices will require either all ports bound to VFIO,
108 + or some of them bound to VFIO while others not being bound to anything at all.
110 + 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.
111 + Therefore, the bridge driver should also be unbound from the bridge PCI device for VFIO to work with devices behind the bridge.
115 + While any user can run the ``dpdk-devbind.py`` script to view the status of the network ports,
116 + binding or unbinding network ports requires root privileges.
122 +To display current device status::
124 + dpdk-devbind --status
126 +To bind eth1 from the current driver and move to use igb_uio::
128 + dpdk-devbind --bind=igb_uio eth1
130 +To unbind 0000:01:00.0 from using any driver::
132 + dpdk-devbind -u 0000:01:00.0
134 +To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver::
136 + dpdk-devbind -b ixgbe 02:00.0 02:00.1
138 +To check status of all network ports, assign one to the igb_uio driver and check status again::
140 + # Check the status of the available devices.
141 + dpdk-devbind --status
142 + Network devices using DPDK-compatible driver
143 + ============================================
146 + Network devices using kernel driver
147 + ===================================
148 + 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
151 + # Bind the device to igb_uio.
152 + sudo dpdk-devbind -b igb_uio 0000:0a:00.0
155 + # Recheck the status of the devices.
156 + dpdk-devbind --status
157 + Network devices using DPDK-compatible driver
158 + ============================================
159 + 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused=
160 --- a/doc/guides/tools/index.rst
161 +++ b/doc/guides/tools/index.rst
168 --- a/mk/rte.sdkinstall.mk
169 +++ b/mk/rte.sdkinstall.mk
171 $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir)/man1)
172 $(Q)cp -a $O/doc/man/*/*.1 $(DESTDIR)$(mandir)/man1
174 +ifneq ($(wildcard $O/doc/man/*/*.8),)
175 + $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir))
176 + $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir)/man8)
177 + $(Q)cp -a $O/doc/man/*/*.8 $(DESTDIR)$(mandir)/man8
181 ifneq ($(wildcard $O/kmod/*),)