xref: /f-stack/dpdk/doc/guides/tools/flow-perf.rst (revision 2d9fd380) 
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 multi core performance measurements.
29
30
31Known Limitations
32-----------------
33
34The current version has limitations which can be removed in future:
35
36* Single core insertion only.
37
38
39Compiling the Application
40-------------------------
41
42The ``test-flow-perf`` application is compiled as part of the main compilation
43of the DPDK libraries and tools.
44
45Refer to the DPDK Getting Started Guides for details.
46
47
48Running the Application
49-----------------------
50
51EAL Command-line Options
52~~~~~~~~~~~~~~~~~~~~~~~~
53
54Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>`
55or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for
56a list of available EAL command-line options.
57
58
59Flow Performance Options
60~~~~~~~~~~~~~~~~~~~~~~~~
61
62The following are the command-line options for the flow performance application.
63They must be separated from the EAL options, shown in the previous section,
64with a ``--`` separator:
65
66.. code-block:: console
67
68	sudo ./dpdk-test-flow_perf -n 4 -a 08:00.0 -- --ingress --ether --ipv4 --queue --rules-count=1000000
69
70The command line options are:
71
72*	``--help``
73	Display a help message and quit.
74
75*	``--rules-count=N``
76	Set the total number of flow rules to insert,
77	where 1 <= N <= "number of flow rules".
78	The default value is 4,000,000.
79
80*	``--rules-batch=N``
81	Set the number of flow rules to insert per iteration window,
82	where 1 <= N <= "number of flow rules per iteration window".
83	The default value is 100,000 flow rules per iteration window.
84	For a total of --rules-count=1000000 flow rules to be inserted
85	and an iteration window size of --rules-batch=100000 flow rules,
86	the application will measure the insertion rate 10 times
87	(i.e., once every 100000 flow rules) and then report an average
88	insertion rate across the 10 measurements.
89
90*	``--dump-iterations``
91	Print rates for each iteration window.
92	Default iteration window equals to the rules-batch size (i.e., 100,000).
93
94*	``--deletion-rate``
95	Enable deletion rate calculations.
96
97*	``--dump-socket-mem``
98	Dump the memory stats for each socket before the insertion and after.
99
100*	``--enable-fwd``
101	Enable packets forwarding after insertion/deletion operations.
102
103*	``--portmask=N``
104	hexadecimal bitmask of ports to be used.
105
106
107Attributes:
108
109*	``--ingress``
110	Set Ingress attribute to all flows attributes.
111
112*	``--egress``
113	Set Egress attribute to all flows attributes.
114
115*	``--transfer``
116	Set Transfer attribute to all flows attributes.
117
118*	``--group=N``
119	Set group for all flows, where N >= 0.
120	Default group is 0.
121
122Items:
123
124*	``--ether``
125	Add Ether item to all flows items, This item have open mask.
126
127*	``--vlan``
128	Add VLAN item to all flows items,
129	This item have VLAN value defined in user_parameters.h
130	under ``VNI_VALUE`` with full mask, default value = 1.
131	Other fields are open mask.
132
133*	``--ipv4``
134	Add IPv4 item to all flows items,
135	This item have incremental source IP, with full mask.
136	Other fields are open mask.
137
138*	``--ipv6``
139	Add IPv6 item to all flows item,
140	This item have incremental source IP, with full mask.
141	Other fields are open mask.
142
143*	``--tcp``
144	Add TCP item to all flows items, This item have open mask.
145
146*	``--udp``
147	Add UDP item to all flows items, This item have open mask.
148
149*	``--vxlan``
150	Add VXLAN item to all flows items,
151	This item have VNI value defined in user_parameters.h
152	under ``VNI_VALUE`` with full mask, default value = 1.
153	Other fields are open mask.
154
155*	``--vxlan-gpe``
156	Add VXLAN-GPE item to all flows items,
157	This item have VNI value defined in user_parameters.h
158	under ``VNI_VALUE`` with full mask, default value = 1.
159	Other fields are open mask.
160
161*	``--gre``
162	Add GRE item to all flows items,
163	This item have protocol value defined in user_parameters.h
164	under ``GRE_PROTO`` with full mask, default protocol = 0x6558 "Ether"
165	Other fields are open mask.
166
167*	``--geneve``
168	Add GENEVE item to all flows items,
169	This item have VNI value defined in user_parameters.h
170	under ``VNI_VALUE`` with full mask, default value = 1.
171	Other fields are open mask.
172
173*	``--gtp``
174	Add GTP item to all flows items,
175	This item have TEID value defined in user_parameters.h
176	under ``TEID_VALUE`` with full mask, default value = 1.
177	Other fields are open mask.
178
179*	``--meta``
180	Add Meta item to all flows items,
181	This item have data value defined in user_parameters.h
182	under ``META_DATA`` with full mask, default value = 1.
183	Other fields are open mask.
184
185*	``--tag``
186	Add Tag item to all flows items,
187	This item have data value defined in user_parameters.h
188	under ``META_DATA`` with full mask, default value = 1.
189
190	Also it have tag value defined in user_parameters.h
191	under ``TAG_INDEX`` with full mask, default value = 0.
192	Other fields are open mask.
193
194*	``--icmpv4``
195	Add icmpv4 item to all flows items, This item have open mask.
196
197*	``--icmpv6``
198	Add icmpv6 item to all flows items, This item have open mask.
199
200
201Actions:
202
203*	``--port-id``
204	Add port redirection action to all flows actions.
205	Port redirection destination is defined in user_parameters.h
206	under PORT_ID_DST, default value = 1.
207
208*	``--rss``
209	Add RSS action to all flows actions,
210	The queues in RSS action will be all queues configured
211	in the app.
212
213*	``--queue``
214	Add queue action to all flows items,
215	The queue will change in round robin state for each flow.
216
217	For example:
218		The app running with 4 RX queues
219		Flow #0: queue index 0
220		Flow #1: queue index 1
221		Flow #2: queue index 2
222		Flow #3: queue index 3
223		Flow #4: queue index 0
224		...
225
226*	``--jump``
227	Add jump action to all flows actions.
228	Jump action destination is defined in user_parameters.h
229	under ``JUMP_ACTION_TABLE``, default value = 2.
230
231*	``--mark``
232	Add mark action to all flows actions.
233	Mark action id is defined in user_parameters.h
234	under ``MARK_ID``, default value = 1.
235
236*	``--count``
237	Add count action to all flows actions.
238
239*	``--set-meta``
240	Add set-meta action to all flows actions.
241	Meta data is defined in user_parameters.h under ``META_DATA``
242	with full mask, default value = 1.
243
244*	``--set-tag``
245	Add set-tag action to all flows actions.
246	Meta data is defined in user_parameters.h under ``META_DATA``
247	with full mask, default value = 1.
248
249	Tag index is defined in user_parameters.h under ``TAG_INDEX``
250	with full mask, default value = 0.
251
252*	``--drop``
253	Add drop action to all flows actions.
254
255*	``--hairpin-queue=N``
256	Add hairpin queue action to all flows actions.
257	The queue will change in round robin state for each flow.
258
259	For example:
260		The app running with 4 RX hairpin queues and 4 normal RX queues
261		Flow #0: queue index 4
262		Flow #1: queue index 5
263		Flow #2: queue index 6
264		Flow #3: queue index 7
265		Flow #4: queue index 4
266		...
267
268*	``--hairpin-rss=N``
269	Add hairpin RSS action to all flows actions.
270	The queues in RSS action will be all hairpin queues configured
271	in the app.
272
273*	``--set-src-mac``
274	Add set source mac action to all flows actions.
275	The mac to be set is random each flow.
276
277*	``--set-dst-mac``
278	Add set destination mac action to all flows actions.
279	The mac to be set is random each flow.
280
281*	``-set-src-ipv4``
282	Add set source ipv4 action to all flows actions.
283	The ipv4 header to be set is random each flow.
284
285*	``--set-dst-ipv4``
286	Add set destination ipv4 action to all flows actions.
287	The ipv4 header to be set is random each flow.
288
289*	``--set-src-ipv6``
290	Add set source ipv6 action to all flows actions.
291	The ipv6 header to be set is random each flow.
292
293*	``--set-dst-ipv6``
294	Add set destination ipv6 action to all flows actions.
295	The ipv6 header to be set is random each flow.
296
297*	``--set-src-tp``
298	Add set source tp action to all flows actions.
299	The tp sport header to be set is random each flow.
300
301*	``--set-dst-tp``
302	Add set destination tp action to all flows actions.
303	The tp dport header to be set is random each flow.
304
305*	``--inc-tcp-ack``
306	Add increment TCP acknowledgment by one to all flows actions.
307
308*	``--dec-tcp-ack``
309	Add decrement TCP acknowledgment by one to all flows actions.
310
311*	``--inc-tcp-seq``
312	Add increment TCP sequence by one to all flows actions.
313
314*	``--dec-tcp-seq``
315	Add decrement TCP sequence by one to all flows actions.
316
317*	``--set-ttl``
318	Add set IP ttl action to all flows actions.
319	The ttl value to be set is random each flow.
320
321*	``--dec-ttl``
322	Add decrement IP ttl by one to all flows actions.
323
324*	``--set-ipv4-dscp``
325	Add set IPv4 dscp action to all flows actions.
326	The dscp value to be is random each flow.
327
328*	``--set-ipv6-dscp``
329	Add set IPv6 dscp action to all flows actions.
330	The dscp value to be is random each flow.
331
332*	``--flag``
333	Add flag action to all flows actions.
334
335*	``--raw-encap=<DATA>``
336	Add raw encap action to all flows actions.
337	Data is the data needed to be encaped, with fixed values.
338	Example: raw-encap=ether,ipv4,udp,vxlan
339
340*	``--raw-decap=<DATA>``
341	Add raw decap action to all flows actions.
342	Data is the data needed to be decaped, with fixed values.
343	Example: raw-decap=ether,ipv4,gre
344
345*	``--vxlan-encap``
346	Add vxlan encap action to all flows actions.
347	Data to encap is fixed with pattern: ether,ipv4,udp,vxlan,
348	all encapped items have fixed values.
349
350*	``--vxlan-decap``
351	Add vxlan decap action to all flows actions.
352