fib: Compiile time option to use 8-8-8-8 stride tries for FIB rather

[vpp.git] / test / doc / overview.rst

diff --git a/test/doc/overview.rst b/test/doc/overview.rst
index fbb51f2..89e557f 100644 (file)
--- a/test/doc/overview.rst
+++ b/test/doc/overview.rst
@@ -5,6 +5,9 @@
 .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 .. _scapy: http://www.secdev.org/projects/scapy/
 .. _logging: https://docs.python.org/2/library/logging.html
+.. _process: https://docs.python.org/2/library/multiprocessing.html#the-process-class
+.. _pipes: https://docs.python.org/2/library/multiprocessing.html#multiprocessing.Pipe
+.. _managed: https://docs.python.org/2/library/multiprocessing.html#managers
 
 .. |vtf| replace:: VPP Test Framework
 
@@ -13,7 +16,7 @@
 
 .. contents::
    :local:
-   :depth: 2
+   :depth: 1
 
 Overview
 ########
@@ -70,6 +73,29 @@ To control the messages printed to console, specify the V= parameter.
    make test V=1     # moderate verbosity
    make test V=2     # maximum verbosity
 
+Parallel test execution
+#######################
+
+|vtf| test suites can be run in parallel. Each test suite is executed
+in a separate process spawned by Python multiprocessing process_.
+
+The results from child test suites are sent to parent through pipes_, which are
+aggregated and summarized at the end of the run.
+
+Stdout, stderr and logs logged in child processes are redirected to individual
+parent managed_ queues. The data from these queues are then emitted to stdout
+of the parent process in the order the test suites have finished. In case there
+are no finished test suites (such as at the beginning of the run), the data
+from last started test suite are emitted in real time.
+
+To enable parallel test run, specify the number of parallel processes:
+
+.. code-block:: shell
+
+   make test TEST_JOBS=n       # at most n processes will be spawned
+   make test TEST_JOBS=auto    # chosen based on the number of cores
+                               # and the size of shared memory
+
 Test temporary directory and VPP life cycle
 ###########################################
 
@@ -214,7 +240,7 @@ packets, it should specify either None or a custom filtering function
 as the value to the 'filter_out_fn' argument.
 
 Common API flow for sending/receiving packets:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We will describe a simple scenario, where packets are sent from pg0 to pg1
 interface, assuming that the interfaces were created using
@@ -318,7 +344,7 @@ basic IPv4 forwarding.
      class IP4FwdTestCase(VppTestCase):
          """ IPv4 simple forwarding test case """
 
-2. Add a setUpClass function containing the setup needed for our test to run::
+3. Add a setUpClass function containing the setup needed for our test to run::
 
          @classmethod
          def setUpClass(self):
@@ -329,7 +355,7 @@ basic IPv4 forwarding.
                  i.config_ip4()  # configure IPv4 address on the interface
                  i.resolve_arp()  # resolve ARP, so that we know VPP MAC
 
-3. Create a helper method to create the packets to send::
+4. Create a helper method to create the packets to send::
 
          def create_stream(self, src_if, dst_if, count):
              packets = []
@@ -351,7 +377,7 @@ basic IPv4 forwarding.
              # return the created packet list
              return packets
 
-4. Create a helper method to verify the capture::
+5. Create a helper method to verify the capture::
 
          def verify_capture(self, src_if, dst_if, capture):
              packet_info = None
@@ -360,7 +386,7 @@ basic IPv4 forwarding.
                      ip = packet[IP]
                      udp = packet[UDP]
                      # convert the payload to packet info object
-                     payload_info = self.payload_to_info(str(packet[Raw]))
+                     payload_info = self.payload_to_info(packet[Raw])
                      # make sure the indexes match
                      self.assert_equal(payload_info.src, src_if.sw_if_index,
                                        "source sw_if_index")
@@ -393,7 +419,7 @@ basic IPv4 forwarding.
                                "Interface %s: Packet expected from interface "
                                "%s didn't arrive" % (dst_if.name, src_if.name))
 
-5. Add the test code to test_basic function::
+6. Add the test code to test_basic function::
 
          def test_basic(self):
              count = 10
@@ -415,4 +441,5 @@ basic IPv4 forwarding.
              # verify capture
              self.verify_capture(self.pg0, self.pg1, capture)
 
-6. Run the test by issuing 'make test'.
+7. Run the test by issuing 'make test' or, to run only this specific
+   test, issue 'make test TEST=test_ip4_fwd'.