X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Ftestpmd_app_ug%2Frun_app.rst;h=640eadeff7353695186002971b44408cd77ac259;hb=a550baf24af90f76354eab0d4f91165a78157d38;hp=d0ced3687c25c41806a40764c16215db0fc9e959;hpb=fb73e096110a41b77448fe27fd9be8c489ec5d82;p=dpdk.git diff --git a/doc/guides/testpmd_app_ug/run_app.rst b/doc/guides/testpmd_app_ug/run_app.rst index d0ced3687c..640eadeff7 100644 --- a/doc/guides/testpmd_app_ug/run_app.rst +++ b/doc/guides/testpmd_app_ug/run_app.rst @@ -7,131 +7,9 @@ Running the Application EAL Command-line Options ------------------------ -The following are the EAL command-line options that can be used in conjunction with the testpmd, -or any other DPDK application. -See the DPDK Getting Started Guides for more information on these options. - -* ``-c COREMASK`` - - Set the hexadecimal bitmask of the cores to run on. - -* ``-l CORELIST`` - - List of cores to run on - - The argument format is ``[-c2][,c3[-c4],...]`` - where ``c1``, ``c2``, etc are core indexes between 0 and 128. - -* ``--lcores COREMAP`` - - Map lcore set to physical cpu set - - The argument format is:: - - [<,lcores[@cpus]>...] - - Lcore and CPU lists are grouped by ``(`` and ``)`` Within the group. - The ``-`` character is used as a range separator and ``,`` is used as a single number separator. - The grouping ``()`` can be omitted for single element group. - The ``@`` can be omitted if cpus and lcores have the same value. - -.. Note:: - At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can be used. - - -* ``--master-lcore ID`` - - Core ID that is used as master. - -* ``-n NUM`` - - Set the number of memory channels to use. - -* ``-b, --pci-blacklist domain:bus:devid.func`` - - Blacklist a PCI device to prevent EAL from using it. Multiple -b options are allowed. - -* ``-d LIB.so`` - - Load an external driver. Multiple -d options are allowed. - -* ``-w, --pci-whitelist domain:bus:devid:func`` - - Add a PCI device in white list. - -* ``-m MB`` - - Memory to allocate. See also ``--socket-mem``. - -* ``-r NUM`` - - Set the number of memory ranks (auto-detected by default). - -* ``-v`` - - Display the version information on startup. - -* ``--syslog`` - - Set the syslog facility. - -* ``--socket-mem`` - - Set the memory to allocate on specific sockets (use comma separated values). - -* ``--huge-dir`` - - Specify the directory where the hugetlbfs is mounted. - -* ``mbuf-pool-ops-name``: - - Pool ops name for mbuf to use. - -* ``--proc-type`` - - Set the type of the current process. - -* ``--file-prefix`` - - Prefix for hugepage filenames. - -* ``-vmware-tsc-map`` - - Use VMware TSC map instead of native RDTSC. - -* ``--vdev`` - - Add a virtual device using the format:: - - [,key=val, ...] - - For example:: - - --vdev 'net_pcap0,rx_pcap=input.pcap,tx_pcap=output.pcap' - -* ``--base-virtaddr`` - - Specify base virtual address. - -* ``--create-uio-dev`` - - Create ``/dev/uioX`` (usually done by hotplug). - -* ``--no-shconf`` - - No shared config (mmap-ed files). - -* ``--no-pci`` - - Disable pci. - -* ``--no-hpet`` - - Disable hpet. - -* ``--no-huge`` - - Use malloc instead of hugetlbfs. +Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>` +or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for +a list of available EAL command-line options. Testpmd Command-line Options @@ -142,9 +20,9 @@ They must be separated from the EAL options, shown in the previous section, with .. code-block:: console - sudo ./testpmd -l 0-3 -n 4 -- -i --portmask=0x1 --nb-cores=2 + sudo ./dpdk-testpmd -l 0-3 -n 4 -- -i --portmask=0x1 --nb-cores=2 -The commandline options are: +The command line options are: * ``-i, --interactive`` @@ -181,24 +59,31 @@ The commandline options are: * ``--nb-cores=N`` Set the number of forwarding cores, - where 1 <= N <= "number of cores" or ``CONFIG_RTE_MAX_LCORE`` from the configuration file. + where 1 <= N <= "number of cores" or ``RTE_MAX_LCORE`` from the configuration file. The default value is 1. * ``--nb-ports=N`` Set the number of forwarding ports, - where 1 <= N <= "number of ports" on the board or ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file. + where 1 <= N <= "number of ports" on the board or ``RTE_MAX_ETHPORTS`` from the configuration file. The default value is the number of ports on the board. * ``--coremask=0xXX`` Set the hexadecimal bitmask of the cores running the packet forwarding test. - The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding. + The main lcore is reserved for command line parsing only and cannot be masked on for packet forwarding. * ``--portmask=0xXX`` Set the hexadecimal bitmask of the ports used by the packet forwarding test. +* ``--portlist=X`` + + Set the forwarding ports based on the user input used by the packet forwarding test. + '-' denotes a range of ports to set including the two specified port IDs + ',' separates multiple port values. + Possible examples like --portlist=0,1 or --portlist=0-2 or --portlist=0,1-2 etc + * ``--numa`` Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers @@ -222,9 +107,12 @@ The commandline options are: Set the socket from which all memory is allocated in NUMA mode, where 0 <= N < number of sockets on the board. -* ``--mbuf-size=N`` +* ``--mbuf-size=N[,N1[,...Nn]`` - Set the data size of the mbufs used to N bytes, where N < 65536. The default value is 2048. + Set the data size of the mbufs used to N bytes, where N < 65536. + The default value is 2048. If multiple mbuf-size values are specified the + extra memory pools will be created for allocating mbufs to receive packets + with buffer splitting features. * ``--total-num-mbufs=N`` @@ -234,6 +122,10 @@ The commandline options are: Set the maximum packet size to N bytes, where N >= 64. The default value is 1518. +* ``--max-lro-pkt-size=N`` + + Set the maximum LRO aggregated packet size to N bytes, where N >= 64. + * ``--eth-peers-configfile=name`` Use a configuration file containing the Ethernet addresses of the peer ports. @@ -243,11 +135,23 @@ The commandline options are: XX:XX:XX:XX:XX:02 ... - * ``--eth-peer=N,XX:XX:XX:XX:XX:XX`` Set the MAC address ``XX:XX:XX:XX:XX:XX`` of the peer port N, - where 0 <= N < ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file. + where 0 <= N < ``RTE_MAX_ETHPORTS``. + +* ``--tx-ip=SRC,DST`` + + Set the source and destination IP address used when doing transmit only test. + The defaults address values are source 198.18.0.1 and + destination 198.18.0.2. These are special purpose addresses + reserved for benchmarking (RFC 5735). + +* ``--tx-udp=SRC[,DST]`` + + Set the source and destination UDP port number for transmit test only test. + The default port is the port 9 which is defined for the discard protocol + (RFC 863). * ``--pkt-filter-mode=mode`` @@ -308,6 +212,10 @@ The commandline options are: Enable hardware VLAN extend. +* ``--enable-hw-qinq-strip`` + + Enable hardware QINQ strip. + * ``--enable-drop-en`` Enable per-queue packet drop for packets with no descriptors. @@ -318,7 +226,7 @@ The commandline options are: * ``--port-topology=mode`` - Set port topology, where mode is ``paired`` (the default) or ``chained``. + Set port topology, where mode is ``paired`` (the default), ``chained`` or ``loop``. In ``paired`` mode, the forwarding is between pairs of ports, for example: (0,1), (2,3), (4,5). @@ -326,13 +234,15 @@ The commandline options are: The ordering of the ports can be changed using the portlist testpmd runtime function. + In ``loop`` mode, ingress traffic is simply transmitted back on the same interface. + * ``--forward-mode=mode`` Set the forwarding mode where ``mode`` is one of the following:: io (the default) mac - mac_swap + macswap flowgen rxonly txonly @@ -340,6 +250,8 @@ The commandline options are: icmpecho ieee1588 tm + noisy + 5tswap * ``--rss-ip`` @@ -369,10 +281,35 @@ The commandline options are: Set the number of descriptors in the TX rings to N, where N > 0. The default value is 512. +* ``--hairpinq=N`` + + Set the number of hairpin queues per port to N, where 1 <= N <= 65535. + The default value is 0. The number of hairpin queues are added to the + number of TX queues and to the number of RX queues. then the first + RX hairpin is binded to the first TX hairpin, the second RX hairpin is + binded to the second TX hairpin and so on. The index of the first + RX hairpin queue is the number of RX queues as configured using --rxq. + The index of the first TX hairpin queue is the number of TX queues + as configured using --txq. + * ``--burst=N`` Set the number of packets per burst to N, where 1 <= N <= 512. - The default value is 16. + The default value is 32. + If set to 0, driver default is used if defined. Else, if driver + default is not defined, default of 32 is used. + +* ``--flowgen-clones=N`` + + Set the number of each packet clones to be sent in `flowgen` mode. + Sending clones reduces host CPU load on creating packets and may help + in testing extreme speeds or maxing out Tx packet performance. + N should be not zero, but less than 'burst' parameter. + +* ``--flowgen-flows=N`` + + Set the number of flows to be generated in `flowgen` mode, where + 1 <= N <= INT32_MAX. * ``--mbcache=N`` @@ -424,27 +361,59 @@ The commandline options are: Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``. The default value is 0. -* ``--rx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]`` +* ``--no-flush-rx`` - Set the RX queues statistics counters mapping 0 <= mapping <= 15. + Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD. -* ``--tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]`` +* ``--rxoffs=X[,Y]`` - Set the TX queues statistics counters mapping 0 <= mapping <= 15. + Set the offsets of packet segments on receiving if split + feature is engaged. Affects only the queues configured + with split offloads (currently BUFFER_SPLIT is supported only). -* ``--no-flush-rx`` +* ``--rxpkts=X[,Y]`` - Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD. + Set the length of segments to scatter packets on receiving if split + feature is engaged. Affects only the queues configured + with split offloads (currently BUFFER_SPLIT is supported only). + Optionally the multiple memory pools can be specified with --mbuf-size + command line parameter and the mbufs to receive will be allocated + sequentially from these extra memory pools. * ``--txpkts=X[,Y]`` Set TX segment sizes or total packet length. Valid for ``tx-only`` and ``flowgen`` forwarding modes. +* ``--txonly-multi-flow`` + + Generate multiple flows in txonly mode. + +* ``--eth-link-speed`` + + Set a forced link speed to the ethernet port:: + + 10 - 10Mbps (not supported) + 100 - 100Mbps (not supported) + 1000 - 1Gbps + 10000 - 10Gbps + 25000 - 25Gbps + 40000 - 40Gbps + 50000 - 50Gbps + 100000 - 100Gbps + 200000 - 200Gbps + ... + * ``--disable-link-check`` Disable check on link status when starting/stopping ports. +* ``--disable-device-start`` + + Do not automatically start all ports. This allows testing + configuration of rx and tx queues before device is started + for the first time. + * ``--no-lsc-interrupt`` Disable LSC interrupts for all ports, even those supporting it. @@ -457,12 +426,12 @@ The commandline options are: Set the logical core N to perform bitrate calculation. -* ``--print-event `` +* ``--print-event `` Enable printing the occurrence of the designated event. Using all will enable all of them. -* ``--mask-event `` +* ``--mask-event `` Disable printing the occurrence of the designated event. Using all will disable all of them. @@ -480,6 +449,188 @@ The commandline options are: Set the hexadecimal bitmask of TX queue offloads. The default value is 0. +* ``--rx-offloads=0xXXXXXXXX`` + + Set the hexadecimal bitmask of RX queue offloads. + The default value is 0. + * ``--hot-plug`` - Enable device event monitor machenism for hotplug. + Enable device event monitor mechanism for hotplug. + +* ``--vxlan-gpe-port=N`` + + Set the UDP port number of tunnel VXLAN-GPE to N. + The default value is 4790. + +* ``--geneve-parsed-port=N`` + + Set the UDP port number that is used for parsing the GENEVE protocol to N. + HW may be configured with another tunnel Geneve port. + The default value is 6081. + +* ``--mlockall`` + + Enable locking all memory. + +* ``--no-mlockall`` + + Disable locking all memory. + +* ``--mp-alloc `` + + Select mempool allocation mode: + + * native: create and populate mempool using native DPDK memory + * anon: create mempool using native DPDK memory, but populate using + anonymous memory + * xmem: create and populate mempool using externally and anonymously + allocated area + * xmemhuge: create and populate mempool using externally and anonymously + allocated hugepage area + +* ``--noisy-tx-sw-buffer-size`` + + Set the number of maximum elements of the FIFO queue to be created + for buffering packets. Only available with the noisy forwarding mode. + The default value is 0. + +* ``--noisy-tx-sw-buffer-flushtime=N`` + + Set the time before packets in the FIFO queue is flushed. + Only available with the noisy forwarding mode. The default value is 0. + +* ``--noisy-lkup-memory=N`` + + Set the size of the noisy neighbor simulation memory buffer in MB to N. + Only available with the noisy forwarding mode. The default value is 0. + + +* ``--noisy-lkup-num-reads=N`` + + Set the number of reads to be done in noisy neighbor simulation memory buffer to N. + Only available with the noisy forwarding mode. The default value is 0. + +* ``--noisy-lkup-num-writes=N`` + + Set the number of writes to be done in noisy neighbor simulation memory buffer to N. + Only available with the noisy forwarding mode. The default value is 0. + +* ``--noisy-lkup-num-reads-writes=N`` + + Set the number of r/w accesses to be done in noisy neighbor simulation memory buffer to N. + Only available with the noisy forwarding mode. The default value is 0. + +* ``--no-iova-contig`` + + Enable to create mempool which is not IOVA contiguous. Valid only with --mp-alloc=anon. + The default value is 0. + +* ``--rx-mq-mode`` + + Set the hexadecimal bitmask of RX multi queue mode which can be enabled. + The default value is 0x7:: + + ETH_MQ_RX_RSS_FLAG | ETH_MQ_RX_DCB_FLAG | ETH_MQ_RX_VMDQ_FLAG + +* ``--record-core-cycles`` + + Enable measurement of CPU cycles per packet. + +* ``--record-burst-stats`` + + Enable display of RX and TX burst stats. + +* ``--hairpin-mode=0xXX`` + + Set the hairpin port mode with bitmask, only valid when hairpin queues number is set:: + + bit 4 - explicit Tx flow rule + bit 1 - two hairpin ports paired + bit 0 - two hairpin ports loop + + The default value is 0. Hairpin will use single port mode and implicit Tx flow mode. + + +Testpmd Multi-Process Command-line Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following are the command-line options for testpmd multi-process support: + +* primary process: + +.. code-block:: console + + sudo ./dpdk-testpmd -a xxx --proc-type=auto -l 0-1 -- -i --rxq=4 --txq=4 \ + --num-procs=2 --proc-id=0 + +* secondary process: + +.. code-block:: console + + sudo ./dpdk-testpmd -a xxx --proc-type=auto -l 2-3 -- -i --rxq=4 --txq=4 \ + --num-procs=2 --proc-id=1 + +The command line options are: + +* ``--num-procs=N`` + + The number of processes which will be used. + +* ``--proc-id=ID`` + + The ID of the current process (ID < num-procs). ID should be different in + primary process and secondary process, which starts from '0'. + +Calculation rule for queue: +All queues are allocated to different processes based on ``proc_num`` and +``proc_id``. +Calculation rule for the testpmd to allocate queues to each process: +* start(queue start id) = proc_id * nb_q / num_procs； + +* end(queue end id) = start + nb_q / num_procs； + +For example, if testpmd is configured to have 4 Tx and Rx queues, +queues 0 and 1 will be used by the primary process and +queues 2 and 3 will be used by the secondary process. + +The number of queues should be a multiple of the number of processes. If not, +redundant queues will exist after queues are allocated to processes. If RSS +is enabled, packet loss occurs when traffic is sent to all processes at the same +time. Some traffic goes to redundant queues and cannot be forwarded. + +All the dev ops is supported in primary process. While secondary process is +not permitted to allocate or release shared memory, so some ops are not supported +as follows: + +- ``dev_configure`` +- ``dev_start`` +- ``dev_stop`` +- ``rx_queue_setup`` +- ``tx_queue_setup`` +- ``rx_queue_release`` +- ``tx_queue_release`` + +So, any command from testpmd which calls those APIs will not be supported in +secondary process, like: + +.. code-block:: console + + port config all rxq|txq|rxd|txd + port config rx_offload xxx on/off + port config tx_offload xxx on/off + +etc. + +When secondary is running, port in primary is not permitted to be stopped. +Reconfigure operation is only valid in primary. + +Stats is supported, stats will not change when one quits and starts, as they +share the same buffer to store the stats. Flow rules are maintained in process +level: primary and secondary has its own flow list (but one flow list in HW). +The two can see all the queues, so setting the flow rules for the other is OK. +But in the testpmd primary process receiving or transmitting packets from the +queue allocated for secondary process is not permitted, and same for secondary +process. + +Flow API and RSS are supported.