[dpdk-dev] [PATCH v4 8/8] examples/ioat: rename application to dmafwd

[Kevin Laatz <kevin.laatz@intel.com>]

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 <kevin.laatz@intel.com>
Reviewed-by: Conor Walsh <conor.walsh@intel.com>
---
 .../sample_app_ug/{ioat.rst => dma.rst}       | 102 +++++++++---------
 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 +-
 7 files changed, 58 insertions(+), 58 deletions(-)
 rename doc/guides/sample_app_ug/{ioat.rst => dma.rst} (75%)
 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/doc/guides/sample_app_ug/ioat.rst b/doc/guides/sample_app_ug/dma.rst
similarity index 75%
rename from doc/guides/sample_app_ug/ioat.rst
rename to doc/guides/sample_app_ug/dma.rst
index 1edad3f9ac..4b8e607774 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:: <isonum.txt>
 
-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,8 +38,8 @@ 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:
 
@@ -52,13 +52,13 @@ 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
@@ -87,7 +87,7 @@ updating issue the command:
 
 .. code-block:: console
 
-    $ ./<build_dir>/examples/dpdk-ioat -l 0-2 -n 2 -- -p 0x1 --mac-updating -c sw
+    $ ./<build_dir>/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
@@ -95,7 +95,7 @@ updating issue the command:
 
 .. code-block:: console
 
-    $ ./<build_dir>/examples/dpdk-ioat -l 0-1 -n 1 -- -p 0x3 --no-mac-updating -c hw
+    $ ./<build_dir>/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.
@@ -120,7 +120,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.
@@ -130,7 +130,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.
@@ -141,7 +141,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.
@@ -151,9 +151,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.
@@ -165,7 +165,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.
@@ -174,7 +174,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.
@@ -183,7 +183,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.
@@ -192,30 +192,30 @@ After that each port application assigns resources needed.
 Ring structures are assigned for exchanging packets between lcores for both SW
 and HW copy modes.
 
-.. 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_dma_configure()`` and
+``rte_dma_vchan_setup()`` functions using the ``rte_dma_conf`` and
+``rte_dma_vchan_conf`` structs. After configuration the device is started
+using ``rte_dma_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.
@@ -237,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.
@@ -248,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.
@@ -260,32 +260,32 @@ 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_dma_copy()``. When all received packets are in the
+buffer the copy operations are started by calling ``rte_dma_submit()``.
+Function ``rte_dma_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 ``rte_pktmbuf_iova()`` API is
 used to get the address of the start of the data within the mbuf.
 
-.. 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
 
 
@@ -293,15 +293,15 @@ Once the copies have been completed (this includes gathering the completions in
 HW copy mode), the copied packets are enqueued to the ``rx_to_tx_ring``, which
 is used to pass the packets to the TX function.
 
-All completed copies are processed by ``ioat_tx_port()`` function. This function
+All completed copies are processed by ``dma_tx_port()`` function. This function
 dequeues copied packets from the ``rx_to_tx_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
@@ -311,7 +311,7 @@ In order to perform SW packet copy, there are user-defined functions to first co
 the packet metadata (``pktmbuf_metadata_copy()``) and then the packet data
 (``pktmbuf_sw_copy()``):
 
-.. 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<ioat>`: The Hardware packet copying,
-  or ``ioatfwd`` application demonstrates how to use IOAT rawdev driver for
+* :doc:`Hardware packet copying<dma>`: The Hardware packet copying,
+  or ``dmafwd`` application demonstrates how to use DMAdev library for
   copying packets between two threads.
 
 * :doc:`Packet Distributor<dist_app>`: 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',
-- 
2.30.2