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(®ex_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
next prev 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).