vhost: add power monitor API

[dpdk.git] / doc / guides / testpmd_app_ug / run_app.rst

diff --git a/doc/guides/testpmd_app_ug/run_app.rst b/doc/guides/testpmd_app_ug/run_app.rst
index 95348ef..30edef0 100644 (file)
--- a/doc/guides/testpmd_app_ug/run_app.rst
+++ b/doc/guides/testpmd_app_ug/run_app.rst
@@ -20,7 +20,7 @@ They must be separated from the EAL options, shown in the previous section, with
 
 .. code-block:: console
 
 
 .. 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 command line options are:
 
 
 The command line options are:
 


@@ -56,22 +56,28 @@ The command line options are:
     Display statistics every PERIOD seconds, if interactive mode is disabled.
     The default value is 0, which means that the statistics will not be displayed.
 
     Display statistics every PERIOD seconds, if interactive mode is disabled.
     The default value is 0, which means that the statistics will not be displayed.
 

+*   ``--display-xstats xstat_name1[,...]``
+
+    Display comma-separated list of extended statistics every PERIOD seconds
+    as specified in ``--stats-period`` or when used with interactive commands
+    that show Rx/Tx statistics (i.e. 'show port stats').
+

 *   ``--nb-cores=N``
 
     Set the number of forwarding cores,
 *   ``--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,
     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 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``
 
 
 *   ``--portmask=0xXX``
 


@@ -112,7 +118,7 @@ The command line options are:
     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
     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 splittling features.
+    with buffer splitting features.

 
 *   ``--total-num-mbufs=N``
 
 
 *   ``--total-num-mbufs=N``
 


@@ -138,7 +144,7 @@ The command line options are:
 *   ``--eth-peer=N,XX:XX:XX:XX:XX:XX``
 
     Set the MAC address ``XX:XX:XX:XX:XX:XX`` of the peer port N,
 *   ``--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``
 
 
 *   ``--tx-ip=SRC,DST``
 


@@ -252,6 +258,7 @@ The command line options are:
        tm
        noisy
        5tswap
        tm
        noisy
        5tswap

+       shared-rxq

 
 *   ``--rss-ip``
 
 
 *   ``--rss-ip``
 


@@ -299,6 +306,18 @@ The command line options are:
     If set to 0, driver default is used if defined. Else, if driver
     default is not defined, default of 32 is used.
 
     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``
 
     Set the cache of mbuf memory pools to N, where 0 <= N <= 512.
 *   ``--mbcache=N``
 
     Set the cache of mbuf memory pools to N, where 0 <= N <= 512.


@@ -349,14 +368,6 @@ The command line options are:
     Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
     The default value is 0.
 
     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)]``
-
-    Set the RX queues statistics counters mapping 0 <= mapping <= 15.
-
-*   ``--tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]``
-
-    Set the TX queues statistics counters mapping 0 <= mapping <= 15.
-

 *   ``--no-flush-rx``
 
     Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD.
 *   ``--no-flush-rx``
 
     Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD.


@@ -385,6 +396,29 @@ The command line options are:
 
     Generate multiple flows in txonly mode.
 
 
     Generate multiple flows in txonly mode.
 

+*   ``--rxq-share=[X]``
+
+    Create queues in shared Rx queue mode if device supports.
+    Shared Rx queues are grouped per X ports. X defaults to UINT32_MAX,
+    implies all ports join share group 1. Forwarding engine "shared-rxq"
+    should be used for shared Rx queues. This engine does Rx only and
+    update stream statistics accordingly.
+
+*   ``--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-link-check``
 
     Disable check on link status when starting/stopping ports.


@@ -512,7 +546,7 @@ The command line options are:
     Set the hexadecimal bitmask of RX multi queue mode which can be enabled.
     The default value is 0x7::
 
     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
+       RTE_ETH_MQ_RX_RSS_FLAG | RTE_ETH_MQ_RX_DCB_FLAG | RTE_ETH_MQ_RX_VMDQ_FLAG

 
 *   ``--record-core-cycles``
 
 
 *   ``--record-core-cycles``
 


@@ -524,8 +558,94 @@ The command line options are:
 
 *   ``--hairpin-mode=0xXX``
 
 
 *   ``--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
+    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.
     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 <value>
+    port config <port_id> rx_offload xxx on/off
+    port config <port_id> 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.