1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2023 Intel Corporation. 3 4dpdk-test-dma-perf Application 5============================== 6 7The ``dpdk-test-dma-perf`` tool is a Data Plane Development Kit (DPDK) application 8that evaluates the performance of DMA (Direct Memory Access) devices accessible in DPDK environment. 9It provides a benchmark framework to assess the performance 10of CPU and DMA devices under various combinations, 11such as varying buffer lengths, scatter-gather copy, copying in remote memory etc. 12It helps in evaluating performance of DMA device as hardware acceleration vehicle 13in DPDK application. 14 15In addition, this tool supports memory-to-memory, memory-to-device and device-to-memory copy tests, 16to compare the performance of CPU and DMA capabilities under various conditions 17with the help of a pre-set configuration file. 18 19 20Configuration 21------------- 22 23Along with EAL command-line arguments, this application supports 24various parameters for the benchmarking through a configuration file. 25An example configuration file is provided below 26along with the application to demonstrate all the parameters. 27 28.. code-block:: ini 29 30 [case1] 31 type=DMA_MEM_COPY 32 mem_size=10 33 buf_size=64,8192,2,MUL 34 dma_ring_size=1024 35 kick_batch=32 36 src_numa_node=0 37 dst_numa_node=0 38 cache_flush=0 39 test_seconds=2 40 lcore_dma0=lcore=10,dev=0000:00:04.2,dir=mem2mem 41 lcore_dma0=lcore=11,dev=0000:00:04.3,dir=mem2mem 42 eal_args=--in-memory --file-prefix=test 43 44 [case2] 45 type=CPU_MEM_COPY 46 mem_size=10 47 buf_size=64,8192,2,MUL 48 src_numa_node=0 49 dst_numa_node=1 50 cache_flush=0 51 test_seconds=2 52 lcore = 3, 4 53 eal_args=--in-memory --no-pci 54 55 [case3] 56 skip=1 57 type=DMA_MEM_COPY 58 dma_src_sge=4 59 dma_dst_sge=1 60 mem_size=10 61 buf_size=64,8192,2,MUL 62 dma_ring_size=1024 63 kick_batch=32 64 src_numa_node=0 65 dst_numa_node=0 66 cache_flush=0 67 test_seconds=2 68 lcore_dma0=lcore=10,dev=0000:00:04.1,dir=mem2mem 69 lcore_dma1=lcore=11,dev=0000:00:04.2,dir=dev2mem,raddr=0x200000000,coreid=1,pfid=2,vfid=3 70 lcore_dma2=lcore=12,dev=0000:00:04.3,dir=mem2dev,raddr=0x200000000,coreid=1,pfid=2,vfid=3 71 eal_args=--in-memory --file-prefix=test 72 73The configuration file is divided into multiple sections, each section represents a test case. 74The four mandatory variables ``mem_size``, ``buf_size``, ``dma_ring_size``, and ``kick_batch`` 75can vary in each test case. 76The format for this is ``variable=first,last,increment,ADD|MUL``. 77This means that the first value of the variable is ``first``, 78the last value is ``last``, ``increment`` is the step size, 79and ``ADD|MUL`` indicates whether the change is by addition or multiplication. 80 81The variables for mem2dev and dev2mem copy are 82``dir``, ``dev``, ``lcore``, ``coreid``, ``pfid``, ``vfid``, ``raddr`` 83and can vary for each device. 84 85For scatter-gather copy test ``dma_src_sge``, ``dma_dst_sge`` must be configured. 86 87Each case can only have one variable change, 88and each change will generate a scenario, so each case can have multiple scenarios. 89 90 91Configuration Parameters 92~~~~~~~~~~~~~~~~~~~~~~~~ 93 94``skip`` 95 To skip a test-case, must be configured as ``1`` 96 97``type`` 98 The type of the test. 99 Currently supported types are ``DMA_MEM_COPY`` and ``CPU_MEM_COPY``. 100 101``dma_src_sge`` 102 Number of source segments for scatter-gather. 103 104``dma_dst_sge`` 105 Number of destination segments for scatter-gather. 106 107``mem_size`` 108 The size of the memory footprint in megabytes (MB) for source and destination. 109 110``buf_size`` 111 The memory size of a single operation in bytes (B). 112 113``dma_ring_size`` 114 The DMA ring buffer size. Must be a power of two, and between ``64`` and ``4096``. 115 116``kick_batch`` 117 The DMA operation batch size, should be greater than ``1`` normally. 118 119``src_numa_node`` 120 Controls the NUMA node where the source memory is allocated. 121 122``dst_numa_node`` 123 Controls the NUMA node where the destination memory is allocated. 124 125``cache_flush`` 126 Determines whether the cache should be flushed. 127 ``1`` indicates to flush and ``0`` to not flush. 128 129``test_seconds`` 130 Controls the test time for each scenario. 131 132``lcore_dma`` 133 Specifies the lcore/DMA mapping and per device specific config. 134 135 * ``lcore`` 136 Core number mapped to a DMA device. 137 138 * ``dir`` 139 The direction of data transfer. 140 Currently supported directions: 141 142 * ``mem2mem`` - memory to memory copy 143 144 * ``mem2dev`` - memory to device copy 145 146 * ``dev2mem`` - device to memory copy 147 148 * ``dev`` 149 DMA device bus address. 150 151 * ``raddr`` 152 Remote machine address for ``mem2dev`` and ``dev2mem`` copy. 153 154 * ``coreid`` 155 Denotes PCIe core index for ``mem2dev`` and ``dev2mem`` copy. 156 157 * ``pfid`` 158 Denotes PF-id to be used for ``mem2dev`` and ``dev2mem`` copy. 159 160 * ``vfid`` 161 Denotes VF-id of PF-id to be used for ``mem2dev`` and ``dev2mem`` copy. 162 163.. note:: 164 165 The mapping of lcore to DMA must be one-to-one and cannot be duplicated. 166 167``lcore`` 168 Specifies the lcore for CPU testing. 169 170``eal_args`` 171 Specifies the EAL arguments. 172 173 174Running the Application 175----------------------- 176 177Typical command-line invocation to execute the application: 178 179.. code-block:: console 180 181 dpdk-test-dma-perf --config ./config_dma.ini --result ./res_dma.csv 182 183Where ``config_dma.ini`` is the configuration file, 184and ``res_dma.csv`` will be the generated result file. 185 186If no result file is specified, the test results are found in a file 187with the same name as the configuration file with the addition of ``_result.csv`` at the end. 188 189 190Limitations 191----------- 192 193Additional enhancements are possible in the future. 194