diff options
5 files changed, 866 insertions, 0 deletions
diff --git a/debian/patches/dpdk-dev-v2-1-4-doc-move-tool-guides-in-their-own-subdirectory.patch b/debian/patches/dpdk-dev-v2-1-4-doc-move-tool-guides-in-their-own-subdirectory.patch new file mode 100644 index 00000000..a1cc65c3 --- /dev/null +++ b/debian/patches/dpdk-dev-v2-1-4-doc-move-tool-guides-in-their-own-subdirectory.patch @@ -0,0 +1,528 @@ +diff --git a/doc/guides/index.rst b/doc/guides/index.rst +index 0441859..57570f6 100644 +--- a/doc/guides/index.rst ++++ b/doc/guides/index.rst +@@ -41,6 +41,7 @@ DPDK documentation + nics/index + cryptodevs/index + sample_app_ug/index ++ tools/index + testpmd_app_ug/index + faq/index + howto/index +diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst +index 96bb317..6573452 100644 +--- a/doc/guides/sample_app_ug/index.rst ++++ b/doc/guides/sample_app_ug/index.rst +@@ -72,11 +72,9 @@ Sample Applications User Guide + dist_app + vm_power_management + tep_termination +- proc_info + ptpclient + performance_thread + ipsec_secgw +- pdump + + **Figures** + +diff --git a/doc/guides/sample_app_ug/pdump.rst b/doc/guides/sample_app_ug/pdump.rst +deleted file mode 100644 +index ac0e7c9..0000000 +--- a/doc/guides/sample_app_ug/pdump.rst ++++ /dev/null +@@ -1,144 +0,0 @@ +- +-.. BSD LICENSE +- Copyright(c) 2016 Intel Corporation. All rights reserved. +- All rights reserved. +- +- Redistribution and use in source and binary forms, with or without +- modification, are permitted provided that the following conditions +- are met: +- +- * Redistributions of source code must retain the above copyright +- notice, this list of conditions and the following disclaimer. +- * Redistributions in binary form must reproduce the above copyright +- notice, this list of conditions and the following disclaimer in +- the documentation and/or other materials provided with the +- distribution. +- * Neither the name of Intel Corporation nor the names of its +- contributors may be used to endorse or promote products derived +- from this software without specific prior written permission. +- +- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +- +- +-dpdk-pdump Application +-====================== +- +-The ``dpdk-pdump`` tool is a Data Plane Development Kit (DPDK) tool that runs as +-a DPDK secondary process and is capable of enabling packet capture on dpdk ports. +- +- .. Note:: +- +- * The ``dpdk-pdump`` tool depends on libpcap based PMD which is disabled +- by default in the build configuration files, +- owing to an external dependency on the libpcap development files +- which must be installed on the board. +- Once the libpcap development files are installed, the libpcap based PMD +- can be enabled by setting CONFIG_RTE_LIBRTE_PMD_PCAP=y and recompiling the DPDK. +- +- +-Running the Application +------------------------ +- +-The tool has a number of command line options: +- +-.. code-block:: console +- +- ./build/app/dpdk-pdump -- +- --pdump '(port=<port id> | device_id=<pci id or vdev name>), +- (queue=<queue_id>), +- (rx-dev=<iface or pcap file> | +- tx-dev=<iface or pcap file>), +- [ring-size=<ring size>], +- [mbuf-size=<mbuf data size>], +- [total-num-mbufs=<number of mbufs>]' +- [--server-socket-path=<server socket dir>] +- [--client-socket-path=<client socket dir>] +- +-The ``--pdump`` command line option is mandatory and it takes various sub arguments which are described in +-below section. +- +- .. Note:: +- +- * Parameters inside the parentheses represents mandatory parameters. +- +- * Parameters inside the square brackets represents optional parameters. +- +- * Multiple instances of ``--pdump`` can be passed to capture packets on different port and queue combinations. +- +-The ``--server-socket-path`` command line option is optional. This represents the server socket directory. +-If no value is passed default values are used i.e. ``/var/run/.dpdk/`` for root users and ``~/.dpdk/`` +-for non root users. +- +-The ``--client-socket-path`` command line option is optional. This represents the client socket directory. +-If no value is passed default values are used i.e. ``/var/run/.dpdk/`` for root users and ``~/.dpdk/`` +-for non root users. +- +- +-The ``--pdump`` parameters +-~~~~~~~~~~~~~~~~~~~~~~~~~~ +- +-``port``: +-Port id of the eth device on which packets should be captured. +- +-``device_id``: +-PCI address (or) name of the eth device on which packets should be captured. +- +- .. Note:: +- +- * As of now the ``dpdk-pdump`` tool cannot capture the packets of virtual devices +- in the primary process due to a bug in the ethdev library. Due to this bug, in a multi process context, +- when the primary and secondary have different ports set, then the secondary process +- (here the ``dpdk-pdump`` tool) overwrites the ``rte_eth_devices[]`` entries of the primary process. +- +-``queue``: +-Queue id of the eth device on which packets should be captured. The user can pass a queue value of ``*`` to enable +-packet capture on all queues of the eth device. +- +-``rx-dev``: +-Can be either a pcap file name or any Linux iface. +- +-``tx-dev``: +-Can be either a pcap file name or any Linux iface. +- +- .. Note:: +- +- * To receive ingress packets only, ``rx-dev`` should be passed. +- +- * To receive egress packets only, ``tx-dev`` should be passed. +- +- * To receive ingress and egress packets separately ``rx-dev`` and ``tx-dev`` +- should both be passed with the different file names or the Linux iface names. +- +- * To receive ingress and egress packets separately ``rx-dev`` and ``tx-dev`` +- should both be passed with the same file names or the the Linux iface names. +- +-``ring-size``: +-Size of the ring. This value is used internally for ring creation. The ring will be used to enqueue the packets from +-the primary application to the secondary. This is an optional parameter with default size 16384. +- +-``mbuf-size``: +-Size of the mbuf data. This is used internally for mempool creation. Ideally this value must be same as +-the primary application's mempool's mbuf data size which is used for packet RX. This is an optional parameter with +-default size 2176. +- +-``total-num-mbufs``: +-Total number mbufs in mempool. This is used internally for mempool creation. This is an optional parameter with default +-value 65535. +- +- +-Example +-------- +- +-.. code-block:: console +- +- $ sudo ./build/app/dpdk-pdump -- --pdump 'port=0,queue=*,rx-dev=/tmp/rx.pcap' +diff --git a/doc/guides/sample_app_ug/proc_info.rst b/doc/guides/sample_app_ug/proc_info.rst +deleted file mode 100644 +index 73f2195..0000000 +--- a/doc/guides/sample_app_ug/proc_info.rst ++++ /dev/null +@@ -1,71 +0,0 @@ +- +-.. BSD LICENSE +- Copyright(c) 2015 Intel Corporation. All rights reserved. +- All rights reserved. +- +- Redistribution and use in source and binary forms, with or without +- modification, are permitted provided that the following conditions +- are met: +- +- * Redistributions of source code must retain the above copyright +- notice, this list of conditions and the following disclaimer. +- * Redistributions in binary form must reproduce the above copyright +- notice, this list of conditions and the following disclaimer in +- the documentation and/or other materials provided with the +- distribution. +- * Neither the name of Intel Corporation nor the names of its +- contributors may be used to endorse or promote products derived +- from this software without specific prior written permission. +- +- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +- +- +-dpdk-procinfo Application +-========================= +- +-The dpdk-procinfo application is a Data Plane Development Kit (DPDK) application +-that runs as a DPDK secondary process and is capable of retrieving port +-statistics, resetting port statistics and printing DPDK memory information. +-This application extends the original functionality that was supported by +-dump_cfg. +- +-Running the Application +------------------------ +-The application has a number of command line options: +- +-.. code-block:: console +- +- ./$(RTE_TARGET)/app/dpdk-procinfo -- -m | [-p PORTMASK] [--stats | --xstats | +- --stats-reset | --xstats-reset] +- +-Parameters +-~~~~~~~~~~ +-**-p PORTMASK**: Hexadecimal bitmask of ports to configure. +- +-**--stats** +-The stats parameter controls the printing of generic port statistics. If no +-port mask is specified stats are printed for all DPDK ports. +- +-**--xstats** +-The stats parameter controls the printing of extended port statistics. If no +-port mask is specified xstats are printed for all DPDK ports. +- +-**--stats-reset** +-The stats-reset parameter controls the resetting of generic port statistics. If +-no port mask is specified, the generic stats are reset for all DPDK ports. +- +-**--xstats-reset** +-The xstats-reset parameter controls the resetting of extended port statistics. +-If no port mask is specified xstats are reset for all DPDK ports. +- +-**-m**: Print DPDK memory information. +diff --git a/doc/guides/tools/index.rst b/doc/guides/tools/index.rst +new file mode 100644 +index 0000000..d7654a2 +--- /dev/null ++++ b/doc/guides/tools/index.rst +@@ -0,0 +1,40 @@ ++.. BSD LICENSE ++ Copyright(c) 2016 Canonical Limited. All rights reserved. ++ All rights reserved. ++ ++ Redistribution and use in source and binary forms, with or without ++ modification, are permitted provided that the following conditions ++ are met: ++ ++ * Redistributions of source code must retain the above copyright ++ notice, this list of conditions and the following disclaimer. ++ * Redistributions in binary form must reproduce the above copyright ++ notice, this list of conditions and the following disclaimer in ++ the documentation and/or other materials provided with the ++ distribution. ++ * Neither the name of Intel Corporation nor the names of its ++ contributors may be used to endorse or promote products derived ++ from this software without specific prior written permission. ++ ++ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ++ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT ++ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ++ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT ++ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ++ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT ++ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, ++ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY ++ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT ++ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE ++ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ++ ++Tool User Guides ++================ ++ ++.. toctree:: ++ :maxdepth: 2 ++ :numbered: ++ ++ proc_info ++ pdump ++ +diff --git a/doc/guides/tools/pdump.rst b/doc/guides/tools/pdump.rst +new file mode 100644 +index 0000000..ac0e7c9 +--- /dev/null ++++ b/doc/guides/tools/pdump.rst +@@ -0,0 +1,144 @@ ++ ++.. BSD LICENSE ++ Copyright(c) 2016 Intel Corporation. All rights reserved. ++ All rights reserved. ++ ++ Redistribution and use in source and binary forms, with or without ++ modification, are permitted provided that the following conditions ++ are met: ++ ++ * Redistributions of source code must retain the above copyright ++ notice, this list of conditions and the following disclaimer. ++ * Redistributions in binary form must reproduce the above copyright ++ notice, this list of conditions and the following disclaimer in ++ the documentation and/or other materials provided with the ++ distribution. ++ * Neither the name of Intel Corporation nor the names of its ++ contributors may be used to endorse or promote products derived ++ from this software without specific prior written permission. ++ ++ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ++ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT ++ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ++ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT ++ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ++ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT ++ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, ++ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY ++ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT ++ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE ++ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ++ ++ ++dpdk-pdump Application ++====================== ++ ++The ``dpdk-pdump`` tool is a Data Plane Development Kit (DPDK) tool that runs as ++a DPDK secondary process and is capable of enabling packet capture on dpdk ports. ++ ++ .. Note:: ++ ++ * The ``dpdk-pdump`` tool depends on libpcap based PMD which is disabled ++ by default in the build configuration files, ++ owing to an external dependency on the libpcap development files ++ which must be installed on the board. ++ Once the libpcap development files are installed, the libpcap based PMD ++ can be enabled by setting CONFIG_RTE_LIBRTE_PMD_PCAP=y and recompiling the DPDK. ++ ++ ++Running the Application ++----------------------- ++ ++The tool has a number of command line options: ++ ++.. code-block:: console ++ ++ ./build/app/dpdk-pdump -- ++ --pdump '(port=<port id> | device_id=<pci id or vdev name>), ++ (queue=<queue_id>), ++ (rx-dev=<iface or pcap file> | ++ tx-dev=<iface or pcap file>), ++ [ring-size=<ring size>], ++ [mbuf-size=<mbuf data size>], ++ [total-num-mbufs=<number of mbufs>]' ++ [--server-socket-path=<server socket dir>] ++ [--client-socket-path=<client socket dir>] ++ ++The ``--pdump`` command line option is mandatory and it takes various sub arguments which are described in ++below section. ++ ++ .. Note:: ++ ++ * Parameters inside the parentheses represents mandatory parameters. ++ ++ * Parameters inside the square brackets represents optional parameters. ++ ++ * Multiple instances of ``--pdump`` can be passed to capture packets on different port and queue combinations. ++ ++The ``--server-socket-path`` command line option is optional. This represents the server socket directory. ++If no value is passed default values are used i.e. ``/var/run/.dpdk/`` for root users and ``~/.dpdk/`` ++for non root users. ++ ++The ``--client-socket-path`` command line option is optional. This represents the client socket directory. ++If no value is passed default values are used i.e. ``/var/run/.dpdk/`` for root users and ``~/.dpdk/`` ++for non root users. ++ ++ ++The ``--pdump`` parameters ++~~~~~~~~~~~~~~~~~~~~~~~~~~ ++ ++``port``: ++Port id of the eth device on which packets should be captured. ++ ++``device_id``: ++PCI address (or) name of the eth device on which packets should be captured. ++ ++ .. Note:: ++ ++ * As of now the ``dpdk-pdump`` tool cannot capture the packets of virtual devices ++ in the primary process due to a bug in the ethdev library. Due to this bug, in a multi process context, ++ when the primary and secondary have different ports set, then the secondary process ++ (here the ``dpdk-pdump`` tool) overwrites the ``rte_eth_devices[]`` entries of the primary process. ++ ++``queue``: ++Queue id of the eth device on which packets should be captured. The user can pass a queue value of ``*`` to enable ++packet capture on all queues of the eth device. ++ ++``rx-dev``: ++Can be either a pcap file name or any Linux iface. ++ ++``tx-dev``: ++Can be either a pcap file name or any Linux iface. ++ ++ .. Note:: ++ ++ * To receive ingress packets only, ``rx-dev`` should be passed. ++ ++ * To receive egress packets only, ``tx-dev`` should be passed. ++ ++ * To receive ingress and egress packets separately ``rx-dev`` and ``tx-dev`` ++ should both be passed with the different file names or the Linux iface names. ++ ++ * To receive ingress and egress packets separately ``rx-dev`` and ``tx-dev`` ++ should both be passed with the same file names or the the Linux iface names. ++ ++``ring-size``: ++Size of the ring. This value is used internally for ring creation. The ring will be used to enqueue the packets from ++the primary application to the secondary. This is an optional parameter with default size 16384. ++ ++``mbuf-size``: ++Size of the mbuf data. This is used internally for mempool creation. Ideally this value must be same as ++the primary application's mempool's mbuf data size which is used for packet RX. This is an optional parameter with ++default size 2176. ++ ++``total-num-mbufs``: ++Total number mbufs in mempool. This is used internally for mempool creation. This is an optional parameter with default ++value 65535. ++ ++ ++Example ++------- ++ ++.. code-block:: console ++ ++ $ sudo ./build/app/dpdk-pdump -- --pdump 'port=0,queue=*,rx-dev=/tmp/rx.pcap' +diff --git a/doc/guides/tools/proc_info.rst b/doc/guides/tools/proc_info.rst +new file mode 100644 +index 0000000..73f2195 +--- /dev/null ++++ b/doc/guides/tools/proc_info.rst +@@ -0,0 +1,71 @@ ++ ++.. BSD LICENSE ++ Copyright(c) 2015 Intel Corporation. All rights reserved. ++ All rights reserved. ++ ++ Redistribution and use in source and binary forms, with or without ++ modification, are permitted provided that the following conditions ++ are met: ++ ++ * Redistributions of source code must retain the above copyright ++ notice, this list of conditions and the following disclaimer. ++ * Redistributions in binary form must reproduce the above copyright ++ notice, this list of conditions and the following disclaimer in ++ the documentation and/or other materials provided with the ++ distribution. ++ * Neither the name of Intel Corporation nor the names of its ++ contributors may be used to endorse or promote products derived ++ from this software without specific prior written permission. ++ ++ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ++ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT ++ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ++ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT ++ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ++ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT ++ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, ++ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY ++ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT ++ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE ++ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ++ ++ ++dpdk-procinfo Application ++========================= ++ ++The dpdk-procinfo application is a Data Plane Development Kit (DPDK) application ++that runs as a DPDK secondary process and is capable of retrieving port ++statistics, resetting port statistics and printing DPDK memory information. ++This application extends the original functionality that was supported by ++dump_cfg. ++ ++Running the Application ++----------------------- ++The application has a number of command line options: ++ ++.. code-block:: console ++ ++ ./$(RTE_TARGET)/app/dpdk-procinfo -- -m | [-p PORTMASK] [--stats | --xstats | ++ --stats-reset | --xstats-reset] ++ ++Parameters ++~~~~~~~~~~ ++**-p PORTMASK**: Hexadecimal bitmask of ports to configure. ++ ++**--stats** ++The stats parameter controls the printing of generic port statistics. If no ++port mask is specified stats are printed for all DPDK ports. ++ ++**--xstats** ++The stats parameter controls the printing of extended port statistics. If no ++port mask is specified xstats are printed for all DPDK ports. ++ ++**--stats-reset** ++The stats-reset parameter controls the resetting of generic port statistics. If ++no port mask is specified, the generic stats are reset for all DPDK ports. ++ ++**--xstats-reset** ++The xstats-reset parameter controls the resetting of extended port statistics. ++If no port mask is specified xstats are reset for all DPDK ports. ++ ++**-m**: Print DPDK memory information. diff --git a/debian/patches/dpdk-dev-v2-2-4-doc-rendering-and-installation-of-man-pages.patch b/debian/patches/dpdk-dev-v2-2-4-doc-rendering-and-installation-of-man-pages.patch new file mode 100644 index 00000000..f2e307f1 --- /dev/null +++ b/debian/patches/dpdk-dev-v2-2-4-doc-rendering-and-installation-of-man-pages.patch @@ -0,0 +1,56 @@ +diff --git a/doc/guides/conf.py b/doc/guides/conf.py +index cd6a4f7..55b6b2f 100644 +--- a/doc/guides/conf.py ++++ b/doc/guides/conf.py +@@ -105,6 +105,14 @@ class CustomLatexFormatter(LatexFormatter): + # Replace the default latex formatter. + PygmentsBridge.latex_formatter = CustomLatexFormatter + ++# Configuration for man pages ++man_pages = [("testpmd_app_ug/run_app", "testpmd", ++ "tests for dpdk pmds", "", 1), ++ ("tools/pdump", "dpdk-pdump", ++ "enable packet capture on dpdk ports", "", 1), ++ ("tools/proc_info", "dpdk-procinfo", ++ "access dpdk port stats and memory info", "", 1)] ++ + ######## :numref: fallback ######## + # The following hook functions add some simple handling for the :numref: + # directive for Sphinx versions prior to 1.3.1. The functions replace the +diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk +index 9952f25..21d9bdf 100644 +--- a/mk/rte.sdkdoc.mk ++++ b/mk/rte.sdkdoc.mk +@@ -63,7 +63,7 @@ help: + all: api-html guides-html guides-pdf + + .PHONY: clean +-clean: api-html-clean guides-html-clean guides-pdf-clean ++clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean + + .PHONY: api-html + api-html: api-html-clean +diff --git a/mk/rte.sdkinstall.mk b/mk/rte.sdkinstall.mk +index 5217063..533d369 100644 +--- a/mk/rte.sdkinstall.mk ++++ b/mk/rte.sdkinstall.mk +@@ -66,6 +66,7 @@ includedir ?= $(prefix)/include/dpdk + datarootdir ?= $(prefix)/share + docdir ?= $(datarootdir)/doc/dpdk + datadir ?= $(datarootdir)/dpdk ++mandir ?= $(datarootdir)/man + sdkdir ?= $(datadir) + targetdir ?= $(datadir)/$(RTE_TARGET) + +@@ -133,6 +134,11 @@ install-runtime: + $(DESTDIR)$(sbindir)/dpdk-devbind) + $(Q)$(call rte_symlink, $(DESTDIR)$(datadir)/tools/dpdk-pmdinfo.py, \ + $(DESTDIR)$(bindir)/dpdk-pmdinfo) ++ifneq ($(wildcard $O/doc/man/*/*.1),) ++ $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir)) ++ $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir)/man1) ++ $(Q)cp -a $O/doc/man/*/*.1 $(DESTDIR)$(mandir)/man1 ++endif + + install-kmod: + ifneq ($(wildcard $O/kmod/*),) diff --git a/debian/patches/dpdk-dev-v2-3-4-doc-add-basic-invocation-info-for-dpdk-pmdinfo.patch b/debian/patches/dpdk-dev-v2-3-4-doc-add-basic-invocation-info-for-dpdk-pmdinfo.patch new file mode 100644 index 00000000..ab0f9b4a --- /dev/null +++ b/debian/patches/dpdk-dev-v2-3-4-doc-add-basic-invocation-info-for-dpdk-pmdinfo.patch @@ -0,0 +1,88 @@ +diff --git a/doc/guides/conf.py b/doc/guides/conf.py +index 55b6b2f..c45c4be 100644 +--- a/doc/guides/conf.py ++++ b/doc/guides/conf.py +@@ -111,7 +111,9 @@ man_pages = [("testpmd_app_ug/run_app", "testpmd", + ("tools/pdump", "dpdk-pdump", + "enable packet capture on dpdk ports", "", 1), + ("tools/proc_info", "dpdk-procinfo", +- "access dpdk port stats and memory info", "", 1)] ++ "access dpdk port stats and memory info", "", 1), ++ ("tools/pmdinfo", "dpdk-pmdinfo", ++ "dump a PMDs hardware support info", "", 1)] + + ######## :numref: fallback ######## + # The following hook functions add some simple handling for the :numref: +diff --git a/doc/guides/tools/index.rst b/doc/guides/tools/index.rst +index d7654a2..80f2115 100644 +--- a/doc/guides/tools/index.rst ++++ b/doc/guides/tools/index.rst +@@ -37,4 +37,5 @@ Tool User Guides + + proc_info + pdump ++ pmdinfo + +diff --git a/doc/guides/tools/pmdinfo.rst b/doc/guides/tools/pmdinfo.rst +new file mode 100644 +index 0000000..a90c59f +--- /dev/null ++++ b/doc/guides/tools/pmdinfo.rst +@@ -0,0 +1,57 @@ ++ ++.. BSD LICENSE ++ Copyright(c) 2016 Canonical Limited. All rights reserved. ++ ++ Redistribution and use in source and binary forms, with or without ++ modification, are permitted provided that the following conditions ++ are met: ++ ++ * Redistributions of source code must retain the above copyright ++ notice, this list of conditions and the following disclaimer. ++ * Redistributions in binary form must reproduce the above copyright ++ notice, this list of conditions and the following disclaimer in ++ the documentation and/or other materials provided with the ++ distribution. ++ * Neither the name of Intel Corporation nor the names of its ++ contributors may be used to endorse or promote products derived ++ from this software without specific prior written permission. ++ ++ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ++ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT ++ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ++ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT ++ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ++ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT ++ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, ++ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY ++ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT ++ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE ++ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ++ ++ ++dpdk-pmdinfo Application ++======================== ++ ++The ``dpdk-pmdinfo`` tool is a Data Plane Development Kit (DPDK) utility that ++can dump a PMDs hardware support info. ++ ++ ++Running the Application ++----------------------- ++ ++The tool has a number of command line options: ++ ++.. code-block:: console ++ ++ ++ dpdk-pmdinfo [-hrtp] [-d <pci id file] <elf-file> ++ ++ -h, --help Show a short help message and exit ++ -r, --raw Dump as raw json strings ++ -d FILE, --pcidb=FILE Specify a pci database to get vendor names from ++ -t, --table Output information on hw support as a hex table ++ -p, --plugindir Scan dpdk for autoload plugins ++ ++.. Note:: ++ ++ * Parameters inside the square brackets represents optional parameters. diff --git a/debian/patches/dpdk-dev-v2-4-4-doc-add-basic-invocation-info-for-dpdk-devbind.patch b/debian/patches/dpdk-dev-v2-4-4-doc-add-basic-invocation-info-for-dpdk-devbind.patch new file mode 100644 index 00000000..4b6c18da --- /dev/null +++ b/debian/patches/dpdk-dev-v2-4-4-doc-add-basic-invocation-info-for-dpdk-devbind.patch @@ -0,0 +1,190 @@ +diff --git a/doc/guides/conf.py b/doc/guides/conf.py +index c45c4be..149bcdb 100644 +--- a/doc/guides/conf.py ++++ b/doc/guides/conf.py +@@ -113,7 +113,9 @@ man_pages = [("testpmd_app_ug/run_app", "testpmd", + ("tools/proc_info", "dpdk-procinfo", + "access dpdk port stats and memory info", "", 1), + ("tools/pmdinfo", "dpdk-pmdinfo", +- "dump a PMDs hardware support info", "", 1)] ++ "dump a PMDs hardware support info", "", 1), ++ ("tools/devbind", "dpdk-devbind", ++ "check device status and bind/unbind them from drivers", "", 8)] + + ######## :numref: fallback ######## + # The following hook functions add some simple handling for the :numref: +diff --git a/doc/guides/tools/devbind.rst b/doc/guides/tools/devbind.rst +new file mode 100644 +index 0000000..18a8059 +--- /dev/null ++++ b/doc/guides/tools/devbind.rst +@@ -0,0 +1,143 @@ ++ ++.. BSD LICENSE ++ Copyright(c) 2016 Canonical Limited. All rights reserved. ++ ++ Redistribution and use in source and binary forms, with or without ++ modification, are permitted provided that the following conditions ++ are met: ++ ++ * Redistributions of source code must retain the above copyright ++ notice, this list of conditions and the following disclaimer. ++ * Redistributions in binary form must reproduce the above copyright ++ notice, this list of conditions and the following disclaimer in ++ the documentation and/or other materials provided with the ++ distribution. ++ * Neither the name of Intel Corporation nor the names of its ++ contributors may be used to endorse or promote products derived ++ from this software without specific prior written permission. ++ ++ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ++ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT ++ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ++ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT ++ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ++ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT ++ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, ++ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY ++ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT ++ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE ++ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ++ ++ ++dpdk-devbind Application ++======================== ++ ++The ``dpdk-devbind`` tool is a Data Plane Development Kit (DPDK) tool that helps binding and unbinding devices from specific drivers. ++As well as checking their status in that regard. ++ ++ ++Running the Application ++----------------------- ++ ++The tool has a number of command line options: ++ ++.. code-block:: console ++ ++ dpdk-devbind [options] DEVICE1 DEVICE2 .... ++ ++OPTIONS ++------- ++ ++* ``--help, --usage`` ++ ++ Display usage information and quit ++ ++* ``-s, --status`` ++ ++ Print the current status of all known network interfaces. ++ For each device, it displays the PCI domain, bus, slot and function, ++ along with a text description of the device. Depending upon whether the ++ device is being used by a kernel driver, the ``igb_uio`` driver, or no ++ driver, other relevant information will be displayed: ++ - the Linux interface name e.g. ``if=eth0`` ++ - the driver being used e.g. ``drv=igb_uio`` ++ - any suitable drivers not currently using that device e.g. ``unused=igb_uio`` ++ NOTE: if this flag is passed along with a bind/unbind option, the ++ status display will always occur after the other operations have taken ++ place. ++ ++* ``-b driver, --bind=driver`` ++ ++ Select the driver to use or "none" to unbind the device ++ ++* ``-u, --unbind`` ++ ++ Unbind a device (Equivalent to ``-b none``) ++ ++* ``--force`` ++ ++ By default, devices which are used by Linux - as indicated by having ++ routes in the routing table - cannot be modified. Using the ``--force`` ++ flag overrides this behavior, allowing active links to be forcibly ++ unbound. ++ WARNING: This can lead to loss of network connection and should be used ++ with caution. ++ ++ ++.. 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. ++ ++ ++Examples ++-------- ++ ++To display current device status:: ++ ++ dpdk-devbind --status ++ ++To bind eth1 from the current driver and move to use igb_uio:: ++ ++ dpdk-devbind --bind=igb_uio eth1 ++ ++To unbind 0000:01:00.0 from using any driver:: ++ ++ dpdk-devbind -u 0000:01:00.0 ++ ++To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver:: ++ ++ dpdk-devbind -b ixgbe 02:00.0 02:00.1 ++ ++To check status of all network ports, assign one to the igb_uio driver and check status again:: ++ ++ # Check the status of the available devices. ++ dpdk-devbind --status ++ Network devices using DPDK-compatible driver ++ ============================================ ++ <none> ++ ++ Network devices using kernel driver ++ =================================== ++ 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused= ++ ++ ++ # Bind the device to igb_uio. ++ sudo dpdk-devbind -b igb_uio 0000:0a:00.0 ++ ++ ++ # Recheck the status of the devices. ++ dpdk-devbind --status ++ Network devices using DPDK-compatible driver ++ ============================================ ++ 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused= +diff --git a/doc/guides/tools/index.rst b/doc/guides/tools/index.rst +index 80f2115..cbe98b2 100644 +--- a/doc/guides/tools/index.rst ++++ b/doc/guides/tools/index.rst +@@ -38,4 +38,5 @@ Tool User Guides + proc_info + pdump + pmdinfo ++ devbind + +diff --git a/mk/rte.sdkinstall.mk b/mk/rte.sdkinstall.mk +index 533d369..b1faf28 100644 +--- a/mk/rte.sdkinstall.mk ++++ b/mk/rte.sdkinstall.mk +@@ -139,6 +139,11 @@ ifneq ($(wildcard $O/doc/man/*/*.1),) + $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir)/man1) + $(Q)cp -a $O/doc/man/*/*.1 $(DESTDIR)$(mandir)/man1 + endif ++ifneq ($(wildcard $O/doc/man/*/*.8),) ++ $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir)) ++ $(Q)$(call rte_mkdir, $(DESTDIR)$(mandir)/man8) ++ $(Q)cp -a $O/doc/man/*/*.8 $(DESTDIR)$(mandir)/man8 ++endif + + install-kmod: + ifneq ($(wildcard $O/kmod/*),) diff --git a/debian/patches/series b/debian/patches/series index 31c7f389..13c6c03e 100644 --- a/debian/patches/series +++ b/debian/patches/series @@ -6,3 +6,7 @@ make-load-devel-config-not-to-appear-as-executable.patch rte-compile-pre-cppflags.patch fix-power-default-config.patch rte-devel-build-env.patch +dpdk-dev-v2-1-4-doc-move-tool-guides-in-their-own-subdirectory.patch +dpdk-dev-v2-2-4-doc-rendering-and-installation-of-man-pages.patch +dpdk-dev-v2-3-4-doc-add-basic-invocation-info-for-dpdk-pmdinfo.patch +dpdk-dev-v2-4-4-doc-add-basic-invocation-info-for-dpdk-devbind.patch |