From: Rakesh Kudurumalla <rkuduruma...@marvell.com> It adds application user guide with detailed infomration about application's parameter, exposed commands by each module etc.
Signed-off-by: Sunil Kumar Kori <sk...@marvell.com> Signed-off-by: Rakesh Kudurumalla <rkuduruma...@marvell.com> --- doc/guides/tools/graph.rst | 240 +++++++++++++++++++ doc/guides/tools/img/graph-usecase-l3fwd.svg | 210 ++++++++++++++++ doc/guides/tools/index.rst | 1 + 3 files changed, 451 insertions(+) create mode 100644 doc/guides/tools/graph.rst create mode 100644 doc/guides/tools/img/graph-usecase-l3fwd.svg diff --git a/doc/guides/tools/graph.rst b/doc/guides/tools/graph.rst new file mode 100644 index 0000000000..52d732cc88 --- /dev/null +++ b/doc/guides/tools/graph.rst @@ -0,0 +1,240 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2023 Marvell. + +dpdk-graph Application +====================== + +The ``dpdk-graph`` tool is a Data Plane Development Kit (DPDK) +application that allows exercising various graph use cases. +This application has a generic framework to add new graph based use cases to +verify functionality. Each use case is defined as a ``<usecase>.cli`` file. +Based on the input file, application creates a graph to cater the use case. + +Supported Use cases +------------------- + * l3fwd + +Running the Application +----------------------- + +The application has a number of command line options which can be provided in +following syntax + +.. code-block:: console + + dpdk-graph [EAL Options] -- [application options] + +EAL Options +~~~~~~~~~~~ + +Following are the EAL command-line options that can be used in conjunction +with the ``dpdk-graph`` application. +See the DPDK Getting Started Guides for more information on these options. + +* ``-c <COREMASK>`` or ``-l <CORELIST>`` + + Set the hexadecimal bit mask of the cores to run on. The CORELIST is a + list of cores to be used. + +Application Options +~~~~~~~~~~~~~~~~~~~ + +Following are the application command-line options: + +* ``-h`` + + Set the host IPv4 address over which telnet session can be opened. + It is an optional parameter. Default host address is 0.0.0.0. + +* ``-p`` + + Set the L4 port number over which telnet session can be opened. + It is an optional parameter. Default port is 8086. + +* ``-s`` + + Script name with absolute path which specifies the use case. It is + a mandatory parameter which will be used to create desired graph + for a given use case. + +* ``--enable-graph-stats`` + + Enable graph statistics printing on console. By default graph statistics are disabled. + +* ``--help`` + + Dumps application usage + +Supported CLI commands +---------------------- + +This section provides details on commands which can be used in ``<usecase>.cli`` +file to express the requested use case configuration. + +.. list-table:: Exposed CLIs + :widths: 40 40 10 10 + :header-rows: 1 + :class: longtable + + * - Command + - Description + - Dynamic + - Optional + * - graph <usecases> [bsz <size>] [tmo <ns>] [coremask <bitmask>] model <rtc | mcd | default> + - Command to express the desired use case + - No + - No + * - graph start + - Command to start the graph. + This command triggers that no more commands are left to be parsed and graph + initialization can be started now. It must be the last command in ``<usecase>.cli`` + - No + - No + * - graph stats show + - Command to dump current graph statistics + - Yes + - Yes + * - help graph + - Command to dump graph help message + - Yes + - Yes + * - mempool <mempool_name> size <mbuf_size> buffers <number_of_buffers> cache <cache_size> numa <numa_id> + - Command to create mempool which will be further associated to RxQ to dequeue the packets + - No + - No + * - help mempool + - Command to dump mempool help message + - Yes + - Yes + * - ethdev <ethdev_name> rxq <n_queues> txq <n_queues> <mempool_name> + - Command to create DPDK port with given number of Rx and Tx queues. Also attached + RxQ with given mempool. Each port can have single mempool only i.e. all RxQs will + share the same mempool. + - No + - No + * - ethdev <ethdev_name> mtu <mtu_sz> + - Command to configure MTU of DPDK port + - Yes + - Yes + * - ethdev <ethdev_name> promiscuous <on/off> + - Command to enable/disable promiscuous mode on DPDK port + - Yes + - Yes + * - ethdev <ethdev_name> show + - Command to dump current ethdev configuration + - Yes + - Yes + * - ethdev <ethdev_name> stats + - Command to dump current ethdev statistics + - Yes + - Yes + * - ethdev <ethdev_name> ip4 addr add <ip> netmask <mask> + - Command to configure IPv4 address on given PCI device. It is needed if user + wishes to use ``ipv4_lookup`` node + - No + - Yes + * - ethdev <ethdev_name> ip6 addr add <ip> netmask <mask> + - Command to configure IPv6 address on given PCI device. It is needed if user + wishes to use ``ipv6_lookup`` node + - No + - Yes + * - help ethdev + - Command to dump ethdev help message + - Yes + - Yes + * - ipv4_lookup route add ipv4 <ip> netmask <mask> via <ip> + - Command to add a route into ``ipv4_lookup`` LPM table. It is needed if user + wishes to route the packets based on LPM lookup table. + - No + - Yes + * - help ipv4_lookup + - Command to dump ipv4_lookup help message + - Yes + - Yes + * - ipv6_lookup route add ipv6 <ip> netmask <mask> via <ip> + - Command to add a route into ``ipv6_lookup`` LPM table. It is needed if user + wishes to route the packets based on LPM6 lookup table. + - No + - Yes + * - help ipv6_lookup + - Command to dump ipv6_lookup help message + - Yes + - Yes + * - neigh add ipv4 <ip> <mac> + - Command to add a neighbour information into ``ipv4_rewrite`` node. + - No + - Yes + * - neigh add ipv6 <ip> <mac> + - Command to add a neighbour information into ``ipv6_rewrite`` node. + - No + - Yes + * - help neigh + - Command to dump neigh help message + - Yes + - Yes + * - ethdev_rx map port <ethdev_name> queue <q_num> core <core_id> + - Command to add port-queue-core mapping to ``ethdev_rx`` node. ``ethdev_rx`` + node instance will be pinned on given core and will poll on requested + port/queue pair. + - No + - No + * - help ethdev_rx + - Command to dump ethdev_rx help message + - Yes + - Yes + +Runtime configuration +--------------------- + +Application allows some configuration to be modified at runtime using a telnet session. +Application initiates a telnet server with host address ``0.0.0.0`` and port number ``8086`` +by default. + +if user passes ``-h`` and ``-p`` options while running application then corresponding +IPv4 address and port number will be used for telnet session. + +After successful launch of application, client can connect to application using given +host & port and console will be accessed with prompt ``graph>``. + +Command to access a telnet session + +.. code-block:: console + + telnet <host> <port> + +Example: ``dpdk-graph`` is started with -h 10.28.35.207 and -p 50000 then + +.. code-block:: console + + $ telnet 10.28.35.207 50000 + Trying 10.28.35.207... + Connected to 10.28.35.207. + Escape character is '^]'. + + Welcome! + + graph> + graph> + graph> help ethdev + + ----------------------------- ethdev command help ----------------------------- + ethdev <ethdev_name> rxq <n_queues> txq <n_queues> <mempool_name> + ethdev <ethdev_name> ip4 addr add <ip> netmask <mask> + ethdev <ethdev_name> ip6 addr add <ip> netmask <mask> + ethdev <ethdev_name> promiscuous <on/off> + ethdev <ethdev_name> mtu <mtu_sz> + ethdev <ethdev_name> show + graph> + +Created graph for use case +-------------------------- + +On the successful execution of ``<usecase>.cli`` file, corresponding graph will be created. +This section mentions the created graph for each use case. + +l3fwd +~~~~~ + +.. _figure_l3fwd_graph: + +.. figure:: img/graph-usecase-l3fwd.* diff --git a/doc/guides/tools/img/graph-usecase-l3fwd.svg b/doc/guides/tools/img/graph-usecase-l3fwd.svg new file mode 100644 index 0000000000..3b991c4cf0 --- /dev/null +++ b/doc/guides/tools/img/graph-usecase-l3fwd.svg @@ -0,0 +1,210 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd";> +<!-- Generated by graphviz version 2.43.0 (0) + --> +<!-- SPDX-License-Identifier: BSD-3-Clause --> +<!-- Copyright(C) 2023 Marvell. --> +<!-- + +Generated with following command +dot -Tsvg dot.dot -o doc/guides/tools/img/graph-usecase-l3fwd.svg + +cat dot.dot +digraph dpdk_app_graph_l3fwd_nodes_flow { + ingress_port [shape=rect] + ethdev_rx + pkt_cls + ip4_lookup + ip6_lookup + ip4_rewrite + ip6_rewrite + ethdev_tx + pkt_drop + egress_port [shape=rect] + + ingress_port -> ethdev_rx [label="ingress packet"] + + ethdev_rx -> pkt_cls + + pkt_cls -> ip4_lookup [color="green"] + pkt_cls -> ip6_lookup [color="blue"] + pkt_cls -> pkt_drop [color="red" style="dashed"] + + ip4_lookup -> ip4_rewrite [color="green"] + ip4_lookup -> pkt_drop [color="red" style="dashed"] + + ip6_lookup -> ip6_rewrite [color="blue"] + ip6_lookup -> pkt_drop [color="red" style="dashed"] + + ip4_rewrite -> ethdev_tx [color="green"] + ip4_rewrite -> pkt_drop [color="red" style="dashed"] + + ip6_rewrite -> ethdev_tx [color="blue"] + ip6_rewrite -> pkt_drop [color="red" style="dashed"] + + ethdev_tx -> egress_port [label="egress packet"] + ethdev_tx -> pkt_drop [color="red" style="dashed"] +} + + --> +<!-- Title: dpdk_app_graph_l3fwd_nodes_flow Pages: 1 --> +<svg width="550pt" height="510pt" + viewBox="0.00 0.00 549.50 510.00" xmlns="http://www.w3.org/2000/svg"; xmlns:xlink="http://www.w3.org/1999/xlink";> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 506)"> +<title>dpdk_app_graph_l3fwd_nodes_flow</title> +<polygon fill="white" stroke="transparent" points="-4,4 -4,-506 545.5,-506 545.5,4 -4,4"/> +<!-- ingress_port --> +<g id="node1" class="node"> +<title>ingress_port</title> +<polygon fill="none" stroke="black" points="489.5,-502 383.5,-502 383.5,-466 489.5,-466 489.5,-502"/> +<text text-anchor="middle" x="436.5" y="-480.3" font-family="Times,serif" font-size="14.00">ingress_port</text> +</g> +<!-- ethdev_rx --> +<g id="node2" class="node"> +<title>ethdev_rx</title> +<ellipse fill="none" stroke="black" cx="436.5" cy="-397" rx="56.59" ry="18"/> +<text text-anchor="middle" x="436.5" y="-393.3" font-family="Times,serif" font-size="14.00">ethdev_rx</text> +</g> +<!-- ingress_port->ethdev_rx --> +<g id="edge1" class="edge"> +<title>ingress_port->ethdev_rx</title> +<path fill="none" stroke="black" d="M436.5,-465.8C436.5,-454.16 436.5,-438.55 436.5,-425.24"/> +<polygon fill="black" stroke="black" points="440,-425.18 436.5,-415.18 433,-425.18 440,-425.18"/> +<text text-anchor="middle" x="489" y="-436.8" font-family="Times,serif" font-size="14.00">ingress packet</text> +</g> +<!-- pkt_cls --> +<g id="node3" class="node"> +<title>pkt_cls</title> +<ellipse fill="none" stroke="black" cx="436.5" cy="-324" rx="42.79" ry="18"/> +<text text-anchor="middle" x="436.5" y="-320.3" font-family="Times,serif" font-size="14.00">pkt_cls</text> +</g> +<!-- ethdev_rx->pkt_cls --> +<g id="edge2" class="edge"> +<title>ethdev_rx->pkt_cls</title> +<path fill="none" stroke="black" d="M436.5,-378.81C436.5,-370.79 436.5,-361.05 436.5,-352.07"/> +<polygon fill="black" stroke="black" points="440,-352.03 436.5,-342.03 433,-352.03 440,-352.03"/> +</g> +<!-- ip4_lookup --> +<g id="node4" class="node"> +<title>ip4_lookup</title> +<ellipse fill="none" stroke="black" cx="436.5" cy="-251" rx="60.39" ry="18"/> +<text text-anchor="middle" x="436.5" y="-247.3" font-family="Times,serif" font-size="14.00">ip4_lookup</text> +</g> +<!-- pkt_cls->ip4_lookup --> +<g id="edge3" class="edge"> +<title>pkt_cls->ip4_lookup</title> +<path fill="none" stroke="green" d="M436.5,-305.81C436.5,-297.79 436.5,-288.05 436.5,-279.07"/> +<polygon fill="green" stroke="green" points="440,-279.03 436.5,-269.03 433,-279.03 440,-279.03"/> +</g> +<!-- ip6_lookup --> +<g id="node5" class="node"> +<title>ip6_lookup</title> +<ellipse fill="none" stroke="black" cx="297.5" cy="-251" rx="60.39" ry="18"/> +<text text-anchor="middle" x="297.5" y="-247.3" font-family="Times,serif" font-size="14.00">ip6_lookup</text> +</g> +<!-- pkt_cls->ip6_lookup --> +<g id="edge4" class="edge"> +<title>pkt_cls->ip6_lookup</title> +<path fill="none" stroke="blue" d="M410.36,-309.65C389.39,-298.94 359.66,-283.75 335.97,-271.65"/> +<polygon fill="blue" stroke="blue" points="337.39,-268.45 326.9,-267.02 334.21,-274.68 337.39,-268.45"/> +</g> +<!-- pkt_drop --> +<g id="node9" class="node"> +<title>pkt_drop</title> +<ellipse fill="none" stroke="black" cx="361.5" cy="-18" rx="51.99" ry="18"/> +<text text-anchor="middle" x="361.5" y="-14.3" font-family="Times,serif" font-size="14.00">pkt_drop</text> +</g> +<!-- pkt_cls->pkt_drop --> +<g id="edge5" class="edge"> +<title>pkt_cls->pkt_drop</title> +<path fill="none" stroke="red" stroke-dasharray="5,2" d="M468.77,-311.93C493.88,-301.02 524.5,-281.64 524.5,-252 524.5,-252 524.5,-252 524.5,-104 524.5,-55.68 467.5,-34.79 420.91,-25.78"/> +<polygon fill="red" stroke="red" points="421.31,-22.29 410.85,-23.98 420.08,-29.18 421.31,-22.29"/> +</g> +<!-- ip4_rewrite --> +<g id="node6" class="node"> +<title>ip4_rewrite</title> +<ellipse fill="none" stroke="black" cx="394.5" cy="-178" rx="63.89" ry="18"/> +<text text-anchor="middle" x="394.5" y="-174.3" font-family="Times,serif" font-size="14.00">ip4_rewrite</text> +</g> +<!-- ip4_lookup->ip4_rewrite --> +<g id="edge6" class="edge"> +<title>ip4_lookup->ip4_rewrite</title> +<path fill="none" stroke="green" d="M426.55,-233.17C421.55,-224.72 415.38,-214.29 409.79,-204.85"/> +<polygon fill="green" stroke="green" points="412.78,-203.02 404.67,-196.2 406.75,-206.59 412.78,-203.02"/> +</g> +<!-- ip4_lookup->pkt_drop --> +<g id="edge7" class="edge"> +<title>ip4_lookup->pkt_drop</title> +<path fill="none" stroke="red" stroke-dasharray="5,2" d="M449.33,-233.03C456.19,-222.87 463.94,-209.37 467.5,-196 471.62,-180.54 472.57,-175.18 467.5,-160 451.61,-112.41 412.64,-67.99 386.65,-42.17"/> +<polygon fill="red" stroke="red" points="388.97,-39.54 379.36,-35.08 384.09,-44.56 388.97,-39.54"/> +</g> +<!-- ip6_rewrite --> +<g id="node7" class="node"> +<title>ip6_rewrite</title> +<ellipse fill="none" stroke="black" cx="210.5" cy="-178" rx="63.89" ry="18"/> +<text text-anchor="middle" x="210.5" y="-174.3" font-family="Times,serif" font-size="14.00">ip6_rewrite</text> +</g> +<!-- ip6_lookup->ip6_rewrite --> +<g id="edge8" class="edge"> +<title>ip6_lookup->ip6_rewrite</title> +<path fill="none" stroke="blue" d="M277.76,-233.89C266.16,-224.42 251.31,-212.31 238.52,-201.87"/> +<polygon fill="blue" stroke="blue" points="240.43,-198.9 230.46,-195.29 236,-204.33 240.43,-198.9"/> +</g> +<!-- ip6_lookup->pkt_drop --> +<g id="edge9" class="edge"> +<title>ip6_lookup->pkt_drop</title> +<path fill="none" stroke="red" stroke-dasharray="5,2" d="M302.02,-232.72C306.79,-214.59 314.55,-185.26 321.5,-160 332.39,-120.41 345.45,-74.7 353.61,-46.32"/> +<polygon fill="red" stroke="red" points="357.08,-46.92 356.49,-36.34 350.35,-44.98 357.08,-46.92"/> +</g> +<!-- ethdev_tx --> +<g id="node8" class="node"> +<title>ethdev_tx</title> +<ellipse fill="none" stroke="black" cx="249.5" cy="-105" rx="55.79" ry="18"/> +<text text-anchor="middle" x="249.5" y="-101.3" font-family="Times,serif" font-size="14.00">ethdev_tx</text> +</g> +<!-- ip4_rewrite->ethdev_tx --> +<g id="edge10" class="edge"> +<title>ip4_rewrite->ethdev_tx</title> +<path fill="none" stroke="green" d="M364.1,-162.12C341.96,-151.27 311.81,-136.51 287.98,-124.84"/> +<polygon fill="green" stroke="green" points="289.39,-121.63 278.87,-120.38 286.31,-127.92 289.39,-121.63"/> +</g> +<!-- ip4_rewrite->pkt_drop --> +<g id="edge11" class="edge"> +<title>ip4_rewrite->pkt_drop</title> +<path fill="none" stroke="red" stroke-dasharray="5,2" d="M390.91,-159.79C385.2,-132.48 374.03,-78.99 367.22,-46.38"/> +<polygon fill="red" stroke="red" points="370.56,-45.26 365.09,-36.19 363.71,-46.69 370.56,-45.26"/> +</g> +<!-- ip6_rewrite->ethdev_tx --> +<g id="edge12" class="edge"> +<title>ip6_rewrite->ethdev_tx</title> +<path fill="none" stroke="blue" d="M219.74,-160.17C224.34,-151.81 230,-141.51 235.14,-132.14"/> +<polygon fill="blue" stroke="blue" points="238.31,-133.65 240.05,-123.2 232.17,-130.28 238.31,-133.65"/> +</g> +<!-- ip6_rewrite->pkt_drop --> +<g id="edge13" class="edge"> +<title>ip6_rewrite->pkt_drop</title> +<path fill="none" stroke="red" stroke-dasharray="5,2" d="M197.68,-160.05C184.87,-140.87 169.12,-109.39 184.5,-87 210.62,-48.98 261.18,-32.21 301.59,-24.82"/> +<polygon fill="red" stroke="red" points="302.35,-28.24 311.63,-23.13 301.19,-21.33 302.35,-28.24"/> +</g> +<!-- ethdev_tx->pkt_drop --> +<g id="edge15" class="edge"> +<title>ethdev_tx->pkt_drop</title> +<path fill="none" stroke="red" stroke-dasharray="5,2" d="M270.3,-88.21C287.91,-74.85 313.31,-55.57 332.84,-40.75"/> +<polygon fill="red" stroke="red" points="334.96,-43.54 340.81,-34.7 330.73,-37.96 334.96,-43.54"/> +</g> +<!-- egress_port --> +<g id="node10" class="node"> +<title>egress_port</title> +<polygon fill="none" stroke="black" points="101,-36 0,-36 0,0 101,0 101,-36"/> +<text text-anchor="middle" x="50.5" y="-14.3" font-family="Times,serif" font-size="14.00">egress_port</text> +</g> +<!-- ethdev_tx->egress_port --> +<g id="edge14" class="edge"> +<title>ethdev_tx->egress_port</title> +<path fill="none" stroke="black" d="M217.08,-90.15C185.34,-76.59 136.54,-55.75 99.95,-40.12"/> +<polygon fill="black" stroke="black" points="101.03,-36.78 90.45,-36.07 98.28,-43.21 101.03,-36.78"/> +<text text-anchor="middle" x="211.5" y="-57.8" font-family="Times,serif" font-size="14.00">egress packet</text> +</g> +</g> +</svg> diff --git a/doc/guides/tools/index.rst b/doc/guides/tools/index.rst index f2afb1fcc5..4f4dc8b518 100644 --- a/doc/guides/tools/index.rst +++ b/doc/guides/tools/index.rst @@ -23,4 +23,5 @@ DPDK Tools User Guides testeventdev testregex testmldev + graph dts -- 2.25.1
