9785e8431ed616fb0478a4adf1bf7142a70574d8
[dpdk.git] / doc / guides / tools / testeventdev.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2017 Cavium, Inc
3
4 dpdk-test-eventdev Application
5 ==============================
6
7 The ``dpdk-test-eventdev`` tool is a Data Plane Development Kit (DPDK)
8 application that allows exercising various eventdev use cases.
9 This application has a generic framework to add new eventdev based test cases to
10 verify functionality and measure the performance parameters of DPDK eventdev
11 devices.
12
13 Compiling the Application
14 -------------------------
15
16 **Build the application**
17
18 Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the
19 ``dpdk-test-eventdev`` application.
20
21 Initially, the user must select a DPDK target to choose the correct target type
22 and compiler options to use when building the libraries.
23 The user must have all libraries, modules, updates and compilers installed
24 in the system prior to this,
25 as described in the earlier chapters in this Getting Started Guide.
26
27 Running the Application
28 -----------------------
29
30 The application has a number of command line options:
31
32 .. code-block:: console
33
34    dpdk-test-eventdev [EAL Options] -- [application options]
35
36 EAL Options
37 ~~~~~~~~~~~
38
39 The following are the EAL command-line options that can be used in conjunction
40 with the ``dpdk-test-eventdev`` application.
41 See the DPDK Getting Started Guides for more information on these options.
42
43 *   ``-c <COREMASK>`` or ``-l <CORELIST>``
44
45         Set the hexadecimal bitmask of the cores to run on. The corelist is a
46         list of cores to use.
47
48 *   ``--vdev <driver><id>``
49
50         Add a virtual eventdev device.
51
52 Application Options
53 ~~~~~~~~~~~~~~~~~~~
54
55 The following are the application command-line options:
56
57 * ``--verbose``
58
59         Set verbose level. Default is 1. Value > 1 displays more details.
60
61 * ``--dev <n>``
62
63         Set the device id of the event device.
64
65 * ``--test <name>``
66
67         Set test name, where ``name`` is one of the following::
68
69          order_queue
70          order_atq
71          perf_queue
72          perf_atq
73
74 * ``--socket_id <n>``
75
76         Set the socket id of the application resources.
77
78 * ``--pool-sz <n>``
79
80         Set the number of mbufs to be allocated from the mempool.
81
82 * ``--plcores <CORELIST>``
83
84         Set the list of cores to be used as producers.
85
86 * ``--wlcores <CORELIST>``
87
88         Set the list of cores to be used as workers.
89
90 * ``--stlist <type_list>``
91
92         Set the scheduled type of each stage where ``type_list`` size
93         determines the number of stages used in the test application.
94         Each type_list member can be one of the following::
95
96             P or p : Parallel schedule type
97             O or o : Ordered schedule type
98             A or a : Atomic schedule type
99
100         Application expects the ``type_list`` in comma separated form (i.e. ``--stlist o,a,a,a``)
101
102 * ``--nb_flows <n>``
103
104         Set the number of flows to produce.
105
106 * ``--nb_pkts <n>``
107
108         Set the number of packets to produce. 0 implies no limit.
109
110 * ``--worker_deq_depth <n>``
111
112         Set the dequeue depth of the worker.
113
114 * ``--fwd_latency``
115
116         Perform forward latency measurement.
117
118 * ``--queue_priority``
119
120         Enable queue priority.
121
122 * ``--prod_type_ethdev``
123
124         Use ethernet device as producer.
125
126 Eventdev Tests
127 --------------
128
129 ORDER_QUEUE Test
130 ~~~~~~~~~~~~~~~~
131
132 This is a functional test case that aims at testing the following:
133
134 #. Verify the ingress order maintenance.
135 #. Verify the exclusive(atomic) access to given atomic flow per eventdev port.
136
137 .. _table_eventdev_order_queue_test:
138
139 .. table:: Order queue test eventdev configuration.
140
141    +---+--------------+----------------+------------------------+
142    | # | Items        | Value          | Comments               |
143    |   |              |                |                        |
144    +===+==============+================+========================+
145    | 1 | nb_queues    | 2              | q0(ordered), q1(atomic)|
146    |   |              |                |                        |
147    +---+--------------+----------------+------------------------+
148    | 2 | nb_producers | 1              |                        |
149    |   |              |                |                        |
150    +---+--------------+----------------+------------------------+
151    | 3 | nb_workers   | >= 1           |                        |
152    |   |              |                |                        |
153    +---+--------------+----------------+------------------------+
154    | 4 | nb_ports     | nb_workers +   | Workers use port 0 to  |
155    |   |              | 1              | port n-1. Producer uses|
156    |   |              |                | port n                 |
157    +---+--------------+----------------+------------------------+
158
159 .. _figure_eventdev_order_queue_test:
160
161 .. figure:: img/eventdev_order_queue_test.*
162
163    order queue test operation.
164
165 The order queue test configures the eventdev with two queues and an event
166 producer to inject the events to q0(ordered) queue. Both q0(ordered) and
167 q1(atomic) are linked to all the workers.
168
169 The event producer maintains a sequence number per flow and injects the events
170 to the ordered queue. The worker receives the events from ordered queue and
171 forwards to atomic queue. Since the events from an ordered queue can be
172 processed in parallel on the different workers, the ingress order of events
173 might have changed on the downstream atomic queue enqueue. On enqueue to the
174 atomic queue, the eventdev PMD driver reorders the event to the original
175 ingress order(i.e producer ingress order).
176
177 When the event is dequeued from the atomic queue by the worker, this test
178 verifies the expected sequence number of associated event per flow by comparing
179 the free running expected sequence number per flow.
180
181 Application options
182 ^^^^^^^^^^^^^^^^^^^
183
184 Supported application command line options are following::
185
186    --verbose
187    --dev
188    --test
189    --socket_id
190    --pool_sz
191    --plcores
192    --wlcores
193    --nb_flows
194    --nb_pkts
195    --worker_deq_depth
196
197 Example
198 ^^^^^^^
199
200 Example command to run order queue test:
201
202 .. code-block:: console
203
204    sudo build/app/dpdk-test-eventdev --vdev=event_sw0 -- \
205                 --test=order_queue --plcores 1 --wlcores 2,3
206
207
208 ORDER_ATQ Test
209 ~~~~~~~~~~~~~~
210
211 This test verifies the same aspects of ``order_queue`` test, the difference is
212 the number of queues used, this test operates on a single ``all types queue(atq)``
213 instead of two different queues for ordered and atomic.
214
215 .. _table_eventdev_order_atq_test:
216
217 .. table:: Order all types queue test eventdev configuration.
218
219    +---+--------------+----------------+------------------------+
220    | # | Items        | Value          | Comments               |
221    |   |              |                |                        |
222    +===+==============+================+========================+
223    | 1 | nb_queues    | 1              | q0(all types queue)    |
224    |   |              |                |                        |
225    +---+--------------+----------------+------------------------+
226    | 2 | nb_producers | 1              |                        |
227    |   |              |                |                        |
228    +---+--------------+----------------+------------------------+
229    | 3 | nb_workers   | >= 1           |                        |
230    |   |              |                |                        |
231    +---+--------------+----------------+------------------------+
232    | 4 | nb_ports     | nb_workers +   | Workers use port 0 to  |
233    |   |              | 1              | port n-1.Producer uses |
234    |   |              |                | port n.                |
235    +---+--------------+----------------+------------------------+
236
237 .. _figure_eventdev_order_atq_test:
238
239 .. figure:: img/eventdev_order_atq_test.*
240
241    order all types queue test operation.
242
243 Application options
244 ^^^^^^^^^^^^^^^^^^^
245
246 Supported application command line options are following::
247
248    --verbose
249    --dev
250    --test
251    --socket_id
252    --pool_sz
253    --plcores
254    --wlcores
255    --nb_flows
256    --nb_pkts
257    --worker_deq_depth
258
259 Example
260 ^^^^^^^
261
262 Example command to run order ``all types queue`` test:
263
264 .. code-block:: console
265
266    sudo build/app/dpdk-test-eventdev --vdev=event_octeontx -- \
267                         --test=order_atq --plcores 1 --wlcores 2,3
268
269
270 PERF_QUEUE Test
271 ~~~~~~~~~~~~~~~
272
273 This is a performance test case that aims at testing the following:
274
275 #. Measure the number of events can be processed in a second.
276 #. Measure the latency to forward an event.
277
278 .. _table_eventdev_perf_queue_test:
279
280 .. table:: Perf queue test eventdev configuration.
281
282    +---+--------------+----------------+-----------------------------------------+
283    | # | Items        | Value          | Comments                                |
284    |   |              |                |                                         |
285    +===+==============+================+=========================================+
286    | 1 | nb_queues    | nb_producers * | Queues will be configured based on the  |
287    |   |              | nb_stages      | user requested sched type list(--stlist)|
288    +---+--------------+----------------+-----------------------------------------+
289    | 2 | nb_producers | >= 1           | Selected through --plcores command line |
290    |   |              |                | argument.                               |
291    +---+--------------+----------------+-----------------------------------------+
292    | 3 | nb_workers   | >= 1           | Selected through --wlcores command line |
293    |   |              |                | argument                                |
294    +---+--------------+----------------+-----------------------------------------+
295    | 4 | nb_ports     | nb_workers +   | Workers use port 0 to port n-1.         |
296    |   |              | nb_producers   | Producers use port n to port p          |
297    +---+--------------+----------------+-----------------------------------------+
298
299 .. _figure_eventdev_perf_queue_test:
300
301 .. figure:: img/eventdev_perf_queue_test.*
302
303    perf queue test operation.
304
305 The perf queue test configures the eventdev with Q queues and P ports, where
306 Q and P is a function of the number of workers, the number of producers and
307 number of stages as mentioned in :numref:`table_eventdev_perf_queue_test`.
308
309 The user can choose the number of workers, the number of producers and number of
310 stages through the ``--wlcores``, ``--plcores`` and the ``--stlist`` application
311 command line arguments respectively.
312
313 The producer(s) injects the events to eventdev based the first stage sched type
314 list requested by the user through ``--stlist`` the command line argument.
315
316 Based on the number of stages to process(selected through ``--stlist``),
317 The application forwards the event to next upstream queue and terminates when it
318 reaches the last stage in the pipeline. On event termination, application
319 increments the number events processed and print periodically in one second
320 to get the number of events processed in one second.
321
322 When ``--fwd_latency`` command line option selected, the application inserts
323 the timestamp in the event on the first stage and then on termination, it
324 updates the number of cycles to forward a packet. The application uses this
325 value to compute the average latency to a forward packet.
326
327 When ``--prod_type_ethdev`` command line option is selected, the application
328 uses the probed ethernet devices as producers by configuring them as Rx
329 adapters instead of using synthetic producers.
330
331 Application options
332 ^^^^^^^^^^^^^^^^^^^
333
334 Supported application command line options are following::
335
336         --verbose
337         --dev
338         --test
339         --socket_id
340         --pool_sz
341         --plcores
342         --wlcores
343         --stlist
344         --nb_flows
345         --nb_pkts
346         --worker_deq_depth
347         --fwd_latency
348         --queue_priority
349         --prod_type_ethdev
350
351 Example
352 ^^^^^^^
353
354 Example command to run perf queue test:
355
356 .. code-block:: console
357
358    sudo build/app/dpdk-test-eventdev -c 0xf -s 0x1 --vdev=event_sw0 -- \
359         --test=perf_queue --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0
360
361 Example command to run perf queue test with ethernet ports:
362
363 .. code-block:: console
364
365    sudo build/app/dpdk-test-eventdev --vdev=event_sw0 -- \
366         --test=perf_queue --plcores=2 --wlcore=3 --stlist=p --prod_type_ethdev
367
368 PERF_ATQ Test
369 ~~~~~~~~~~~~~~~
370
371 This is a performance test case that aims at testing the following with
372 ``all types queue`` eventdev scheme.
373
374 #. Measure the number of events can be processed in a second.
375 #. Measure the latency to forward an event.
376
377 .. _table_eventdev_perf_atq_test:
378
379 .. table:: Perf all types queue test eventdev configuration.
380
381    +---+--------------+----------------+-----------------------------------------+
382    | # | Items        | Value          | Comments                                |
383    |   |              |                |                                         |
384    +===+==============+================+=========================================+
385    | 1 | nb_queues    | nb_producers   | Queues will be configured based on the  |
386    |   |              |                | user requested sched type list(--stlist)|
387    +---+--------------+----------------+-----------------------------------------+
388    | 2 | nb_producers | >= 1           | Selected through --plcores command line |
389    |   |              |                | argument.                               |
390    +---+--------------+----------------+-----------------------------------------+
391    | 3 | nb_workers   | >= 1           | Selected through --wlcores command line |
392    |   |              |                | argument                                |
393    +---+--------------+----------------+-----------------------------------------+
394    | 4 | nb_ports     | nb_workers +   | Workers use port 0 to port n-1.         |
395    |   |              | nb_producers   | Producers use port n to port p          |
396    +---+--------------+----------------+-----------------------------------------+
397
398 .. _figure_eventdev_perf_atq_test:
399
400 .. figure:: img/eventdev_perf_atq_test.*
401
402    perf all types queue test operation.
403
404
405 The ``all types queues(atq)`` perf test configures the eventdev with Q queues
406 and P ports, where Q and P is a function of the number of workers and number of
407 producers as mentioned in :numref:`table_eventdev_perf_atq_test`.
408
409
410 The atq queue test functions as same as ``perf_queue`` test. The difference
411 is, It uses, ``all type queue scheme`` instead of separate queues for each
412 stage and thus reduces the number of queues required to realize the use case
413 and enables flow pinning as the event does not move to the next queue.
414
415
416 Application options
417 ^^^^^^^^^^^^^^^^^^^
418
419 Supported application command line options are following::
420
421         --verbose
422         --dev
423         --test
424         --socket_id
425         --pool_sz
426         --plcores
427         --wlcores
428         --stlist
429         --nb_flows
430         --nb_pkts
431         --worker_deq_depth
432         --fwd_latency
433         --prod_type_ethdev
434
435 Example
436 ^^^^^^^
437
438 Example command to run perf ``all types queue`` test:
439
440 .. code-block:: console
441
442    sudo build/app/dpdk-test-eventdev --vdev=event_octeontx -- \
443                 --test=perf_atq --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0