From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from youngberry.canonical.com (youngberry.canonical.com [91.189.89.112]) by dpdk.org (Postfix) with ESMTP id B235E2BD2 for ; Wed, 31 Aug 2016 09:50:17 +0200 (CEST) Received: from 1.general.paelzer.uk.vpn ([10.172.196.172] helo=localhost.localdomain) by youngberry.canonical.com with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.76) (envelope-from ) id 1bf0Hp-00011w-DB; Wed, 31 Aug 2016 07:50:17 +0000 From: Christian Ehrhardt To: christian.ehrhardt@canonical.com, thomas.monjalon@6wind.com, dev@dpdk.org Date: Wed, 31 Aug 2016 09:50:09 +0200 Message-Id: <1472629812-4397-2-git-send-email-christian.ehrhardt@canonical.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1472629812-4397-1-git-send-email-christian.ehrhardt@canonical.com> References: <1472629812-4397-1-git-send-email-christian.ehrhardt@canonical.com> Subject: [dpdk-dev] [PATCH v2 1/4] doc: move tool guides in their own subdirectory X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 31 Aug 2016 07:50:18 -0000 This is to clarify the scope of these documents that are more tools than sample applications. Also this is a preparation step to add more tools and generate man pages off of their rst files. Signed-off-by: Christian Ehrhardt --- doc/guides/index.rst | 1 + doc/guides/sample_app_ug/index.rst | 2 - doc/guides/sample_app_ug/pdump.rst | 144 --------------------------------- doc/guides/sample_app_ug/proc_info.rst | 71 ---------------- doc/guides/tools/index.rst | 40 +++++++++ doc/guides/tools/pdump.rst | 144 +++++++++++++++++++++++++++++++++ doc/guides/tools/proc_info.rst | 71 ++++++++++++++++ 7 files changed, 256 insertions(+), 217 deletions(-) delete mode 100644 doc/guides/sample_app_ug/pdump.rst delete mode 100644 doc/guides/sample_app_ug/proc_info.rst create mode 100644 doc/guides/tools/index.rst create mode 100644 doc/guides/tools/pdump.rst create mode 100644 doc/guides/tools/proc_info.rst 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= | device_id=), - (queue=), - (rx-dev= | - tx-dev=), - [ring-size=], - [mbuf-size=], - [total-num-mbufs=]' - [--server-socket-path=] - [--client-socket-path=] - -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= | device_id=), + (queue=), + (rx-dev= | + tx-dev=), + [ring-size=], + [mbuf-size=], + [total-num-mbufs=]' + [--server-socket-path=] + [--client-socket-path=] + +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. -- 2.7.4