doc: add tested Intel platforms with Intel NICs
[dpdk.git] / doc / guides / tools / flow-perf.rst
1 .. SPDX-License-Identifier: BSD-3-Clause
2    Copyright 2020 Mellanox Technologies, Ltd
3
4 Flow Performance Tool
5 =====================
6
7 Application for rte_flow performance testing.
8 The application provides the ability to test insertion rate of specific
9 rte_flow rule, by stressing it to the NIC, and calculates the insertion
10 and deletion rates.
11
12 The application allows to configure which rule to apply through several
13 options of the command line.
14
15 After that the application will start producing rules with same pattern
16 but increasing the outer IP source address by 1 each time, thus it will
17 give different flow each time, and all other items will have open masks.
18
19 To assess the rule insertion rate, the flow performance tool breaks
20 down the entire number of flow rule operations into windows of fixed size
21 (defaults to 100000 flow rule operations per window, but can be configured).
22 Then, the flow performance tool measures the total time per window and
23 computes an average time across all windows.
24
25 The application also provides the ability to measure rte flow deletion rate,
26 in addition to memory consumption before and after the flow rules' creation.
27
28 The app supports single and multiple core performance measurements, and
29 support multiple cores insertion/deletion as well.
30
31
32 Compiling the Application
33 -------------------------
34
35 The ``test-flow-perf`` application is compiled as part of the main compilation
36 of the DPDK libraries and tools.
37
38 Refer to the DPDK Getting Started Guides for details.
39
40
41 Running the Application
42 -----------------------
43
44 EAL Command-line Options
45 ~~~~~~~~~~~~~~~~~~~~~~~~
46
47 Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>`
48 or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for
49 a list of available EAL command-line options.
50
51
52 Flow Performance Options
53 ~~~~~~~~~~~~~~~~~~~~~~~~
54
55 The following are the command-line options for the flow performance application.
56 They must be separated from the EAL options, shown in the previous section,
57 with a ``--`` separator:
58
59 .. code-block:: console
60
61         sudo ./dpdk-test-flow_perf -n 4 -a 08:00.0 -- --ingress --ether --ipv4 --queue --rules-count=1000000
62
63 The command line options are:
64
65 *       ``--help``
66         Display a help message and quit.
67
68 *       ``--rules-count=N``
69         Set the total number of flow rules to insert,
70         where 1 <= N <= "number of flow rules".
71         The default value is 4,000,000.
72
73 *       ``--rules-batch=N``
74         Set the number of flow rules to insert per iteration window,
75         where 1 <= N <= "number of flow rules per iteration window".
76         The default value is 100,000 flow rules per iteration window.
77         For a total of --rules-count=1000000 flow rules to be inserted
78         and an iteration window size of --rules-batch=100000 flow rules,
79         the application will measure the insertion rate 10 times
80         (i.e., once every 100000 flow rules) and then report an average
81         insertion rate across the 10 measurements.
82
83 *       ``--dump-iterations``
84         Print rates for each iteration window.
85         Default iteration window equals to the rules-batch size (i.e., 100,000).
86
87 *       ``--deletion-rate``
88         Enable deletion rate calculations.
89
90 *       ``--dump-socket-mem``
91         Dump the memory stats for each socket before the insertion and after.
92
93 *       ``--enable-fwd``
94         Enable packets forwarding after insertion/deletion operations.
95
96 *       ``--portmask=N``
97         hexadecimal bitmask of ports to be used.
98
99 *       ``--cores=N``
100         Set the number of needed cores to insert/delete rte_flow rules.
101         Default cores count is 1.
102
103 *       ``--random-priority=N,S``
104         Create flows with the priority attribute set randomly between 0 to N - 1
105         and use S as seed for the pseudo-random number generator.
106
107 *       ``--meter-profile-alg``
108         Set the traffic metering algorithm.
109         Example: meter-profile-alg=srtcmp, default algorithm is srtcm_rfc2697
110
111 *       ``--unique-data``
112         Flag to set using unique data for all actions that support data,
113         Such as header modify and encap actions. Default is using fixed
114         data for any action that support data for all flows.
115
116 *       ``--rxq=N``
117         Set the count of receive queues, default is 1.
118
119 *       ``--txq=N``
120         Set the count of send queues, default is 1.
121
122 *       ``--rxd=N``
123         Set the count of rxd, default is 256.
124
125 *       ``--txd=N``
126         Set the count of txd, default is 256.
127
128 *       ``--mbuf-size=N``
129         Set the size of mbuf, default size is 2048.
130
131 *       ``--mbuf-cache-size=N``
132         Set the size of mbuf cache, default size is 512.
133
134 *       ``--total-mbuf-count=N``
135         Set the count of total mbuf number, default count is 32000.
136
137 *       ``--meter-profile=N1,N2,N3``
138         Set the CIR, CBS and EBS parameters, default values are 1250000, 156250 and 0.
139
140 *       ``--packet-mode``
141         Enable packet mode for meter profile.
142
143 Attributes:
144
145 *       ``--ingress``
146         Set Ingress attribute to all flows attributes.
147
148 *       ``--egress``
149         Set Egress attribute to all flows attributes.
150
151 *       ``--transfer``
152         Set Transfer attribute to all flows attributes.
153
154 *       ``--group=N``
155         Set group for all flows, where N >= 0.
156         Default group is 0.
157
158 Items:
159
160 *       ``--ether``
161         Add Ether item to all flows items, This item have open mask.
162
163 *       ``--vlan``
164         Add VLAN item to all flows items,
165         This item have VLAN value defined in user_parameters.h
166         under ``VNI_VALUE`` with full mask, default value = 1.
167         Other fields are open mask.
168
169 *       ``--ipv4``
170         Add IPv4 item to all flows items,
171         This item have incremental source IP, with full mask.
172         Other fields are open mask.
173
174 *       ``--ipv6``
175         Add IPv6 item to all flows item,
176         This item have incremental source IP, with full mask.
177         Other fields are open mask.
178
179 *       ``--tcp``
180         Add TCP item to all flows items, This item have open mask.
181
182 *       ``--udp``
183         Add UDP item to all flows items, This item have open mask.
184
185 *       ``--vxlan``
186         Add VXLAN item to all flows items,
187         This item have VNI value defined in user_parameters.h
188         under ``VNI_VALUE`` with full mask, default value = 1.
189         Other fields are open mask.
190
191 *       ``--vxlan-gpe``
192         Add VXLAN-GPE item to all flows items,
193         This item have VNI value defined in user_parameters.h
194         under ``VNI_VALUE`` with full mask, default value = 1.
195         Other fields are open mask.
196
197 *       ``--gre``
198         Add GRE item to all flows items,
199         This item have protocol value defined in user_parameters.h
200         under ``GRE_PROTO`` with full mask, default protocol = 0x6558 "Ether"
201         Other fields are open mask.
202
203 *       ``--geneve``
204         Add GENEVE item to all flows items,
205         This item have VNI value defined in user_parameters.h
206         under ``VNI_VALUE`` with full mask, default value = 1.
207         Other fields are open mask.
208
209 *       ``--gtp``
210         Add GTP item to all flows items,
211         This item have TEID value defined in user_parameters.h
212         under ``TEID_VALUE`` with full mask, default value = 1.
213         Other fields are open mask.
214
215 *       ``--meta``
216         Add Meta item to all flows items,
217         This item have data value defined in user_parameters.h
218         under ``META_DATA`` with full mask, default value = 1.
219         Other fields are open mask.
220
221 *       ``--tag``
222         Add Tag item to all flows items,
223         This item have data value defined in user_parameters.h
224         under ``META_DATA`` with full mask, default value = 1.
225
226         Also it have tag value defined in user_parameters.h
227         under ``TAG_INDEX`` with full mask, default value = 0.
228         Other fields are open mask.
229
230 *       ``--icmpv4``
231         Add icmpv4 item to all flows items, This item have open mask.
232
233 *       ``--icmpv6``
234         Add icmpv6 item to all flows items, This item have open mask.
235
236
237 Actions:
238
239 *       ``--port-id``
240         Add port redirection action to all flows actions.
241         Port redirection destination is defined in user_parameters.h
242         under PORT_ID_DST, default value = 1.
243
244        It can also has optional parameter like --port-id=N[,M] to
245        specify the destination port, the number of values should be
246        the same with number of set bits in portmask.
247
248 *       ``--rss``
249         Add RSS action to all flows actions,
250         The queues in RSS action will be all queues configured
251         in the app.
252
253 *       ``--queue``
254         Add queue action to all flows items,
255         The queue will change in round robin state for each flow.
256
257         For example:
258                 The app running with 4 RX queues
259                 Flow #0: queue index 0
260                 Flow #1: queue index 1
261                 Flow #2: queue index 2
262                 Flow #3: queue index 3
263                 Flow #4: queue index 0
264                 ...
265
266 *       ``--jump``
267         Add jump action to all flows actions.
268         Jump action destination is defined in user_parameters.h
269         under ``JUMP_ACTION_TABLE``, default value = 2.
270
271 *       ``--mark``
272         Add mark action to all flows actions.
273         Mark action id is defined in user_parameters.h
274         under ``MARK_ID``, default value = 1.
275
276 *       ``--count``
277         Add count action to all flows actions.
278
279 *       ``--set-meta``
280         Add set-meta action to all flows actions.
281         Meta data is defined in user_parameters.h under ``META_DATA``
282         with full mask, default value = 1.
283
284 *       ``--set-tag``
285         Add set-tag action to all flows actions.
286         Meta data is defined in user_parameters.h under ``META_DATA``
287         with full mask, default value = 1.
288
289         Tag index is defined in user_parameters.h under ``TAG_INDEX``
290         with full mask, default value = 0.
291
292 *       ``--drop``
293         Add drop action to all flows actions.
294
295 *       ``--hairpin-queue=N``
296         Add hairpin queue action to all flows actions.
297         The queue will change in round robin state for each flow.
298
299         For example:
300                 The app running with 4 RX hairpin queues and 4 normal RX queues
301                 Flow #0: queue index 4
302                 Flow #1: queue index 5
303                 Flow #2: queue index 6
304                 Flow #3: queue index 7
305                 Flow #4: queue index 4
306                 ...
307
308 *       ``--hairpin-rss=N``
309         Add hairpin RSS action to all flows actions.
310         The queues in RSS action will be all hairpin queues configured
311         in the app.
312
313 *       ``--set-src-mac``
314         Add set source mac action to all flows actions.
315         The mac to be set is random each flow.
316
317 *       ``--set-dst-mac``
318         Add set destination mac action to all flows actions.
319         The mac to be set is random each flow.
320
321 *       ``-set-src-ipv4``
322         Add set source ipv4 action to all flows actions.
323         The ipv4 header to be set is random each flow.
324
325 *       ``--set-dst-ipv4``
326         Add set destination ipv4 action to all flows actions.
327         The ipv4 header to be set is random each flow.
328
329 *       ``--set-src-ipv6``
330         Add set source ipv6 action to all flows actions.
331         The ipv6 header to be set is random each flow.
332
333 *       ``--set-dst-ipv6``
334         Add set destination ipv6 action to all flows actions.
335         The ipv6 header to be set is random each flow.
336
337 *       ``--set-src-tp``
338         Add set source tp action to all flows actions.
339         The tp sport header to be set is random each flow.
340
341 *       ``--set-dst-tp``
342         Add set destination tp action to all flows actions.
343         The tp dport header to be set is random each flow.
344
345 *       ``--inc-tcp-ack``
346         Add increment TCP acknowledgment by one to all flows actions.
347
348 *       ``--dec-tcp-ack``
349         Add decrement TCP acknowledgment by one to all flows actions.
350
351 *       ``--inc-tcp-seq``
352         Add increment TCP sequence by one to all flows actions.
353
354 *       ``--dec-tcp-seq``
355         Add decrement TCP sequence by one to all flows actions.
356
357 *       ``--set-ttl``
358         Add set IP ttl action to all flows actions.
359         The ttl value to be set is random each flow.
360
361 *       ``--dec-ttl``
362         Add decrement IP ttl by one to all flows actions.
363
364 *       ``--set-ipv4-dscp``
365         Add set IPv4 dscp action to all flows actions.
366         The dscp value to be is random each flow.
367
368 *       ``--set-ipv6-dscp``
369         Add set IPv6 dscp action to all flows actions.
370         The dscp value to be is random each flow.
371
372 *       ``--flag``
373         Add flag action to all flows actions.
374
375 *       ``--raw-encap=<DATA>``
376         Add raw encap action to all flows actions.
377         Data is the data needed to be encaped, with fixed values.
378         Example: raw-encap=ether,ipv4,udp,vxlan
379
380 *       ``--raw-decap=<DATA>``
381         Add raw decap action to all flows actions.
382         Data is the data needed to be decaped, with fixed values.
383         Example: raw-decap=ether,ipv4,gre
384
385 *       ``--vxlan-encap``
386         Add vxlan encap action to all flows actions.
387         Data to encap is fixed with pattern: ether,ipv4,udp,vxlan,
388         all encapped items have fixed values.
389
390 *       ``--vxlan-decap``
391         Add vxlan decap action to all flows actions.
392
393 *       ``--policy-mtr=<str>``
394         Add policy-mtr to create meter with policy and specify policy actions.
395         Example: policy-mtr=rss,mark::drop
396
397 *       ``--meter``
398         Add meter action to all flows actions.
399         Currently, 1 meter profile -> N meter rules -> N rte flows.