1 diff --git a/doc/guides/conf.py b/doc/guides/conf.py
2 index c45c4be..149bcdb 100644
3 --- a/doc/guides/conf.py
4 +++ b/doc/guides/conf.py
5 @@ -113,7 +113,9 @@ man_pages = [("testpmd_app_ug/run_app", "testpmd",
6 ("tools/proc_info", "dpdk-procinfo",
7 "access dpdk port stats and memory info", "", 1),
8 ("tools/pmdinfo", "dpdk-pmdinfo",
9 - "dump a PMDs hardware support info", "", 1)]
10 + "dump a PMDs hardware support info", "", 1),
11 + ("tools/devbind", "dpdk-devbind",
12 + "check device status and bind/unbind them from drivers", "", 8)]
14 ######## :numref: fallback ########
15 # The following hook functions add some simple handling for the :numref:
16 diff --git a/doc/guides/tools/devbind.rst b/doc/guides/tools/devbind.rst
18 index 0000000..18a8059
20 +++ b/doc/guides/tools/devbind.rst
24 + Copyright(c) 2016 Canonical Limited. All rights reserved.
26 + Redistribution and use in source and binary forms, with or without
27 + modification, are permitted provided that the following conditions
30 + * Redistributions of source code must retain the above copyright
31 + notice, this list of conditions and the following disclaimer.
32 + * Redistributions in binary form must reproduce the above copyright
33 + notice, this list of conditions and the following disclaimer in
34 + the documentation and/or other materials provided with the
36 + * Neither the name of Intel Corporation nor the names of its
37 + contributors may be used to endorse or promote products derived
38 + from this software without specific prior written permission.
40 + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
41 + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
42 + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
43 + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
44 + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45 + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
46 + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
47 + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
48 + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
49 + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
50 + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
53 +dpdk-devbind Application
54 +========================
56 +The ``dpdk-devbind`` tool is a Data Plane Development Kit (DPDK) tool that helps binding and unbinding devices from specific drivers.
57 +As well as checking their status in that regard.
60 +Running the Application
61 +-----------------------
63 +The tool has a number of command line options:
65 +.. code-block:: console
67 + dpdk-devbind [options] DEVICE1 DEVICE2 ....
72 +* ``--help, --usage``
74 + Display usage information and quit
78 + Print the current status of all known network interfaces.
79 + For each device, it displays the PCI domain, bus, slot and function,
80 + along with a text description of the device. Depending upon whether the
81 + device is being used by a kernel driver, the ``igb_uio`` driver, or no
82 + driver, other relevant information will be displayed:
83 + - the Linux interface name e.g. ``if=eth0``
84 + - the driver being used e.g. ``drv=igb_uio``
85 + - any suitable drivers not currently using that device e.g. ``unused=igb_uio``
86 + NOTE: if this flag is passed along with a bind/unbind option, the
87 + status display will always occur after the other operations have taken
90 +* ``-b driver, --bind=driver``
92 + Select the driver to use or "none" to unbind the device
96 + Unbind a device (Equivalent to ``-b none``)
100 + By default, devices which are used by Linux - as indicated by having
101 + routes in the routing table - cannot be modified. Using the ``--force``
102 + flag overrides this behavior, allowing active links to be forcibly
104 + WARNING: This can lead to loss of network connection and should be used
110 + Due to the way VFIO works, there are certain limitations to which devices can be used with VFIO.
111 + Mainly it comes down to how IOMMU groups work.
112 + Any Virtual Function device can be used with VFIO on its own, but physical devices will require either all ports bound to VFIO,
113 + or some of them bound to VFIO while others not being bound to anything at all.
115 + 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.
116 + Therefore, the bridge driver should also be unbound from the bridge PCI device for VFIO to work with devices behind the bridge.
120 + While any user can run the ``dpdk-devbind.py`` script to view the status of the network ports,
121 + binding or unbinding network ports requires root privileges.
127 +To display current device status::
129 + dpdk-devbind --status
131 +To bind eth1 from the current driver and move to use igb_uio::
133 + dpdk-devbind --bind=igb_uio eth1
135 +To unbind 0000:01:00.0 from using any driver::
137 + dpdk-devbind -u 0000:01:00.0
139 +To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver::
141 + dpdk-devbind -b ixgbe 02:00.0 02:00.1
143 +To check status of all network ports, assign one to the igb_uio driver and check status again::
145 + # Check the status of the available devices.
146 + dpdk-devbind --status
147 + Network devices using DPDK-compatible driver
148 + ============================================
151 + Network devices using kernel driver
152 + ===================================
153 + 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
156 + # Bind the device to igb_uio.
157 + sudo dpdk-devbind -b igb_uio 0000:0a:00.0
160 + # Recheck the status of the devices.
161 + dpdk-devbind --status
162 + Network devices using DPDK-compatible driver
163 + ============================================
164 + 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused=
165 diff --git a/doc/guides/tools/index.rst b/doc/guides/tools/index.rst
166 index 80f2115..cbe98b2 100644
167 --- a/doc/guides/tools/index.rst
168 +++ b/doc/guides/tools/index.rst
169 @@ -38,4 +38,5 @@ Tool User Guides
175 diff --git a/mk/rte.sdkinstall.mk b/mk/rte.sdkinstall.mk
176 index 533d369..b1faf28 100644
177 --- a/mk/rte.sdkinstall.mk
178 +++ b/mk/rte.sdkinstall.mk
179 @@ -139,6 +139,11 @@ ifneq ($(wildcard $O/doc/man/*/*.1),)
180 $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir)/man1)
181 $(Q)cp -a $O/doc/man/*/*.1 $(DESTDIR)$(mandir)/man1
183 +ifneq ($(wildcard $O/doc/man/*/*.8),)
184 + $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir))
185 + $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir)/man8)
186 + $(Q)cp -a $O/doc/man/*/*.8 $(DESTDIR)$(mandir)/man8
190 ifneq ($(wildcard $O/kmod/*),)