new file mode 100644
@@ -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.*
new file mode 100644
@@ -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>
@@ -23,4 +23,5 @@ DPDK Tools User Guides
testeventdev
testregex
testmldev
+ graph
dts