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
    Running tests:

     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-papi         - rebuild vpp_papi sources
     test-wipe-all          - wipe (temporary) files generated by unit tests, 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|n|no]  - disable cache VPP stdout/stderr and log as one block after test finishes (default: yes)
     FAILFAST=[1|y|yes]     - fail fast if 1, otherwise complete all tests
     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=[1|y|yes]         - enable stepping through a testcase (for testcase debugging)
     SANITY=[0|n|no]        - disable sanity import of vpp-api/sanity vpp run before running tests
     EXTENDED_TESTS=[1|y|yes] - 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
}
/*
 * Copyright (c) 2015 Cisco and/or its affiliates.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
  Copyright (c) 2005 Eliot Dresselhaus

  Permission is hereby granted, free of charge, to any person obtaining
  a copy of this software and associated documentation files (the
  "Software"), to deal in the Software without restriction, including
  without limitation the rights to use, copy, modify, merge, publish,
  distribute, sublicense, and/or sell copies of the Software, and to
  permit persons to whom the Software is furnished to do so, subject to
  the following conditions:

  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/

#ifndef included_fifo_h
#define included_fifo_h

#include <vppinfra/cache.h>
#include <vppinfra/error.h>	/* for ASSERT */
#include <vppinfra/vec.h>

typedef struct
{
  /* First index of valid data in fifo. */
  u32 head_index;