From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 6ADD6A04B0; Sun, 18 Oct 2020 14:05:54 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 0651BD01D; Sun, 18 Oct 2020 14:05:36 +0200 (CEST) Received: from mx0b-0016f401.pphosted.com (mx0a-0016f401.pphosted.com [67.231.148.174]) by dpdk.org (Postfix) with ESMTP id D6D99CFEB for ; Sun, 18 Oct 2020 14:05:34 +0200 (CEST) Received: from pps.filterd (m0045849.ppops.net [127.0.0.1]) by mx0a-0016f401.pphosted.com (8.16.0.42/8.16.0.42) with SMTP id 09IBuc3I023756; Sun, 18 Oct 2020 05:05:33 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=marvell.com; h=from : to : cc : subject : date : message-id : in-reply-to : references : mime-version : content-transfer-encoding : content-type; s=pfpt0220; bh=J22HwnZHwQ4OPzdtwWHxT4WAAspuP4LO2IrbovggWvU=; b=dkDgf1Fb3W3ElYKDJlMoVC12E7R3iqOWhwTez09sYBIYvyoN1novTl3ZLCMQ0zUvu5Qv Qnq6Yw7FFn5tgfZr3yJM6NYxZlNATkUJrAiG87hHTeB+4Q+INzdPx06Lj4wgrwGCTzdi 9hcw4ncD/dlbJim4x6/Gg2S848+7dQiCAUKMBhwZPyqcxDh6PTIgTeconTxHIkSlTUGQ 6opjVFT6lU56ls8P9DaJ7NMBI1m2VoLJMFEFjpBSM9H8il+ovLBjHue6lx7WbnTRHtxI GtHILKL1ZSanZnyE9tcD9Hr1onhQ6wV5Ns0c+z6aYJ7wXuP3tGjOkIXM/n4tbu8i3o1o uQ== Received: from sc-exch02.marvell.com ([199.233.58.182]) by mx0a-0016f401.pphosted.com with ESMTP id 347wyq2dfq-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT); Sun, 18 Oct 2020 05:05:33 -0700 Received: from DC5-EXCH02.marvell.com (10.69.176.39) by SC-EXCH02.marvell.com (10.93.176.82) with Microsoft SMTP Server (TLS) id 15.0.1497.2; Sun, 18 Oct 2020 05:05:31 -0700 Received: from maili.marvell.com (10.69.176.80) by DC5-EXCH02.marvell.com (10.69.176.39) with Microsoft SMTP Server id 15.0.1497.2 via Frontend Transport; Sun, 18 Oct 2020 05:05:32 -0700 Received: from vvenus124.il.marvell.com (unknown [10.5.116.64]) by maili.marvell.com (Postfix) with ESMTP id CFA983F7040; Sun, 18 Oct 2020 05:05:29 -0700 (PDT) From: To: , , , CC: , , , , Date: Sun, 18 Oct 2020 15:03:53 +0300 Message-ID: <20201018120353.11325-3-guyk@marvell.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201018120353.11325-1-guyk@marvell.com> References: <20200908123144.26444-3-guyk@marvell.com> <20201018120353.11325-1-guyk@marvell.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.235, 18.0.687 definitions=2020-10-18_02:2020-10-16, 2020-10-18 signatures=0 Subject: [dpdk-dev] [PATCH v3 2/2] doc: add l3fwd-regex application user guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" From: Guy Kaneti Adding the user guide for l3fwd regex application. Signed-off-by: Guy Kaneti --- 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 F: examples/l3fwd-regex/ +F: doc/guides/sample_app_ug/l3_forward_regex.rst Eventdev API M: Jerin Jacob 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`: 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`: 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