docs: better docs, mv doxygen to sphinx

This patch refactors the VPP sphinx docs
in order to make it easier to consume
for external readers as well as VPP developers.

It also makes sphinx the single source
of documentation, which simplifies maintenance
and operation.

Most important updates are:

- reformat the existing documentation as rst
- split RELEASE.md and move it into separate rst files
- remove section 'events'
- remove section 'archive'
- remove section 'related projects'
- remove section 'feature by release'
- remove section 'Various links'
- make (Configuration reference, CLI docs,
  developer docs) top level items in the list
- move 'Use Cases' as part of 'About VPP'
- move 'Troubleshooting' as part of 'Getting Started'
- move test framework docs into 'Developer Documentation'
- add a 'Contributing' section for gerrit,
  docs and other contributer related infos
- deprecate doxygen and test-docs targets
- redirect the "make doxygen" target to "make docs"

Type: refactor

Change-Id: I552a5645d5b7964d547f99b1336e2ac24e7c209f
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>

6 files changed, 594 insertions, 0 deletions

diff --git a/docs/developer/build-run-debug/building.rst b/docs/developer/build-run-debug/building.rst
new file mode 100644
index 00000000000..1df838abf84
--- /dev/null
+++ b/docs/developer/build-run-debug/building.rst
@@ -0,0 +1,181 @@
+.. _building:
+
+.. toctree::
+
+Building VPP
+============
+
+To get started developing with VPP, you need to get the required VPP sources and then build the packages.
+For more detailed information on the build system please refer to :ref:`buildsystem`.
+
+.. _setupproxies:
+
+Set up Proxies
+--------------------------
+
+Depending on the environment you are operating in, proxies may need to be set.
+Run these proxy commands to specify the *proxy-server-name* and corresponding *port-number*:
+
+.. code-block:: console
+
+    $ export http_proxy=http://<proxy-server-name>.com:<port-number>
+    $ export https_proxy=https://<proxy-server-name>.com:<port-number>
+
+
+Get the VPP Sources
+-----------------------------------
+
+To get the VPP sources that are used to create the build, run the following commands:
+
+.. code-block:: console
+
+    $ git clone https://gerrit.fd.io/r/vpp
+    $ cd vpp
+
+Build VPP Dependencies
+--------------------------------------
+
+Before building a VPP image, make sure there are no FD.io VPP or DPDK packages
+installed, by entering the following commands:
+
+.. code-block:: console
+
+    $ dpkg -l | grep vpp
+    $ dpkg -l | grep DPDK
+
+There should be no output, or no packages shown after the above commands are run.
+
+Run the following **make** command to install the dependencies for FD.io VPP.
+
+If the download hangs at any point, then you may need to
+:ref:`set up proxies <setupproxies>` for the download to work.
+
+.. code-block:: console
+
+    $ make install-dep
+    Hit:1 http://us.archive.ubuntu.com/ubuntu xenial InRelease
+    Get:2 http://us.archive.ubuntu.com/ubuntu xenial-updates InRelease [109 kB]
+    Get:3 http://security.ubuntu.com/ubuntu xenial-security InRelease [107 kB]
+    Get:4 http://us.archive.ubuntu.com/ubuntu xenial-backports InRelease [107 kB]
+    Get:5 http://us.archive.ubuntu.com/ubuntu xenial-updates/main amd64 Packages [803 kB]
+    Get:6 http://us.archive.ubuntu.com/ubuntu xenial-updates/main i386 Packages [732 kB]
+    ...
+    ...
+    Update-alternatives: using /usr/lib/jvm/java-8-openjdk-amd64/bin/jmap to provide /usr/bin/jmap (jmap) in auto mode
+    Setting up default-jdk-headless (2:1.8-56ubuntu2) ...
+    Processing triggers for libc-bin (2.23-0ubuntu3) ...
+    Processing triggers for systemd (229-4ubuntu6) ...
+    Processing triggers for ureadahead (0.100.0-19) ...
+    Processing triggers for ca-certificates (20160104ubuntu1) ...
+    Updating certificates in /etc/ssl/certs...
+    0 added, 0 removed; done.
+    Running hooks in /etc/ca-certificates/update.d...
+
+    done.
+    done.
+
+Build VPP (Debug)
+----------------------------
+
+This build version contains debug symbols which are useful for modifying VPP. The
+**make** command below builds a debug version of VPP. The binaries, when building the
+debug images, can be found in /build-root/vpp_debug-native.
+
+The Debug build version contains debug symbols, which are useful for troubleshooting
+or modifying VPP. The **make** command below, builds a debug version of VPP. The
+binaries used for building the debug image can be found in */build-root/vpp_debug-native*.
+
+.. code-block:: console
+
+    $ make build
+    make[1]: Entering directory '/home/vagrant/vpp-master/build-root'
+    @@@@ Arch for platform 'vpp' is native @@@@
+    @@@@ Finding source for dpdk @@@@
+    @@@@ Makefile fragment found in /home/vagrant/vpp-master/build-data/packages/dpdk.mk @@@@
+    @@@@ Source found in /home/vagrant/vpp-master/dpdk @@@@
+    @@@@ Arch for platform 'vpp' is native @@@@
+    @@@@ Finding source for vpp @@@@
+    @@@@ Makefile fragment found in /home/vagrant/vpp-master/build-data/packages/vpp.mk @@@@
+    @@@@ Source found in /home/vagrant/vpp-master/src @@@@
+    ...
+    ...
+    make[5]: Leaving directory '/home/vagrant/vpp-master/build-root/build-vpp_debug-native/vpp/vpp-api/java'
+    make[4]: Leaving directory '/home/vagrant/vpp-master/build-root/build-vpp_debug-native/vpp/vpp-api/java'
+    make[3]: Leaving directory '/home/vagrant/vpp-master/build-root/build-vpp_debug-native/vpp'
+    make[2]: Leaving directory '/home/vagrant/vpp-master/build-root/build-vpp_debug-native/vpp'
+    @@@@ Installing vpp: nothing to do @@@@
+    make[1]: Leaving directory '/home/vagrant/vpp-master/build-root'
+
+Build VPP (Release Version)
+-----------------------------------------
+
+This section describes how to build the regular release version of FD.io VPP. The
+release build is optimized and does not create any debug symbols.
+The binaries used in building the release images are found in */build-root/vpp-native*.
+
+Use the following **make** command below to build the release version of FD.io VPP.
+
+.. code-block:: console
+
+    $ make build-release
+
+
+Building Necessary Packages
+--------------------------------------------
+
+The package that needs to be built depends on the type system VPP will be running on:
+
+* The :ref:`Debian package <debianpackages>` is built if VPP is going to run on Ubuntu
+* The :ref:`RPM package <rpmpackages>` is built if VPP is going to run on Centos or Redhat
+
+.. _debianpackages:
+
+Building Debian Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To build the debian packages, use the following command:
+
+.. code-block:: console
+
+    $ make pkg-deb
+
+.. _rpmpackages:
+
+Building RPM Packages
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To build the rpm packages, use one of the following commands below, depending on the system:
+
+.. code-block:: console
+
+    $ make pkg-rpm
+
+Once the packages are built they can be found in the build-root directory.
+
+.. code-block:: console
+
+    $ ls *.deb
+
+    If the packages are built correctly, then this should be the corresponding output:
+
+    vpp_18.07-rc0~456-gb361076_amd64.deb             vpp-dbg_18.07-rc0~456-gb361076_amd64.deb
+    vpp-dev_18.07-rc0~456-gb361076_amd64.deb         vpp-api-lua_18.07-rc0~456-gb361076_amd64.deb
+    vpp-lib_18.07-rc0~456-gb361076_amd64.deb         vpp-api-python_18.07-rc0~456-gb361076_amd64.deb
+    vpp-plugins_18.07-rc0~456-gb361076_amd64.deb
+
+Finally, the created packages can be installed using the following commands. Install
+the package that corresponds to OS that VPP will be running on:
+
+For Ubuntu:
+
+.. code-block:: console
+
+   $ sudo bash
+   # dpkg -i *.deb
+
+For Centos or Redhat:
+
+.. code-block:: console
+
+   $ sudo bash
+   # rpm -ivh *.rpm
diff --git a/docs/developer/build-run-debug/cross_compile_macos.rst b/docs/developer/build-run-debug/cross_compile_macos.rst
new file mode 100644
index 00000000000..5eec5569a8b
--- /dev/null
+++ b/docs/developer/build-run-debug/cross_compile_macos.rst
@@ -0,0 +1,70 @@
+.. _cross_compile_macos :
+
+Cross compilation on MacOS
+==========================
+
+This is a first attempt to support Cross compilation of VPP on MacOS for development (linting, completion, compile_commands.json)
+
+
+**Prerequisites**
+
+* You'll need to install the following packages
+
+.. code-block:: console
+
+  $ pip3 install ply pyyaml jsonschema
+  $ brew install gnu-sed pkg-config ninja crosstool-ng
+
+* You'll also need to install ``clang-format 10.0.0`` to be able to ``make checkstyle``. This can be done with :ref:`this doc<install_clang_format_10_0_0>`
+* You should link the binaries to make them available in your path with their original names e.g. :
+
+.. code-block:: console
+
+  $ ln -s $(which gsed) /usr/local/bin/sed
+
+**Setup**
+
+* Create a `cross compile toolchain <https://crosstool-ng.github.io/>`_
+* Create a case sensitive volume and mount the toolchain in it e.g. in ``/Volumes/xchain``
+* Create a xchain.toolchain file with ``$VPP_DIR/extras/scripts/cross_compile_macos.sh conf /Volumes/xchan``
+
+For now we don't support e-build so dpdk, rdma, quicly won't be compiled as part of ``make build``
+
+To build with the toolchain do:
+
+.. code-block:: console
+
+  $ $VPP_DIR/extras/scripts/cross_compile_macos.sh build
+
+
+To get the compile_commands.json do
+
+.. code-block:: console
+
+  $ $VPP_DIR/extras/scripts/cross_compile_macos.sh cc
+  $ >> ./build-root/build-vpp[_debug]-native/vpp/compile_commands.json
+
+
+
+This should build vpp on MacOS
+
+
+Good luck :)
+
+.. _install_clang_format_10_0_0 :
+
+Installing clang-format 10.0.0
+------------------------------
+
+In order to install clang-format on macos :
+
+.. code-block:: bash
+
+    $ wget https://github.com/llvm/llvm-project/releases/download/llvmorg-10.0.0/clang-10.0.0.src.tar.xz
+    $ tar -xvf clang+llvm-10.0.0-x86_64-apple-darwin.tar.xz
+    $ mv clang+llvm-10.0.0-x86_64-apple-darwin /usr/local/Cellar/
+    $ sudo ln -s ../Cellar/clang+llvm-10.0.0-x86_64-apple-darwin/bin/clang-format /usr/local/bin/clang-format
+    $ sudo ln -s ../Cellar/clang+llvm-10.0.0-x86_64-apple-darwin/bin/clang-format /usr/local/bin/clang-format-10
+    $ sudo ln -s ../Cellar/clang+llvm-10.0.0-x86_64-apple-darwin/share/clang/clang-format-diff.py /usr/local/bin/clang-format-diff-10
+
+Source `Clang website <https://releases.llvm.org/download.html#git>`_
diff --git a/docs/developer/build-run-debug/gdb_examples.rst b/docs/developer/build-run-debug/gdb_examples.rst
new file mode 100644
index 00000000000..2a33f17f4da
--- /dev/null
+++ b/docs/developer/build-run-debug/gdb_examples.rst
@@ -0,0 +1,141 @@
+.. _gdb_examples:
+
+.. toctree::
+
+GDB Examples
+===============
+
+In this section we have a few useful gdb commands.
+
+Starting GDB
+----------------------------
+
+Once at the gdb prompt, VPP can be started by running the following commands:
+
+.. code-block:: console
+
+   (gdb) run -c /etc/vpp/startup.conf
+   Starting program: /scratch/vpp-master/build-root/install-vpp_debug-native/vpp/bin/vpp -c /etc/vpp/startup.conf
+    [Thread debugging using libthread_db enabled]
+    Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
+    vlib_plugin_early_init:361: plugin path /scratch/vpp-master/build-root/install-vpp_debug-native/vpp/lib/vpp_plugins:/scratch/vpp-master/build-root/install-vpp_debug-native/vpp/lib/vpp_plugins
+    ....
+
+Backtrace
+----------------------------
+
+If you encounter errors when running VPP, such as VPP terminating due to a segfault
+or abort signal, then you can run the VPP debug binary and then execute **backtrace** or **bt**.
+
+.. code-block:: console
+
+    (gdb) bt
+    #0  ip4_icmp_input (vm=0x7ffff7b89a40 <vlib_global_main>, node=0x7fffb6bb6900, frame=0x7fffb6725ac0) at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:187
+    #1  0x00007ffff78da4be in dispatch_node (vm=0x7ffff7b89a40 <vlib_global_main>, node=0x7fffb6bb    6900, type=VLIB_NODE_TYPE_INTERNAL, dispatch_state=VLIB_NODE_STATE_POLLING, frame=0x7fffb6725ac0, last_time_stamp=10581236529    65565) at /scratch/vpp-master/build-data/../src/vlib/main.c:988
+    #2  0x00007ffff78daa77 in dispatch_pending_node (vm=0x7ffff7b89a40 <vlib_global_main>, pending_frame_index=6, last_time_stamp=1058123652965565) at /scratch/vpp-master/build-data/../src/vlib/main.c:1138
+    ....
+
+Get to the GDB prompt
+---------------------------------------
+
+When VPP is running, you can get to the command prompt by pressing **CTRL+C**.
+
+Breakpoints
+---------------------------------------
+
+When at the GDB prompt, set a breakpoint by running the commands below:
+
+.. code-block:: console
+
+    (gdb) break ip4_icmp_input
+    Breakpoint 4 at 0x7ffff6b9c00b: file /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c, line 142.
+
+List the breakpoints already set:
+
+.. code-block:: console
+
+    (gdb) i b
+    Num     Type           Disp Enb Address            What
+    1       breakpoint     keep y   0x00007ffff6b9c00b in ip4_icmp_input at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
+        breakpoint already hit 3 times
+    2       breakpoint     keep y   0x00007ffff6b9c00b in ip4_icmp_input at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
+    3       breakpoint     keep y   0x00007ffff640f646 in tw_timer_expire_timers_internal_1t_3w_1024sl_ov
+        at /scratch/vpp-master/build-data/../src/vppinfra/tw_timer_template.c:775
+
+Delete a breakpoint:
+
+.. code-block:: console
+
+    (gdb) del 2
+    (gdb) i b
+    Num     Type           Disp Enb Address            What
+    1       breakpoint     keep y   0x00007ffff6b9c00b in ip4_icmp_input at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
+	breakpoint already hit 3 times
+    3       breakpoint     keep y   0x00007ffff640f646 in tw_timer_expire_timers_internal_1t_3w_1024sl_ov
+        at /scratch/vpp-master/build-data/../src/vppinfra/tw_timer_template.c:775
+
+Step/Next/List
+---------------------------------------
+
+Step through the code using (s)tep into, (n)ext, and list some lines before and after where you are with list.
+
+.. code-block:: console
+
+    Thread 1 "vpp_main" hit Breakpoint 1, ip4_icmp_input (vm=0x7ffff7b89a40 <vlib_global_main>, node=0x7fffb6bb6900, frame=0x7fffb6709480)
+        at /scratch/jdenisco/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
+    142	{
+    (gdb) n
+    143	  icmp4_main_t *im = &icmp4_main;
+    (
+    (gdb) list
+    202	      vlib_put_next_frame (vm, node, next, n_left_to_next);
+    203	    }
+    204
+    205	  return frame->n_vectors;
+    206	}
+    207
+    208	/* *INDENT-OFF* */
+    209	VLIB_REGISTER_NODE (ip4_icmp_input_node,static) = {
+    210	  .function = ip4_icmp_input,
+    211	  .name = "ip4-icmp-input",
+
+Examining Data and packets
+-----------------------------------------------
+
+To look at data and packets use e(x)amine or (p)rint.
+
+
+For example in this code look at the ip packet:
+
+.. code-block:: console
+
+    (gdb) p/x *ip0
+    $3 = {{ip_version_and_header_length = 0x45, tos = 0x0, length = 0x5400,
+    fragment_id = 0x7049, flags_and_fragment_offset = 0x40, ttl = 0x40, protocol = 0x1,
+    checksum = 0x2ddd, {{src_address = {data = {0xa, 0x0, 0x0, 0x2},
+    data_u32 = 0x200000a, as_u8 = {0xa, 0x0, 0x0, 0x2}, as_u16 = {0xa, 0x200},
+    as_u32 = 0x200000a}, dst_address = {data = {0xa, 0x0, 0x0, 0xa}, data_u32 = 0xa00000a,
+    as_u8 = {0xa, 0x0, 0x0, 0xa}, as_u16 = {0xa, 0xa00},  as_u32 = 0xa00000a}},
+    address_pair = {src = {data = {0xa, 0x0, 0x0, 0x2}, data_u32 = 0x200000a,
+    as_u8 = {0xa, 0x0, 0x0, 0x2}, as_u16 = {0xa, 0x200},  as_u32 = 0x200000a},
+    dst = {data = {0xa, 0x0, 0x0, 0xa}, data_u32 = 0xa00000a, as_u8 = {0xa, 0x0, 0x0, 0xa},
+    as_u16 = {0xa, 0xa00}, as_u32 = 0xa00000a}}}}, {checksum_data_64 =
+    {0x40704954000045, 0x200000a2ddd0140}, checksum_data_64_32 = {0xa00000a}},
+    {checksum_data_32 = {0x54000045, 0x407049, 0x2ddd0140, 0x200000a, 0xa00000a}}}
+
+Then the icmp header
+
+.. code-block:: console
+
+    (gdb) p/x *icmp0
+    $4 = {type = 0x8, code = 0x0, checksum = 0xf148}
+
+Then look at the actual bytes:
+
+.. code-block:: console
+
+    (gdb) x/50w ip0
+    0x7fde9953510e:	0x54000045	0x00407049	0x2ddd0140	0x0200000a
+    0x7fde9953511e:	0x0a00000a	0xf1480008	0x03000554	0x5b6b2e8a
+    0x7fde9953512e:	0x00000000	0x000ca99a	0x00000000	0x13121110
+    0x7fde9953513e:	0x17161514	0x1b1a1918	0x1f1e1d1c	0x23222120
diff --git a/docs/developer/build-run-debug/index.rst b/docs/developer/build-run-debug/index.rst
new file mode 100644
index 00000000000..f8bfeab0bf8
--- /dev/null
+++ b/docs/developer/build-run-debug/index.rst
@@ -0,0 +1,14 @@
+.. _build_run_debug:
+
+=======================
+Build, Run & Debug
+=======================
+
+.. toctree::
+   :maxdepth: 1
+
+   building
+   running_vpp
+   testing_vpp
+   gdb_examples
+   cross_compile_macos
diff --git a/docs/developer/build-run-debug/running_vpp.rst b/docs/developer/build-run-debug/running_vpp.rst
new file mode 100644
index 00000000000..9b33e53ec60
--- /dev/null
+++ b/docs/developer/build-run-debug/running_vpp.rst
@@ -0,0 +1,48 @@
+.. _running_vpp:
+
+.. toctree::
+
+Running VPP
+===========
+
+After building the VPP binaries, you now have several images built.
+These images are useful when you need to run VPP without installing the packages.
+For instance if you want to run VPP with GDB.
+
+Running Without GDB
+_________________________
+
+To run the VPP images that you've built without GDB, run the following commands:
+
+Running the release image:
+
+.. code-block:: console
+
+   # make run-release
+   #
+
+Running the debug image:
+
+.. code-block:: console
+
+   # make run
+   #
+
+Running With GDB
+_________________________
+
+With the following commands you can run VPP and then be dropped into the GDB prompt.
+
+Running the release image:
+
+.. code-block:: console
+
+   # make debug-release
+   (gdb)
+
+Running the debug image:
+
+.. code-block:: console
+
+   # make debug
+   (gdb)
diff --git a/docs/developer/build-run-debug/testing_vpp.rst b/docs/developer/build-run-debug/testing_vpp.rst
new file mode 100644
index 00000000000..ca9a09efb71
--- /dev/null
+++ b/docs/developer/build-run-debug/testing_vpp.rst
@@ -0,0 +1,140 @@
+Testing VPP
+===========
+
+As of this writing, the vpp source tree includes over 1,000 unit test
+vectors. Best practices prior to pushing patches for code review: make
+sure that all of the “make test” test vectors pass.
+
+We attempt to maintain the top-level “make test-help” command so that it
+accurately describes all of the “make test” options.
+
+Examples
+--------
+
+Basic test run, all test vectors, single-vpp instance, optimized image:
+
+::
+
+     $ make test
+
+10-way parallel basic test run:
+
+::
+
+     $ make TEST_JOBS=10 test
+
+Run a specific test suite (mpls, in this case):
+
+::
+
+     $ make TEST=test_mpls test
+
+Run a specific test suite, debug image, pause prior to running the test
+suite; attach to the vpp image in gdb:
+
+::
+
+     $ make TEST=xxx DEBUG=gdb test-debug
+
+Detailed Documentation
+----------------------
+
+Current “make test-help” output:
+
+::
+
+     $ make test-help
+      test                   - build and run (basic) functional tests
+      test-debug             - build and run (basic) functional tests (debug build)
+      test-all               - build and run functional and extended tests
+      test-all-debug         - build and run functional and extended tests (debug build)
+      retest                 - run functional tests
+      retest-debug           - run functional tests (debug build)
+      retest-all             - run functional and extended tests
+      retest-all-debug       - run functional and extended tests (debug build)
+      test-cov               - generate code coverage report for test framework
+      test-gcov                      - build and run functional tests (gcov build)
+      test-wipe              - wipe (temporary) files generated by unit tests
+      test-wipe-cov          - wipe code coverage report for test framework
+      test-wipe-doc          - wipe documentation for test framework
+      test-wipe-papi         - rebuild vpp_papi sources
+      test-wipe-all          - wipe (temporary) files generated by unit tests, docs, and coverage
+      test-shell             - enter shell with test environment
+      test-shell-debug       - enter shell with test environment (debug build)
+      test-checkstyle        - check PEP8 compliance for test framework
+      test-refresh-deps      - refresh the Python dependencies for the tests
+
+     Arguments controlling test runs:
+      V=[0|1|2]              - set test verbosity level
+                               0=ERROR, 1=INFO, 2=DEBUG
+      TEST_JOBS=[<n>|auto]   - use at most <n> parallel python processes for test execution, if auto, set to number of available cpus (default: 1)
+      MAX_VPP_CPUS=[<n>|auto]- use at most <n> cpus for running vpp main and worker threads, if auto, set to number of available cpus (default: auto)
+      CACHE_OUTPUT=[0|1]     - cache VPP stdout/stderr and log as one block after test finishes (default: 1)
+      FAILFAST=[0|1]         - fail fast if 1, complete all tests if 0
+      TIMEOUT=<timeout>      - fail test suite if any single test takes longer than <timeout> (in seconds) to finish (default: 600)
+      RETRIES=<n>            - retry failed tests <n> times
+      DEBUG=<type>           - set VPP debugging kind
+         DEBUG=core          - detect coredump and load it in gdb on crash
+         DEBUG=gdb           - allow easy debugging by printing VPP PID
+                               and waiting for user input before running
+                               and tearing down a testcase
+         DEBUG=gdbserver     - run gdb inside a gdb server, otherwise
+                               same as above
+         DEBUG=attach        - attach test case to already running vpp in gdb (see test-start-vpp-in-gdb)
+
+      STEP=[yes|no]          - ease debugging by stepping through a testcase
+      SANITY=[yes|no]        - perform sanity import of vpp-api/sanity vpp run before running tests (default: yes)
+      EXTENDED_TESTS=[1|y]   - used by '[re]test-all' & '[re]test-all-debug' to run extended tests
+      TEST=<filter>          - filter the set of tests:
+         by file-name        - only run tests from specified file, e.g. TEST=test_bfd selects all tests from test_bfd.py
+         by file-suffix      - same as file-name, but 'test_' is omitted e.g. TEST=bfd selects all tests from test_bfd.py
+         by wildcard         - wildcard filter is <file>.<class>.<test function>, each can be replaced by '*'
+                               e.g. TEST='test_bfd.*.*' is equivalent to above example of filter by file-name
+                                    TEST='bfd.*.*' is equivalent to above example of filter by file-suffix
+                                    TEST='bfd.BFDAPITestCase.*' selects all tests from test_bfd.py which are part of BFDAPITestCase class
+                                    TEST='bfd.BFDAPITestCase.test_add_bfd' selects a single test named test_add_bfd from test_bfd.py/BFDAPITestCase
+                                    TEST='*.*.test_add_bfd' selects all test functions named test_add_bfd from all files/classes
+
+      VARIANT=<variant>      - specify which march node variant to unit test
+                               e.g. VARIANT=skx test the skx march variants
+                               e.g. VARIANT=icl test the icl march variants
+
+      COREDUMP_SIZE=<size>   - pass <size> as unix { coredump-size <size> } argument to vpp
+                               e.g. COREDUMP_SIZE=4g
+                                    COREDUMP_SIZE=unlimited
+      COREDUMP_COMPRESS=1    - compress core files if not debugging them
+      EXTERN_TESTS=<path>    - path to out-of-tree test_<name>.py files containing test cases
+      EXTERN_PLUGINS=<path>  - path to out-of-tree plugins to be loaded by vpp under test
+      EXTERN_COV_DIR=<path>  - path to out-of-tree prefix, where source, object and .gcda files can be found for coverage report
+
+      PROFILE=1              - enable profiling of test framework via cProfile module
+      PROFILE_SORT_BY=opt    - sort profiling report by opt - consult cProfile documentation for possible values (default: cumtime)
+      PROFILE_OUTPUT=file    - output profiling info to file - use absolute path (default: stdout)
+
+      TEST_DEBUG=1           - turn on debugging of the test framework itself (expert)
+
+      SKIP_AARCH64=1         - skip tests that are failing on the ARM platorm in FD.io CI
+
+      RND_SEED=seed          - Seed RND with given seed
+
+     Starting VPP in GDB for use with DEBUG=attach:
+
+      test-start-vpp-in-gdb       - start VPP in gdb (release)
+      test-start-vpp-debug-in-gdb - start VPP in gdb (debug)
+
+     Arguments controlling VPP in GDB runs:
+
+      VPP_IN_GDB_TMP_DIR     - specify directory to run VPP IN (default: /tmp/unittest-attach-gdb)
+      VPP_IN_GDB_NO_RMDIR=0  - don't remove existing tmp dir but fail instead
+      VPP_IN_GDB_CMDLINE=1   - add 'interactive' to VPP arguments to run with command line
+
+     Creating test documentation
+      test-doc               - generate documentation for test framework
+      test-wipe-doc          - wipe documentation for test framework
+
+     Creating test code coverage report
+      test-cov               - generate code coverage report for test framework
+      test-wipe-cov          - wipe code coverage report for test framework
+
+     Verifying code-style
+      test-checkstyle        - check PEP8 compliance