From patchwork Fri Sep 17 16:41:36 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kevin Laatz X-Patchwork-Id: 99246 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 1948AA0C43; Fri, 17 Sep 2021 18:42:26 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id D7E0B4113D; Fri, 17 Sep 2021 18:42:05 +0200 (CEST) Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) by mails.dpdk.org (Postfix) with ESMTP id F0258410FE for ; Fri, 17 Sep 2021 18:42:03 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10110"; a="283840581" X-IronPort-AV: E=Sophos;i="5.85,301,1624345200"; d="scan'208";a="283840581" Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 17 Sep 2021 09:42:02 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.85,301,1624345200"; d="scan'208";a="546488192" Received: from silpixa00401122.ir.intel.com ([10.55.128.10]) by FMSMGA003.fm.intel.com with ESMTP; 17 Sep 2021 09:41:56 -0700 From: Kevin Laatz To: dev@dpdk.org Cc: bruce.richardson@intel.com, fengchengwen@huawei.com, conor.walsh@intel.com, Kevin Laatz Date: Fri, 17 Sep 2021 16:41:36 +0000 Message-Id: <20210917164136.3499904-7-kevin.laatz@intel.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20210917164136.3499904-1-kevin.laatz@intel.com> References: <20210910172737.2561156-1-kevin.laatz@intel.com> <20210917164136.3499904-1-kevin.laatz@intel.com> MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH v2 6/6] examples/ioat: rename application to dmafwd X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 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" Since the APIs have been updated from rawdev to dmadev, the application should also be renamed to match. This patch also includes the documentation updates for the renaming. Signed-off-by: Kevin Laatz Reviewed-by: Conor Walsh --- MAINTAINERS | 7 +- .../sample_app_ug/{ioat.rst => dma.rst} | 114 +++++++++--------- doc/guides/sample_app_ug/index.rst | 2 +- doc/guides/sample_app_ug/intro.rst | 4 +- examples/{ioat => dma}/Makefile | 4 +- examples/{ioat/ioatfwd.c => dma/dmafwd.c} | 0 examples/{ioat => dma}/meson.build | 2 +- examples/meson.build | 2 +- 8 files changed, 71 insertions(+), 64 deletions(-) rename doc/guides/sample_app_ug/{ioat.rst => dma.rst} (73%) rename examples/{ioat => dma}/Makefile (97%) rename examples/{ioat/ioatfwd.c => dma/dmafwd.c} (100%) rename examples/{ioat => dma}/meson.build (94%) diff --git a/MAINTAINERS b/MAINTAINERS index 70993d23e8..500fa94c58 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1326,8 +1326,6 @@ IOAT Rawdev M: Bruce Richardson F: drivers/raw/ioat/ F: doc/guides/rawdevs/ioat.rst -F: examples/ioat/ -F: doc/guides/sample_app_ug/ioat.rst NXP DPAA2 QDMA M: Nipun Gupta @@ -1698,6 +1696,11 @@ F: doc/guides/tools/proc_info.rst Other Example Applications -------------------------- +DMAdev example +M: Kevin Laatz +F: examples/dma/ +F: doc/guides/sample_app_ug/dma.rst + Ethtool example F: examples/ethtool/ F: doc/guides/sample_app_ug/ethtool.rst diff --git a/doc/guides/sample_app_ug/ioat.rst b/doc/guides/sample_app_ug/dma.rst similarity index 73% rename from doc/guides/sample_app_ug/ioat.rst rename to doc/guides/sample_app_ug/dma.rst index ee0a627b06..3246c780ac 100644 --- a/doc/guides/sample_app_ug/ioat.rst +++ b/doc/guides/sample_app_ug/dma.rst @@ -1,17 +1,17 @@ .. SPDX-License-Identifier: BSD-3-Clause - Copyright(c) 2019 Intel Corporation. + Copyright(c) 2019-2021 Intel Corporation. .. include:: -Packet copying using Intel\ |reg| QuickData Technology -====================================================== +Packet copying using DMAdev library +=================================== Overview -------- This sample is intended as a demonstration of the basic components of a DPDK -forwarding application and example of how to use IOAT driver API to make -packets copies. +forwarding application and example of how to use the DMAdev API to make a packet +copy application. Also while forwarding, the MAC addresses are affected as follows: @@ -29,7 +29,7 @@ Compiling the Application To compile the sample application see :doc:`compiling`. -The application is located in the ``ioat`` sub-directory. +The application is located in the ``dma`` sub-directory. Running the Application @@ -38,32 +38,36 @@ Running the Application In order to run the hardware copy application, the copying device needs to be bound to user-space IO driver. -Refer to the "IOAT Rawdev Driver" chapter in the "Rawdev Drivers" document -for information on using the driver. +Refer to the "DMAdev library" chapter in the "Programmers guide" for information +on using the library. The application requires a number of command line options: .. code-block:: console - .//examples/dpdk-ioat [EAL options] -- [-p MASK] [-q NQ] [-s RS] [-c ] - [--[no-]mac-updating] + .//examples/dpdk-dma [EAL options] -- [-p MASK] [-q NQ] [-s RS] [-c ] + [--[no-]mac-updating] [-f FS] [-b BS] where, * p MASK: A hexadecimal bitmask of the ports to configure (default is all) -* q NQ: Number of Rx queues used per port equivalent to CBDMA channels +* q NQ: Number of Rx queues used per port equivalent to DMA channels per port (default is 1) * c CT: Performed packet copy type: software (sw) or hardware using DMA (hw) (default is hw) -* s RS: Size of IOAT rawdev ring for hardware copy mode or rte_ring for +* s RS: Size of dmadev descriptor ring for hardware copy mode or rte_ring for software copy mode (default is 2048) * --[no-]mac-updating: Whether MAC address of packets should be changed or not (default is mac-updating) +* f FS: set the max frame size + +* b BS: set the DMA batch size + The application can be launched in various configurations depending on provided parameters. The app can use up to 2 lcores: one of them receives incoming traffic and makes a copy of each packet. The second lcore then @@ -81,7 +85,7 @@ updating issue the command: .. code-block:: console - $ .//examples/dpdk-ioat -l 0-2 -n 2 -- -p 0x1 --mac-updating -c sw + $ .//examples/dpdk-dma -l 0-2 -n 2 -- -p 0x1 --mac-updating -c sw To run the application in a Linux environment with 2 lcores (the main lcore, plus one forwarding core), 2 ports (ports 0 and 1), hardware copying and no MAC @@ -89,7 +93,7 @@ updating issue the command: .. code-block:: console - $ .//examples/dpdk-ioat -l 0-1 -n 1 -- -p 0x3 --no-mac-updating -c hw + $ .//examples/dpdk-dma -l 0-1 -n 1 -- -p 0x3 --no-mac-updating -c hw Refer to the *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options. @@ -114,7 +118,7 @@ The first task is to initialize the Environment Abstraction Layer (EAL). The ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()`` function. The value returned is the number of parsed arguments: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Init EAL. 8< :end-before: >8 End of init EAL. @@ -124,7 +128,7 @@ function. The value returned is the number of parsed arguments: The ``main()`` also allocates a mempool to hold the mbufs (Message Buffers) used by the application: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Allocates mempool to hold the mbufs. 8< :end-before: >8 End of allocates mempool to hold the mbufs. @@ -135,7 +139,7 @@ detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*. The ``main()`` function also initializes the ports: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Initialize each port. 8< :end-before: >8 End of initializing each port. @@ -145,9 +149,9 @@ Each port is configured using ``port_init()`` function. The Ethernet ports are configured with local settings using the ``rte_eth_dev_configure()`` function and the ``port_conf`` struct. The RSS is enabled so that multiple Rx queues could be used for packet receiving and copying by -multiple CBDMA channels per port: +multiple DMA channels per port: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Configuring port to use RSS for multiple RX queues. 8< :end-before: >8 End of configuring port to use RSS for multiple RX queues. @@ -159,7 +163,7 @@ and ``rte_eth_tx_queue_setup()`` functions. The Ethernet port is then started: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Start device. 8< :end-before: >8 End of starting device. @@ -168,7 +172,7 @@ The Ethernet port is then started: Finally the Rx port is set in promiscuous mode: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: RX port is set in promiscuous mode. 8< :end-before: >8 End of RX port is set in promiscuous mode. @@ -177,7 +181,7 @@ Finally the Rx port is set in promiscuous mode: After that each port application assigns resources needed. -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Assigning each port resources. 8< :end-before: >8 End of assigning each port resources. @@ -188,30 +192,30 @@ special structures are assigned to each port. If software copy was chosen, application have to assign ring structures for packet exchanging between lcores assigned to ports. -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Assign ring structures for packet exchanging. 8< :end-before: >8 End of assigning ring structures for packet exchanging. :dedent: 0 -When using hardware copy each Rx queue of the port is assigned an -IOAT device (``assign_rawdevs()``) using IOAT Rawdev Driver API -functions: +When using hardware copy each Rx queue of the port is assigned a DMA device +(``assign_dmadevs()``) using DMAdev library API functions: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c - :start-after: Using IOAT rawdev API functions. 8< - :end-before: >8 End of using IOAT rawdev API functions. + :start-after: Using dmadev API functions. 8< + :end-before: >8 End of using dmadev API functions. :dedent: 0 -The initialization of hardware device is done by ``rte_rawdev_configure()`` -function using ``rte_rawdev_info`` struct. After configuration the device is -started using ``rte_rawdev_start()`` function. Each of the above operations -is done in ``configure_rawdev_queue()``. +The initialization of hardware device is done by ``rte_dmadev_configure()`` and +``rte_dmadev_vchan_setup()`` functions using the ``rte_dmadev_conf`` and +``rte_dmadev_vchan_conf`` structs. After configuration the device is started +using ``rte_dmadev_start()`` function. Each of the above operations is done in +``configure_dmadev_queue()``. -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Configuration of device. 8< :end-before: >8 End of configuration of device. @@ -233,7 +237,7 @@ The Lcores Launching Functions As described above, ``main()`` function invokes ``start_forwarding_cores()`` function in order to start processing for each lcore: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Start processing for each lcore. 8< :end-before: >8 End of starting to processfor each lcore. @@ -244,7 +248,7 @@ using ``rte_eal_remote_launch()``. The configured ports, their number and number of assigned lcores are stored in user-defined ``rxtx_transmission_config`` struct: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Configuring ports and number of assigned lcores in struct. 8< :end-before: >8 End of configuration of ports and number of assigned lcores. @@ -256,24 +260,24 @@ corresponding to ports and lcores configuration provided by the user. The Lcores Processing Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For receiving packets on each port, the ``ioat_rx_port()`` function is used. +For receiving packets on each port, the ``dma_rx_port()`` function is used. The function receives packets on each configured Rx queue. Depending on the -mode the user chose, it will enqueue packets to IOAT rawdev channels and +mode the user chose, it will enqueue packets to DMA channels and then invoke copy process (hardware copy), or perform software copy of each packet using ``pktmbuf_sw_copy()`` function and enqueue them to an rte_ring: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c - :start-after: Receive packets on one port and enqueue to IOAT rawdev or rte_ring. 8< - :end-before: >8 End of receive packets on one port and enqueue to IOAT rawdev or rte_ring. + :start-after: Receive packets on one port and enqueue to dmadev or rte_ring. 8< + :end-before: >8 End of receive packets on one port and enqueue to dmadev or rte_ring. :dedent: 0 The packets are received in burst mode using ``rte_eth_rx_burst()`` function. When using hardware copy mode the packets are enqueued in -copying device's buffer using ``ioat_enqueue_packets()`` which calls -``rte_ioat_enqueue_copy()``. When all received packets are in the -buffer the copy operations are started by calling ``rte_ioat_perform_ops()``. -Function ``rte_ioat_enqueue_copy()`` operates on physical address of +copying device's buffer using ``dma_enqueue_packets()`` which calls +``rte_dmadev_copy()``. When all received packets are in the +buffer the copy operations are started by calling ``rte_dmadev_submit()``. +Function ``rte_dmadev_copy()`` operates on physical address of the packet. Structure ``rte_mbuf`` contains only physical address to start of the data buffer (``buf_iova``). Thus the address is adjusted by ``addr_offset`` value in order to get the address of ``rearm_data`` @@ -282,25 +286,25 @@ be copied in a single operation. This method can be used because the mbufs are direct mbufs allocated by the apps. If another app uses external buffers, or indirect mbufs, then multiple copy operations must be used. -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c - :start-after: Receive packets on one port and enqueue to IOAT rawdev or rte_ring. 8< - :end-before: >8 End of receive packets on one port and enqueue to IOAT rawdev or rte_ring. + :start-after: Receive packets on one port and enqueue to dmadev or rte_ring. 8< + :end-before: >8 End of receive packets on one port and enqueue to dmadev or rte_ring. :dedent: 0 -All completed copies are processed by ``ioat_tx_port()`` function. When using -hardware copy mode the function invokes ``rte_ioat_completed_ops()`` -on each assigned IOAT channel to gather copied packets. If software copy +All completed copies are processed by ``dma_tx_port()`` function. When using +hardware copy mode the function invokes ``rte_dma_completed()`` +on each assigned DMA channel to gather copied packets. If software copy mode is used the function dequeues copied packets from the rte_ring. Then each packet MAC address is changed if it was enabled. After that copies are sent in burst mode using `` rte_eth_tx_burst()``. -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c - :start-after: Transmit packets from IOAT rawdev/rte_ring for one port. 8< - :end-before: >8 End of transmitting packets from IOAT. + :start-after: Transmit packets from dmadev/rte_ring for one port. 8< + :end-before: >8 End of transmitting packets from dmadev. :dedent: 0 The Packet Copying Functions @@ -312,7 +316,7 @@ metadata from source packet to new mbuf, and then copying a data chunk of source packet. Both memory copies are done using ``rte_memcpy()``: -.. literalinclude:: ../../../examples/ioat/ioatfwd.c +.. literalinclude:: ../../../examples/dma/dmafwd.c :language: c :start-after: Perform packet copy there is a user-defined function. 8< :end-before: >8 End of perform packet copy there is a user-defined function. diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst index e8db83d3a7..8835dd03ac 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -22,7 +22,7 @@ Sample Applications User Guides ip_reassembly kernel_nic_interface keep_alive - ioat + dma l2_forward_crypto l2_forward_job_stats l2_forward_real_virtual diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst index 8ff223b16c..e765f1fd6b 100644 --- a/doc/guides/sample_app_ug/intro.rst +++ b/doc/guides/sample_app_ug/intro.rst @@ -58,8 +58,8 @@ examples are highlighted below. forwarding Graph, or ``l3fwd_graph`` application does forwarding based on IPv4 like a simple router with DPDK Graph framework. -* :doc:`Hardware packet copying`: The Hardware packet copying, - or ``ioatfwd`` application demonstrates how to use IOAT rawdev driver for +* :doc:`Hardware packet copying`: The Hardware packet copying, + or ``dmafwd`` application demonstrates how to use DMAdev library for copying packets between two threads. * :doc:`Packet Distributor`: The Packet Distributor diff --git a/examples/ioat/Makefile b/examples/dma/Makefile similarity index 97% rename from examples/ioat/Makefile rename to examples/dma/Makefile index 178fc8778c..59af6478b7 100644 --- a/examples/ioat/Makefile +++ b/examples/dma/Makefile @@ -2,10 +2,10 @@ # Copyright(c) 2019 Intel Corporation # binary name -APP = ioatfwd +APP = dmafwd # all source are stored in SRCS-y -SRCS-y := ioatfwd.c +SRCS-y := dmafwd.c PKGCONF ?= pkg-config diff --git a/examples/ioat/ioatfwd.c b/examples/dma/dmafwd.c similarity index 100% rename from examples/ioat/ioatfwd.c rename to examples/dma/dmafwd.c diff --git a/examples/ioat/meson.build b/examples/dma/meson.build similarity index 94% rename from examples/ioat/meson.build rename to examples/dma/meson.build index c1dd7c9b29..9fdcad660e 100644 --- a/examples/ioat/meson.build +++ b/examples/dma/meson.build @@ -11,5 +11,5 @@ allow_experimental_apis = true deps += ['dmadev'] sources = files( - 'ioatfwd.c', + 'dmafwd.c', ) diff --git a/examples/meson.build b/examples/meson.build index 07e682401b..d50f09db12 100644 --- a/examples/meson.build +++ b/examples/meson.build @@ -12,13 +12,13 @@ all_examples = [ 'bond', 'cmdline', 'distributor', + 'dma', 'ethtool', 'eventdev_pipeline', 'fips_validation', 'flow_classify', 'flow_filtering', 'helloworld', - 'ioat', 'ip_fragmentation', 'ip_pipeline', 'ip_reassembly',