diff --git a/MAINTAINERS b/MAINTAINERS index be2c9b6815..0e5951f8f1 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -462,6 +462,10 @@ F: lib/dmadev/ F: drivers/dma/skeleton/ F: app/test/test_dmadev* F: doc/guides/prog_guide/dmadev.rst +M: Kevin Laatz +M: Bruce Richardson +F: examples/dma/ +F: doc/guides/sample_app_ug/dma.rst Eventdev API M: Jerin Jacob @@ -1323,8 +1327,6 @@ IOAT Rawdev - DEPRECATED M: Bruce Richardson F: drivers/raw/ioat/ F: doc/guides/rawdevs/ioat.rst -F: examples/ioat/ -F: doc/guides/sample_app_ug/ioat.rst Marvell CNXK BPHY M: Jakub Palider 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:: -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 - $ .//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 @@ -95,7 +95,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. @@ -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`: 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',