DPDK patches and discussions
 help / color / mirror / Atom feed
From: <guyk@marvell.com>
To: <thomas@monjalon.net>, <orika@mellanox.com>,
	<john.mcnamara@intel.com>, <marko.kovacevic@intel.com>
Cc: <dev@dpdk.org>, <guyk@marvell.com>, <jerinj@marvell.com>,
	<smadarf@marvell.com>, <dovrat@marvell.com>
Subject: [dpdk-dev] [PATCH 2/2] doc: add l3fwd-regex application user guide
Date: Tue, 8 Sep 2020 15:31:44 +0300	[thread overview]
Message-ID: <20200908123144.26444-3-guyk@marvell.com> (raw)
In-Reply-To: <20200908123144.26444-1-guyk@marvell.com>

From: Guy Kaneti <guyk@marvell.com>

Adding the user guide for l3fwd regex application.

Signed-off-by: Guy Kaneti <guyk@marvell.com>
---
 MAINTAINERS                                   |   1 +
 doc/guides/sample_app_ug/index.rst            |   1 +
 doc/guides/sample_app_ug/intro.rst            |   4 +
 doc/guides/sample_app_ug/l3_forward_regex.rst | 235 ++++++++++++++++++
 4 files changed, 241 insertions(+)
 create mode 100644 doc/guides/sample_app_ug/l3_forward_regex.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index a73845a2d..af8a803ea 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -453,6 +453,7 @@ F: doc/guides/prog_guide/regexdev.rst
 F: doc/guides/regexdevs/features/default.ini
 M: Guy Kaneti <guyk@marvell.com>
 F: examples/l3fwd-regex/
+F: doc/guides/sample_app_ug/l3_forward_regex.rst
 
 Eventdev API
 M: Jerin Jacob <jerinj@marvell.com>
diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
index affa9c574..dc67580af 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -32,6 +32,7 @@ Sample Applications User Guides
     l3_forward_graph
     l3_forward_power_man
     l3_forward_access_ctrl
+    l3_forward_regex
     link_status_intr
     server_node_efd
     service_cores
diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst
index 8ff223b16..94070933b 100644
--- a/doc/guides/sample_app_ug/intro.rst
+++ b/doc/guides/sample_app_ug/intro.rst
@@ -58,6 +58,10 @@ examples are highlighted below.
   forwarding Graph, or ``l3fwd_graph`` application does forwarding based on IPv4
   like a simple router with DPDK Graph framework.
 
+* :doc:`Network Layer 3 forwarding Regex<l3_forward_regex>`: The Network Layer3
+  forwarding Regex, or ``l3fwd-regex`` application does forwarding based on IPv4
+  like a simple router with DPDK Regex framework.
+
 * :doc:`Hardware packet copying<ioat>`: The Hardware packet copying,
   or ``ioatfwd`` application demonstrates how to use IOAT rawdev driver for
   copying packets between two threads.
diff --git a/doc/guides/sample_app_ug/l3_forward_regex.rst b/doc/guides/sample_app_ug/l3_forward_regex.rst
new file mode 100644
index 000000000..bb11884a3
--- /dev/null
+++ b/doc/guides/sample_app_ug/l3_forward_regex.rst
@@ -0,0 +1,235 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(C) 2020 Marvell International Ltd.
+
+L3 Forwarding Regex Sample Application
+======================================
+
+The L3 Forwarding with Regex application is a simple example of packet processing using DPDK Regex framework.
+The application performs L3 LPM based forwarding while using Regex framework for pre-filtering decision.
+
+Overview
+--------
+
+The application demonstrates the use of the Regex libraries in DPDK to implement packet forwarding.
+The initialization is very similar to those of the :doc:`l3_forward`.
+There is also additional initialization of Regex device and configuration per lcore.
+The main difference from the L3 Forwarding sample application is that this application introduces
+Regex based pre-filtering decision done before LPM lookup.
+Thus, packet can be dropped or flagged before the forwarding decision.
+
+In the sample application, only IPv4 forwarding is supported as of now.
+
+Compiling the Application
+-------------------------
+
+To compile the sample application see :doc:`compiling`.
+
+The application is located in the ``l3fwd-regex`` sub-directory.
+
+Running the Application
+-----------------------
+
+The application has a number of command line options similar to l3fwd::
+
+    ./l3fwd-graph [EAL options] -- -p PORTMASK
+                                   [-P]
+                                   --config (port,queue,lcore,regex-dev,regex-q)[,(port,queue,lcore,regex-dev,regex-q)]
+                                   [--regex-rule-db-file FILENAME
+                                   [--regex-drop]
+                                   [--eth-dest=X,MM:MM:MM:MM:MM:MM]
+                                   [--enable-jumbo [--max-pkt-len PKTLEN]]
+                                   [--no-numa]
+                                   [--parse-ptype]
+                                   [--per-port-pool]
+                                   [--regex-drop]
+                                   [--regex-debug]
+
+Where,
+
+* ``-p PORTMASK:`` Hexadecimal bitmask of ports to configure
+
+* ``-P:`` Optional, sets all ports to promiscuous mode so that packets are accepted regardless of the packet's Ethernet MAC destination address.
+  Without this option, only packets with the Ethernet MAC destination address set to the Ethernet address of the port are accepted.
+
+* ``--config (port,queue,lcore,regex-dev,regex-q)[,(port,queue,lcore,regex-dev,regex-q)]:`` Determines which queues from which ports are mapped
+  to which cores, and which Regex device and queues to use.
+
+* ``--regex-rule-db-file FILENAME:`` prebuilt rule database to configure Regex device with.
+
+* ``--eth-dest=X,MM:MM:MM:MM:MM:MM:`` Optional, ethernet destination for port X.
+
+* ``--enable-jumbo:`` Optional, enables jumbo frames.
+
+*   --max-pkt-len: Optional, under the premise of enabling jumbo, maximum packet length in decimal (64-9600).
+
+* ``--no-numa:`` Optional, disables numa awareness.
+
+* ``--parse-ptype:`` Set to use software to analyze packet type.
+
+* ``--per-port-pool:`` Optional, set to use independent buffer pools per port. Without this option, single buffer pool is used for all ports.
+
+* ``--regex-drop:`` Enable Regex decision drop on match.
+
+* ``--regex-debug:`` Enable Regex debug printing.
+
+See :doc:`l3_forward` for details.
+The L3fwd-regex example reuses the L3fwd command line options.
+
+Refer to the *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options.
+
+.. _l3_fwd_regex_explanation:
+
+Explanation
+-----------
+
+The following sections provide some explanation of the sample application code.
+As mentioned in the overview section, the initialization is similar to that of the :doc:`l3_forward`.
+Run-time path though similar in functionality to that of :doc:`l3_forward`, includes a Regex based pre-filtering stage before forwarding.
+The following sections describe aspects that are specific to the L3 Forwarding Regex sample application.
+
+Regex Library Initialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Regex library is initialized during the l3fwd poll resource setup.
+The Regex device is configured with the input rule data base and each queue
+that was mapped with ``--config`` is setup.
+
+.. code-block:: c
+
+    /* ... */
+    ret = rte_regexdev_info_get(dev_id, &dev_info);
+    /* ... */
+
+    cfg.dev_cfg_flags = 0;
+    cfg.nb_max_matches = dev_info.max_matches;
+    cfg.nb_queue_pairs = nb_queue_pairs;
+    cfg.nb_rules_per_group = dev_info.max_rules_per_group;
+    cfg.nb_groups = dev_info.max_groups;
+    cfg.rule_db = conf->rule_db;
+    cfg.rule_db_len = conf->rule_db_len;
+    ret = rte_regexdev_configure(dev_id, &cfg);
+    /* ... */
+
+    qp_conf.qp_conf_flags = 0;
+    qp_conf.nb_desc = 8192;
+    qp_conf.cb = NULL;
+    for (i = 0; i < nb_queue_pairs; i++) {
+        ret = rte_regexdev_queue_pair_setup(dev_id, i, &qp_conf);
+        /* ... */
+        }
+    }
+
+After device and queue configuration there is a per lcore configuration,
+where a ``rte_regex_ops`` pool is created and initiliazed.
+
+.. code-block:: c
+
+    /* ... */
+    for (lcore_id = 0; lcore_id < RTE_MAX_LCORE; lcore_id++) {
+        if (rte_lcore_is_enabled(lcore_id) == 0)
+            continue;
+            /* ... */
+        ret = regex_lcore_init(lcore_id, qconf->regex_dev_id,
+                qconf->regex_qp_id);
+        /* ... */
+    }
+
+.. code-block:: c
+
+    int
+    regex_lcore_init(uint32_t lcore_id, uint32_t dev_id, uint32_t qp_id)
+    {
+        uint32_t i;
+
+        regex_lcore_conf[lcore_id].qp_id = qp_id;
+        regex_lcore_conf[lcore_id].dev_id = dev_id;
+
+        memset(&regex_lcore_params[lcore_id].stats, 0,
+                sizeof(struct regex_stats));
+
+        regex_lcore_conf[lcore_id].ops = rte_malloc("regex_ops",
+                REGEX_NB_OPS*sizeof(struct rte_regex_ops *),
+                0);
+        /* ... */
+        regex_lcore_conf[lcore_id].ops_pool = rte_malloc("regex_ops_pool",
+                REGEX_NB_OPS*sizeof(struct rte_regex_ops *),
+                0);
+        /* ... */
+        for (i = 0; i < REGEX_NB_OPS; i++) {
+            regex_lcore_conf[lcore_id].ops_pool[i] = rte_malloc("",
+                    REGEX_OPS_DATA_SIZE, 0);
+            /* ... */
+        }
+        regex_lcore_params[lcore_id].ops_head = 0;
+        regex_lcore_params[lcore_id].ops_tail = 0;
+        regex_lcore_params[lcore_id].ops_avail = REGEX_NB_OPS;
+
+        return 0;
+    }
+
+Packet Forwarding with Regex
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As part of slave lcores main loop, after packets are received from network port,
+they are sent to the Regex device to be matched against the programmed Regex rules.
+After that the REgex device is polled for responses during which the finished ops are checked for matches and an ops that had a match is counted.
+The finished Regex ops are sent to the forwarding decision.
+
+.. note::
+
+    packets that had a match will be dropped during the forwarding decision
+    if ``--regex-drop`` was given as an input to the application.
+
+.. code-block:: c
+
+    /* Main processing loop */
+
+    /* ... */
+
+     * Read packet from RX queues
+     */
+    for (i = 0; i < qconf->n_rx_queue; ++i) {
+        portid = qconf->rx_queue_list[i].port_id;
+        queueid = qconf->rx_queue_list[i].queue_id;
+        nb_rx = rte_eth_rx_burst(portid, queueid, pkts_burst,
+            MAX_PKT_BURST);
+        if (nb_rx == 0)
+            continue;
+        nb_ops = regex_enqueue_burst_ops(regex_dev_id,
+                lcore_id, regex_qp_id,
+                pkts_burst, nb_rx);
+        /* ... */
+
+        regex_nb_ops += nb_ops;
+
+        deq_cnt = regex_dequeue_burst_ops(regex_dev_id,
+                lcore_id, regex_qp_id,
+                pkts_burst, REGEX_NB_OPS);
+        if (deq_cnt) {
+            l3fwd_lpm_no_opt_send_packets(deq_cnt,
+                    pkts_burst,
+                    portid, qconf);
+            regex_nb_ops -= deq_cnt;
+        }
+
+    }
+
+During the Regex ops response processing, if ``--regex-drop`` was given as an input to the application,
+the packet is marked to be dropped, by setting ``mbuf->packet_type = RTE_PTYPE_UNKNOWN``.
+Because during the forwarding decision non-IP packets are dropped.
+
+.. code-block:: c
+
+    l3fwd_lpm_simple_forward(struct rte_mbuf *m, uint16_t portid,
+            struct lcore_conf *qconf)
+    {
+        /* ... */
+        if (RTE_ETH_IS_IPV4_HDR(m->packet_type)) {
+            /* ... */
+        } else if (RTE_ETH_IS_IPV6_HDR(m->packet_type)) {
+            /* ... */
+        } else {
+            /* Free the mbuf that contains non-IPV4/IPV6 packet */
+            rte_pktmbuf_free(m);
+        }
+    }
-- 
2.28.0


  parent reply	other threads:[~2020-09-08 12:33 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-09-08 12:31 [dpdk-dev] [PATCH 0/2] Add example l3fwd-regex guyk
2020-09-08 12:31 ` [dpdk-dev] [PATCH 1/2] examples/l3fwd-regex: add regex based l3fwd guyk
2020-10-14  8:47   ` Thomas Monjalon
2020-10-18 11:53     ` [dpdk-dev] [EXT] " Guy Kaneti
2020-10-18 13:32       ` Thomas Monjalon
2020-09-08 12:31 ` guyk [this message]
2020-09-09 12:08   ` [dpdk-dev] [PATCH v2 0/2] Add example l3fwd-regex guyk
2020-09-09 12:08     ` [dpdk-dev] [PATCH v2 1/2] examples/l3fwd-regex: add regex based l3fwd guyk
2020-10-07 13:44       ` Ori Kam
2020-10-14  8:50       ` Thomas Monjalon
2020-09-09 12:08     ` [dpdk-dev] [PATCH v2 2/2] doc: add l3fwd-regex application user guide guyk
2020-10-07 13:28       ` Ori Kam
2020-10-18 12:03   ` [dpdk-dev] [PATCH v3 0/2] Add example l3fwd-regex guyk
2020-10-18 12:03     ` [dpdk-dev] [PATCH v3 1/2] examples/l3fwd-regex: add regex based l3fwd guyk
2020-10-19 15:09       ` Ori Kam
2020-10-18 12:03     ` [dpdk-dev] [PATCH v3 2/2] doc: add l3fwd-regex application user guide guyk
2020-10-19 15:12       ` Ori Kam
2020-11-15 14:07     ` [dpdk-dev] [PATCH v3 0/2] Add example l3fwd-regex Thomas Monjalon
2023-06-29 17:11       ` Stephen Hemminger

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200908123144.26444-3-guyk@marvell.com \
    --to=guyk@marvell.com \
    --cc=dev@dpdk.org \
    --cc=dovrat@marvell.com \
    --cc=jerinj@marvell.com \
    --cc=john.mcnamara@intel.com \
    --cc=marko.kovacevic@intel.com \
    --cc=orika@mellanox.com \
    --cc=smadarf@marvell.com \
    --cc=thomas@monjalon.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).