From: Guy Kaneti <g...@marvell.com>
Adding the user guide for l3fwd regex application.
Signed-off-by: Guy Kaneti <g...@marvell.com>
---
MAINTAINERS | 1 +
doc/guides/rel_notes/release_20_11.rst | 5 +
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 ++++++++++++++++++
5 files changed, 246 insertions(+)
create mode 100644 doc/guides/sample_app_ug/l3_forward_regex.rst
diff --git a/MAINTAINERS b/MAINTAINERS
index 9880efa3a..3dcf9aa62 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -433,6 +433,7 @@ F: doc/guides/prog_guide/regexdev.rst
F: doc/guides/regexdevs/features/default.ini
M: Guy Kaneti <g...@marvell.com>
F: examples/l3fwd-regex/
+F: doc/guides/sample_app_ug/l3_forward_regex.rst
Eventdev API
M: Jerin Jacob <jer...@marvell.com>
diff --git a/doc/guides/rel_notes/release_20_11.rst
b/doc/guides/rel_notes/release_20_11.rst
index 48717ee53..857645e88 100644
--- a/doc/guides/rel_notes/release_20_11.rst
+++ b/doc/guides/rel_notes/release_20_11.rst
@@ -285,6 +285,11 @@ New Features
* Added scatter gather support.
* Added NIST GCMVS complaint GMAC test method support.
+* **Added new l3fwd-regex sample application.**
+
+ Added an example application ``l3fwd-regex``. This demonstrates the usage of
+ packet processing using DPDK Regex libraries.
+
Removed Items
-------------
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..4e4265362
--- /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-regex [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 initialized.
+
+.. 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
