xref: /dpdk/doc/guides/testpmd_app_ug/run_app.rst (revision bd89cca3ca34d255e48fa4246998c89bb38301d4) 
1..  BSD LICENSE
2    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
3    All rights reserved.
4
5    Redistribution and use in source and binary forms, with or without
6    modification, are permitted provided that the following conditions
7    are met:
8
9    * Redistributions of source code must retain the above copyright
10    notice, this list of conditions and the following disclaimer.
11    * Redistributions in binary form must reproduce the above copyright
12    notice, this list of conditions and the following disclaimer in
13    the documentation and/or other materials provided with the
14    distribution.
15    * Neither the name of Intel Corporation nor the names of its
16    contributors may be used to endorse or promote products derived
17    from this software without specific prior written permission.
18
19    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31Running the Application
32=======================
33
34EAL Command-line Options
35------------------------
36
37The following are the EAL command-line options that can be used in conjunction with the testpmd,
38or any other DPDK application.
39See the DPDK Getting Started Guide for more information on these options.
40
41*   -c COREMASK
42
43    Set the hexadecimal bitmask of the cores to run on.
44
45*   -n NUM
46
47    Set the number of memory channels to use.
48
49*   -b, --pci-blacklist domain:bus:devid.func
50
51    Blacklist a PCI devise to prevent EAL from using it. Multiple -b options are allowed.
52
53*   -d LIB.so
54
55    Load an external driver. Multiple -d options are allowed.
56
57*   -w, --pci-whitelist domain:bus:devid:func
58
59    Add a PCI device in white list.
60
61*   -m MB
62
63    Memory to allocate. See also --socket-mem.
64
65*   -r NUM
66
67    Set the number of memory ranks (auto-detected by default).
68
69*   -v
70
71    Display the version information on startup.
72
73*   --xen-dom0
74
75    Support application running on Xen Domain0 without hugetlbfs.
76
77*   --syslog
78
79    Set the syslog facility.
80
81*   --socket-mem
82
83    Set the memory to allocate on specific sockets (use comma separated values).
84
85*   --huge-dir
86
87    Specify the directory where the hugetlbfs is mounted.
88
89*   --proc-type
90
91    Set the type of the current process.
92
93*   --file-prefix
94
95    Prefix for hugepage filenames.
96
97*   -vmware-tsc-map
98
99    Use VMware TSC map instead of native RDTSC.
100
101*   --vdev
102
103    Add a virtual device, with format "<driver><id>[,key=val, ...]", e.g. --vdev=eth_pcap0,iface=eth2.
104
105*   --base-virtaddr
106
107    Specify base virtual address.
108
109*   --create-uio-dev
110
111    Create /dev/uioX (usually done by hotplug).
112
113*   --no-shconf
114
115    No shared config (mmap'd files).
116
117*   --no-pci
118
119    Disable pci.
120
121*   --no-hpet
122
123    Disable hpet.
124
125*   --no-huge
126
127    Use malloc instead of hugetlbfs.
128
129
130Testpmd Command-line Options
131----------------------------
132
133The following are the command-line options for the testpmd applications.
134They must be separated from the EAL options, shown in the previous section, with a -- separator:
135
136.. code-block:: console
137
138    sudo ./testpmd -c 0xF -n 4 -- -i --portmask=0x1 --nb-cores=2
139
140*   -i, --interactive
141
142    Run testpmd in interactive mode.
143    In this mode, the testpmd starts with a prompt that can be used to start and stop forwarding,
144    configure the application and display stats on the current packet processing session.
145    See the Section 5.0, "Test Runtime Functions" section for more details.
146
147    In non-interactive mode,
148    the application starts with the configuration specified on the command-line and
149    immediately enters forwarding mode.
150
151*   -h, --help
152
153    Display a help message and quit.
154
155*   -a, --auto-start
156
157    Start forwarding on init.
158
159*   --nb-cores=N
160
161    Set the number of forwarding cores,
162    where 1 <= N <= number of cores or RTE_MAX_LCORE from the configuration file.
163    The default value is 1.
164
165*   --nb-ports=N
166
167    Set the number of forwarding ports,
168    where 1 <= N <= number of ports on the board or RTE_MAX_ETHPORTS from the configuration file.
169    The default value is the number of ports on the board.
170
171*   --coremask=0xXX
172
173    Set the hexadecimal bitmask of the cores running the packet forwarding test.
174    The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
175
176*   --portmask=0xXX
177
178    Set the hexadecimal bitmask of the ports used by the packet forwarding test.
179
180*   --numa
181
182    Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers (mbufs).
183
184*   --port-numa-config=(port,socket)[,(port,socket)]
185
186    Specify the socket on which the memory pool to be used by the port will be allocated.
187
188*   --ring-numa-config=(port,flag,socket)[,(port,flag,socket)]
189
190    Specify the socket on which the TX/RX rings for the port will be allocated.
191    Where flag is 1 for RX, 2 for TX, and 3 for RX and TX.
192
193*   --socket-num=N
194
195    Set the socket from which all memory is allocated in NUMA mode,
196    where 0 <= N < number of sockets on the board.
197
198*   --mbuf-size=N
199
200    Set the data size of the mbufs used to N bytes, where N < 65536. The default value is 2048.
201
202*   --total-num-mbufs=N
203
204    Set the number of mbufs to be allocated in the mbuf pools, where N > 1024.
205
206*   --max-pkt-len=N
207
208    Set the maximum packet size to N bytes, where N >= 64. The default value is 1518.
209
210*   --eth-peers-configfile=name
211
212    Use a configuration file containing the Ethernet addresses of the peer ports.
213    The configuration file should contain the Ethernet addresses on separate lines:
214
215    XX:XX:XX:XX:XX:01
216
217    XX:XX:XX:XX:XX:02
218
219    ...
220
221*   --eth-peer=N,XX:XX:XX:XX:XX:XX
222
223    Set the MAC address XX:XX:XX:XX:XX:XX of the peer port N,
224    where 0 <= N < RTE_MAX_ETHPORTS from the configuration file.
225
226*   --pkt-filter-mode=mode
227
228    Set Flow Director mode where mode is either none (the default), signature or perfect.
229    See the Section 5.6, "Flow Director Functions" for more detail.
230
231*   --pkt-filter-report-hash=mode
232
233    Set Flow Director hash match reporting mode where mode is none, match (the default) or always.
234
235*   --pkt-filter-size=N
236
237    Set Flow Director allocated memory size, where N is 64K, 128K or 256K.
238    Sizes are in kilobytes. The default is 64.
239
240*   --pkt-filter-flexbytes-offset=N
241
242    Set the flexbytes offset.
243    The offset is defined in words (not bytes) counted from the first byte of the destination Ethernet MAC address,
244    where N is 0 <= N <= 32.
245    The default value is 0x6.
246
247*   --pkt-filter-drop-queue=N
248
249    Set the drop-queue.
250    In perfect filter mode, when a rule is added with queue = -1, the packet will be enqueued into the RX drop-queue.
251    If the drop-queue does not exist, the packet is dropped. The default value is N=127.
252
253*   --crc-strip
254
255    Enable hardware CRC stripping.
256
257*   --enable-rx-cksum
258
259    Enable hardware RX checksum offload.
260
261*   --disable-hw-vlan
262
263    Disable hardware VLAN.
264
265*   --enable-drop-en
266
267    Enable per-queue packet drop for packets with no descriptors.
268
269*   --disable-rss
270
271    Disable RSS (Receive Side Scaling).
272
273*   --port-topology=mode
274
275    Set port topology, where mode is paired(the default) or chained.
276    In paired mode, the forwarding is between pairs of ports, for example: (0,1), (2,3), (4,5).
277    In chained mode, the forwarding is to the next available port in the port mask, for example: (0,1), (1,2), (2,0).
278    The ordering of the ports can be changed using the portlist testpmd runtime function.
279
280*   --forward-mode=N
281
282    Set forwarding mode. (N: io|mac|mac_retry|mac_swap|flowgen|rxonly|txonly|csum|icmpecho)
283
284*   --rss-ip
285
286    Set RSS functions for IPv4/IPv6 only.
287
288*   --rss-udp
289
290    Set RSS functions for IPv4/IPv6 and UDP.
291
292*   --rxq=N
293
294    Set the number of RX queues per port to N, where 1 <= N <= 65535.
295    The default value is 1.
296
297*   --rxd=N
298
299    Set the number of descriptors in the RX rings to N, where N > 0.
300    The default value is 128.
301
302*   --txq=N
303
304    Set the number of TX queues per port to N, where 1 <= N <= 65535.
305    The default value is 1.
306
307*   --txd=N
308
309    Set the number of descriptors in the TX rings to N, where N > 0.
310    The default value is 512.
311
312*   --burst=N
313
314    Set the number of packets per burst to N, where 1 <= N <= 512.
315    The default value is 16.
316
317*   --mbcache=N
318
319    Set the cache of mbuf memory pools to N, where 0 <= N <= 512.
320    The default value is 16.
321
322*   --rxpt=N
323
324    Set the prefetch threshold register of RX rings to N, where N >= 0.
325    The default value is 8.
326
327*   --rxht=N
328
329    Set the host threshold register of RX rings to N, where N >= 0.
330    The default value is 8.
331
332*   --rxfreet=N
333
334    Set the free threshold of RX descriptors to N, where 0 <= N < value of --rxd.
335    The default value is 0.
336
337*   --rxwt=N
338
339    Set the write-back threshold register of RX rings to N, where N >= 0.
340    The default value is 4.
341
342*   --txpt=N
343
344    Set the prefetch threshold register of TX rings to N, where N >= 0.
345    The default value is 36.
346
347*   --txht=N
348
349    Set the host threshold register of TX rings to N, where N >= 0.
350    The default value is 0.
351
352*   --txwt=N
353
354    Set the write-back threshold register of TX rings to N, where N >= 0.
355    The default value is 0.
356
357*   --txfreet=N
358
359    Set the transmit free threshold of TX rings to N, where 0 <= N <= value of --txd.
360    The default value is 0.
361
362*   --txrst=N
363
364    Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of --txd.
365    The default value is 0.
366
367*   --txqflags=0xXXXXXXXX
368
369    Set the hexadecimal bitmask of TX queue flags, where 0 <= N <= 0x7FFFFFFF.
370    The default value is 0.
371
372*   --rx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]
373
374    Set the RX queues statistics counters mapping 0 <= mapping <= 15.
375
376*   --tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]
377
378    Set the TX queues statistics counters mapping 0 <= mapping <= 15.
379
380*   --no-flush-rx
381
382    Don't flush the RX streams before starting forwarding. Used mainly with PCAP drivers.
383
384*   --txpkts=X[,Y]
385
386    Set TX segment sizes.
387
388*   --disable-link-check
389
390    Disable check on link status when starting/stopping ports.
391