VNFs/DPPD-PROX/README

   1 ##
   2 ## Copyright (c) 2010-2017 Intel Corporation
   3 ##
   4 ## Licensed under the Apache License, Version 2.0 (the "License");
   5 ## you may not use this file except in compliance with the License.
   6 ## You may obtain a copy of the License at
   7 ##
   8 ##     http://www.apache.org/licenses/LICENSE-2.0
   9 ##
  10 ## Unless required by applicable law or agreed to in writing, software
  11 ## distributed under the License is distributed on an "AS IS" BASIS,
  12 ## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 ## See the License for the specific language governing permissions and
  14 ## limitations under the License.
  15 ##
  16
  17 Description
  18 -----------
  19 This is PROX, the Packet pROcessing eXecution engine, part of Intel(R)
  20 Data Plane Performance Demonstrators, and formerly known as DPPD-BNG.
  21 PROX is a DPDK-based application implementing Telco use-cases such as
  22 a simplified BRAS/BNG, light-weight AFTR... It also allows configuring
  23 finer grained network functions like QoS, Routing, load-balancing...
  24
  25 Compiling and running this application
  26 --------------------------------------
  27 This application supports DPDK 16.04, 16.11, 16.11.1, 17.02, 17.05 and 17.08.
  28 The following commands assume that the following variables have been set:
  29
  30 export RTE_SDK=/path/to/dpdk
  31 export RTE_TARGET=x86_64-native-linuxapp-gcc
  32
  33 Example: DPDK 17.05 installation
  34 --------------------------------
  35 git clone http://dpdk.org/git/dpdk
  36 cd dpdk
  37 git checkout v17.05
  38 make install T=$RTE_TARGET
  39
  40 PROX compilation
  41 ----------------
  42 The Makefile with this application expects RTE_SDK to point to the
  43 root directory of DPDK (e.g. export RTE_SDK=/root/dpdk). If RTE_TARGET
  44 has not been set, x86_64-native-linuxapp-gcc will be assumed.
  45
  46 Running PROX
  47 ------------
  48 After DPDK has been set up, run make from the directory where you have
  49 extracted this application. A build directory will be created
  50 containing the PROX executable. The usage of the application is shown
  51 below. Note that this application assumes that all required ports have
  52 been bound to the DPDK provided igb_uio driver. Refer to the "Getting
  53 Started Guide - DPDK" document for more details.
  54
  55 Usage: ./build/prox [-f CONFIG_FILE] [-l LOG_FILE] [-p] [-o DISPLAY] [-v] [-a|-e] \
  56                 [-m|-s|-i] [-n] [-w DEF] [-q] [-k] [-d] [-z] [-r VAL] [-u] [-t]
  57         -f CONFIG_FILE : configuration file to load, ./prox.cfg by default
  58         -l LOG_FILE : log file name, ./prox.log by default
  59         -p : include PID in log file name if default log file is used
  60         -o DISPLAY: Set display to use, can be 'curses' (default), 'cli' or 'none'
  61         -v verbosity : initial logging verbosity
  62         -a : autostart all cores (by default)
  63         -e : don't autostart
  64         -n : Create NULL devices instead of using PCI devices, useful together with -i
  65         -m : list supported task modes and exit
  66         -s : check configuration file syntax and exit
  67         -i : check initialization sequence and exit
  68         -u : Listen on UDS /tmp/prox.sock
  69         -t : Listen on TCP port 8474
  70         -q : Pass argument to Lua interpreter, useful to define variables
  71         -w : define variable using syntax varname=value
  72              takes precedence over variables defined in CONFIG_FILE
  73         -k : Log statistics to file "stats_dump" in current directory
  74         -d : Run as daemon, the parent process will block until PROX is not initialized
  75         -z : Ignore CPU topology, implies -i
  76         -r : Change initial screen refresh rate. If set to a lower than 0.001 seconds,
  77                   screen refreshing will be disabled
  78
  79 While applications using DPDK typically rely on the core mask and the
  80 number of channels to be specified on the command line, this
  81 application is configured using a .cfg file. The core mask and number
  82 of channels is derived from this config. For example, to run the
  83 application from the source directory execute:
  84
  85   user@target:~$ ./build/prox -f ./config/nop.cfg
  86
  87 Provided example configurations
  88 -------------------------------
  89 PROX can be configured either as the SUT (System Under Test) or as the
  90 Traffic Generator. Some example configuration files are provided, both
  91 in the config directory to run PROX as a SUT, and in the gen directory
  92 to run it as a Traffic Generator.
  93 A quick description of these example configurations is provided below.
  94 Additional details are provided in the example configuration files.
  95
  96 Basic configurations, mostly used as sanity check:
  97 - config/nop.cfg
  98 - config/nop-rings.cfg
  99 - gen/nop-gen.cfg
 100
 101 Simplified BNG (Border Network Gateway) configurations, using different
 102 number of ports, with and without QoS, running on the host or in a VM:
 103 - config/bng-4ports.cfg
 104 - config/bng-8ports.cfg
 105 - config/bng-qos-4ports.cfg
 106 - config/bng-qos-8ports.cfg
 107 - config/bng-1q-4ports.cfg
 108 - config/bng-ovs-usv-4ports.cfg
 109 - config/bng-no-cpu-topology-4ports.cfg
 110 - gen/bng-4ports-gen.cfg
 111 - gen/bng-8ports-gen.cfg
 112 - gen/bng-ovs-usv-4ports-gen.cfg
 113
 114 Light-weight AFTR configurations:
 115 - config/lw_aftr.cfg
 116 - gen/lw_aftr-gen.cfg
 117