xref: /dpdk/doc/guides/tools/flow-perf.rst (revision 0cd91fd3) 
1.. SPDX-License-Identifier: BSD-3-Clause
2   Copyright 2020 Mellanox Technologies, Ltd
3
4Flow Performance Tool
5=====================
6
7Application for rte_flow performance testing.
8The application provides the ability to test insertion rate of specific
9rte_flow rule, by stressing it to the NIC, and calculates the insertion
10and deletion rates.
11
12The application allows to configure which rule to apply through several
13options of the command line.
14
15After that the application will start producing rules with same pattern
16but increasing the outer IP source address by 1 each time, thus it will
17give different flow each time, and all other items will have open masks.
18
19To assess the rule insertion rate, the flow performance tool breaks
20down 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).
22Then, the flow performance tool measures the total time per window and
23computes an average time across all windows.
24
25The application also provides the ability to measure rte flow deletion rate,
26in addition to memory consumption before and after the flow rules' creation.
27
28The app supports single and multiple core performance measurements, and
29support multiple cores insertion/deletion as well.
30
31
32Compiling the Application
33-------------------------
34
35The ``test-flow-perf`` application is compiled as part of the main compilation
36of the DPDK libraries and tools.
37
38Refer to the DPDK Getting Started Guides for details.
39
40
41Running the Application
42-----------------------
43
44EAL Command-line Options
45~~~~~~~~~~~~~~~~~~~~~~~~
46
47Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>`
48or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for
49a list of available EAL command-line options.
50
51
52Flow Performance Options
53~~~~~~~~~~~~~~~~~~~~~~~~
54
55The following are the command-line options for the flow performance application.
56They must be separated from the EAL options, shown in the previous section,
57with 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
63The 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
137Attributes:
138
139*	``--ingress``
140	Set Ingress attribute to all flows attributes.
141
142*	``--egress``
143	Set Egress attribute to all flows attributes.
144
145*	``--transfer``
146	Set Transfer attribute to all flows attributes.
147
148*	``--group=N``
149	Set group for all flows, where N >= 0.
150	Default group is 0.
151
152Items:
153
154*	``--ether``
155	Add Ether item to all flows items, This item have open mask.
156
157*	``--vlan``
158	Add VLAN item to all flows items,
159	This item have VLAN value defined in user_parameters.h
160	under ``VNI_VALUE`` with full mask, default value = 1.
161	Other fields are open mask.
162
163*	``--ipv4``
164	Add IPv4 item to all flows items,
165	This item have incremental source IP, with full mask.
166	Other fields are open mask.
167
168*	``--ipv6``
169	Add IPv6 item to all flows item,
170	This item have incremental source IP, with full mask.
171	Other fields are open mask.
172
173*	``--tcp``
174	Add TCP item to all flows items, This item have open mask.
175
176*	``--udp``
177	Add UDP item to all flows items, This item have open mask.
178
179*	``--vxlan``
180	Add VXLAN item to all flows items,
181	This item have VNI value defined in user_parameters.h
182	under ``VNI_VALUE`` with full mask, default value = 1.
183	Other fields are open mask.
184
185*	``--vxlan-gpe``
186	Add VXLAN-GPE 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*	``--gre``
192	Add GRE item to all flows items,
193	This item have protocol value defined in user_parameters.h
194	under ``GRE_PROTO`` with full mask, default protocol = 0x6558 "Ether"
195	Other fields are open mask.
196
197*	``--geneve``
198	Add GENEVE item to all flows items,
199	This item have VNI value defined in user_parameters.h
200	under ``VNI_VALUE`` with full mask, default value = 1.
201	Other fields are open mask.
202
203*	``--gtp``
204	Add GTP item to all flows items,
205	This item have TEID value defined in user_parameters.h
206	under ``TEID_VALUE`` with full mask, default value = 1.
207	Other fields are open mask.
208
209*	``--meta``
210	Add Meta item to all flows items,
211	This item have data value defined in user_parameters.h
212	under ``META_DATA`` with full mask, default value = 1.
213	Other fields are open mask.
214
215*	``--tag``
216	Add Tag 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
220	Also it have tag value defined in user_parameters.h
221	under ``TAG_INDEX`` with full mask, default value = 0.
222	Other fields are open mask.
223
224*	``--icmpv4``
225	Add icmpv4 item to all flows items, This item have open mask.
226
227*	``--icmpv6``
228	Add icmpv6 item to all flows items, This item have open mask.
229
230
231Actions:
232
233*	``--port-id``
234	Add port redirection action to all flows actions.
235	Port redirection destination is defined in user_parameters.h
236	under PORT_ID_DST, default value = 1.
237
238       It can also has optional parameter like --port-id=N[,M] to
239       specify the destination port, the number of values should be
240       the same with number of set bits in portmask.
241
242*	``--rss``
243	Add RSS action to all flows actions,
244	The queues in RSS action will be all queues configured
245	in the app.
246
247*	``--queue``
248	Add queue action to all flows items,
249	The queue will change in round robin state for each flow.
250
251	For example:
252		The app running with 4 RX queues
253		Flow #0: queue index 0
254		Flow #1: queue index 1
255		Flow #2: queue index 2
256		Flow #3: queue index 3
257		Flow #4: queue index 0
258		...
259
260*	``--jump``
261	Add jump action to all flows actions.
262	Jump action destination is defined in user_parameters.h
263	under ``JUMP_ACTION_TABLE``, default value = 2.
264
265*	``--mark``
266	Add mark action to all flows actions.
267	Mark action id is defined in user_parameters.h
268	under ``MARK_ID``, default value = 1.
269
270*	``--count``
271	Add count action to all flows actions.
272
273*	``--set-meta``
274	Add set-meta action to all flows actions.
275	Meta data is defined in user_parameters.h under ``META_DATA``
276	with full mask, default value = 1.
277
278*	``--set-tag``
279	Add set-tag action to all flows actions.
280	Meta data is defined in user_parameters.h under ``META_DATA``
281	with full mask, default value = 1.
282
283	Tag index is defined in user_parameters.h under ``TAG_INDEX``
284	with full mask, default value = 0.
285
286*	``--drop``
287	Add drop action to all flows actions.
288
289*	``--hairpin-queue=N``
290	Add hairpin queue action to all flows actions.
291	The queue will change in round robin state for each flow.
292
293	For example:
294		The app running with 4 RX hairpin queues and 4 normal RX queues
295		Flow #0: queue index 4
296		Flow #1: queue index 5
297		Flow #2: queue index 6
298		Flow #3: queue index 7
299		Flow #4: queue index 4
300		...
301
302*	``--hairpin-rss=N``
303	Add hairpin RSS action to all flows actions.
304	The queues in RSS action will be all hairpin queues configured
305	in the app.
306
307*	``--set-src-mac``
308	Add set source mac action to all flows actions.
309	The mac to be set is random each flow.
310
311*	``--set-dst-mac``
312	Add set destination mac action to all flows actions.
313	The mac to be set is random each flow.
314
315*	``-set-src-ipv4``
316	Add set source ipv4 action to all flows actions.
317	The ipv4 header to be set is random each flow.
318
319*	``--set-dst-ipv4``
320	Add set destination ipv4 action to all flows actions.
321	The ipv4 header to be set is random each flow.
322
323*	``--set-src-ipv6``
324	Add set source ipv6 action to all flows actions.
325	The ipv6 header to be set is random each flow.
326
327*	``--set-dst-ipv6``
328	Add set destination ipv6 action to all flows actions.
329	The ipv6 header to be set is random each flow.
330
331*	``--set-src-tp``
332	Add set source tp action to all flows actions.
333	The tp sport header to be set is random each flow.
334
335*	``--set-dst-tp``
336	Add set destination tp action to all flows actions.
337	The tp dport header to be set is random each flow.
338
339*	``--inc-tcp-ack``
340	Add increment TCP acknowledgment by one to all flows actions.
341
342*	``--dec-tcp-ack``
343	Add decrement TCP acknowledgment by one to all flows actions.
344
345*	``--inc-tcp-seq``
346	Add increment TCP sequence by one to all flows actions.
347
348*	``--dec-tcp-seq``
349	Add decrement TCP sequence by one to all flows actions.
350
351*	``--set-ttl``
352	Add set IP ttl action to all flows actions.
353	The ttl value to be set is random each flow.
354
355*	``--dec-ttl``
356	Add decrement IP ttl by one to all flows actions.
357
358*	``--set-ipv4-dscp``
359	Add set IPv4 dscp action to all flows actions.
360	The dscp value to be is random each flow.
361
362*	``--set-ipv6-dscp``
363	Add set IPv6 dscp action to all flows actions.
364	The dscp value to be is random each flow.
365
366*	``--flag``
367	Add flag action to all flows actions.
368
369*	``--raw-encap=<DATA>``
370	Add raw encap action to all flows actions.
371	Data is the data needed to be encaped, with fixed values.
372	Example: raw-encap=ether,ipv4,udp,vxlan
373
374*	``--raw-decap=<DATA>``
375	Add raw decap action to all flows actions.
376	Data is the data needed to be decaped, with fixed values.
377	Example: raw-decap=ether,ipv4,gre
378
379*	``--vxlan-encap``
380	Add vxlan encap action to all flows actions.
381	Data to encap is fixed with pattern: ether,ipv4,udp,vxlan,
382	all encapped items have fixed values.
383
384*	``--vxlan-decap``
385	Add vxlan decap action to all flows actions.
386
387*       ``--meter``
388        Add meter action to all flows actions.
389        Currently, 1 meter profile -> N meter rules -> N rte flows.
390