VNFs/DPPD-PROX/README

   1 ##
   2 ## Copyright (c) 2010-2020 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, 17.08,
  28 17.11, 18.02, 18.05, 18.08, 18.11, 19.02, 19.05, 19.08, 19.11, 20.02 and
  29 20.05 20.11
  30
  31 Meson compilation
  32 -----------------
  33 Support for 'make' has been deprecated in DPDK from v20.11 onward.
  34
  35 Example: DPDK 20.11 installation with meson
  36 -------------------------------------------
  37 git clone http://dpdk.org/git/dpdk-stable
  38 git checkout 20.11
  39 meson build
  40 cd build
  41 ninja
  42 ninja install
  43 ldconfig
  44
  45 PROX meson compilation (From the root of this repo)
  46 --------------------------------------------------
  47 Depending on the distribution in use the DPDK libraries will be installed in
  48 different locations. The 'PKG_CONFIG_PATH' environment variable is used to
  49 point to the correct location.
  50
  51 For RHEL/CentOS systems:
  52 export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig
  53 meson build
  54 cd build
  55 ninja
  56
  57 Additional options can be passed to the meson build system. See the
  58 'meson_options.txt' file for possible options
  59
  60 Legacy Make compilation
  61 -----------------------
  62 The following commands assume that the following variables have been set:
  63
  64 export RTE_SDK=/path/to/dpdk
  65 export RTE_TARGET=x86_64-native-linuxapp-gcc
  66
  67 IPSec is only supported in PROX starting from DPDK 17.11
  68 It will only be compiled if CONFIG_RTE_LIBRTE_PMD_AESNI_MB is
  69 set in DPDK .config. This also requires AESNI_MULTI_BUFFER_LIB_PATH to point to
  70 the multi-buffer library which can be downloaded from
  71 <https://github.com/01org/intel-ipsec-mb>.
  72 See doc/guides/cryptodevs/aesni_mb.rst within dpdk for more details
  73
  74 Example: DPDK 17.05 installation with make
  75 ------------------------------------------
  76 git clone http://dpdk.org/git/dpdk
  77 cd dpdk
  78 git checkout v17.05
  79 make install T=$RTE_TARGET
  80
  81 PROX make compilation
  82 ----------------
  83 The Makefile with this application expects RTE_SDK to point to the
  84 root directory of DPDK (e.g. export RTE_SDK=/root/dpdk). If RTE_TARGET
  85 has not been set, x86_64-native-linuxapp-gcc will be assumed.
  86
  87 Running PROX
  88 ------------
  89 After DPDK has been set up, run make from the directory where you have
  90 extracted this application. A build directory will be created
  91 containing the PROX executable. The usage of the application is shown
  92 below. Note that this application assumes that all required ports have
  93 been bound to the DPDK provided igb_uio driver. Refer to the "Getting
  94 Started Guide - DPDK" document for more details.
  95
  96 Usage: ./build/prox [-f CONFIG_FILE] [-l LOG_FILE] [-p] [-o DISPLAY] [-v] [-a|-e] \
  97                 [-m|-s|-i] [-n] [-w DEF] [-q] [-k] [-d] [-z] [-r VAL] [-u] [-t]
  98         -f CONFIG_FILE : configuration file to load, ./prox.cfg by default
  99         -l LOG_FILE : log file name, ./prox.log by default
 100         -p : include PID in log file name if default log file is used
 101         -o DISPLAY: Set display to use, can be 'curses' (default), 'cli' or 'none'
 102         -v verbosity : initial logging verbosity
 103         -a : autostart all cores (by default)
 104         -e : don't autostart
 105         -n : Create NULL devices instead of using PCI devices, useful together with -i
 106         -m : list supported task modes and exit
 107         -s : check configuration file syntax and exit
 108         -i : check initialization sequence and exit
 109         -u : Listen on UDS /tmp/prox.sock
 110         -t : Listen on TCP port 8474
 111         -q : Pass argument to Lua interpreter, useful to define variables
 112         -w : define variable using syntax varname=value
 113              takes precedence over variables defined in CONFIG_FILE
 114         -k : Log statistics to file "stats_dump" in current directory
 115         -d : Run as daemon, the parent process will block until PROX is not initialized
 116         -z : Ignore CPU topology, implies -i
 117         -r : Change initial screen refresh rate. If set to a lower than 0.001 seconds,
 118                   screen refreshing will be disabled
 119
 120 While applications using DPDK typically rely on the core mask and the
 121 number of channels to be specified on the command line, this
 122 application is configured using a .cfg file. The core mask and number
 123 of channels is derived from this config. For example, to run the
 124 application from the source directory execute:
 125
 126   user@target:~$ ./build/prox -f ./config/nop.cfg
 127
 128 Provided example configurations
 129 -------------------------------
 130 PROX can be configured either as the SUT (System Under Test) or as the
 131 Traffic Generator. Some example configuration files are provided, both
 132 in the config directory to run PROX as a SUT, and in the gen directory
 133 to run it as a Traffic Generator.
 134 A quick description of these example configurations is provided below.
 135 Additional details are provided in the example configuration files.
 136
 137 Basic configurations, mostly used as sanity check:
 138 - config/nop.cfg
 139 - config/nop-rings.cfg
 140 - gen/nop-gen.cfg
 141
 142 Simplified BNG (Border Network Gateway) configurations, using different
 143 number of ports, with and without QoS, running on the host or in a VM:
 144 - config/bng-4ports.cfg
 145 - config/bng-8ports.cfg
 146 - config/bng-qos-4ports.cfg
 147 - config/bng-qos-8ports.cfg
 148 - config/bng-1q-4ports.cfg
 149 - config/bng-ovs-usv-4ports.cfg
 150 - config/bng-no-cpu-topology-4ports.cfg
 151 - gen/bng-4ports-gen.cfg
 152 - gen/bng-8ports-gen.cfg
 153 - gen/bng-ovs-usv-4ports-gen.cfg
 154
 155 Light-weight AFTR configurations:
 156 - config/lw_aftr.cfg
 157 - gen/lw_aftr-gen.cfg
 158