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.07, 16.11, 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, 20.05,
  29 20.08, 20.11, 21.02, 21.05, 21.08, 21.11, 22.03, 22.07, 22.11
  30
  31 DPDK meson compilation
  32 ----------------------
  33 Compilation with meson and ninja is supported since DPDK 18.02, while support
  34 for make has been removed in DPDK 20.11.
  35
  36 Example: DPDK 20.11 installation with meson
  37 -------------------------------------------
  38 cd /your/path/for/dpdk/meson/compilation/
  39 git clone http://dpdk.org/git/dpdk-stable
  40 cd dpdk-stable/
  41 git checkout 20.11
  42 meson setup build
  43 # For DPDK 21.11 and above, please run:
  44 # meson setup -Denable_driver_sdk=true build            # instead, or
  45 # meson configure build/ -Denable_driver_sdk=true       # afterwards.
  46 cd build/
  47 ninja
  48 sudo ninja install
  49 sudo ldconfig
  50
  51 PROX meson compilation
  52 ----------------------
  53 Depending on the distribution in use the DPDK libraries will be installed in
  54 different locations. The PKG_CONFIG_PATH environment variable is used to
  55 point to the correct location.
  56
  57 On RHEL/CentOS: export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig
  58 On Ubuntu:      export PKG_CONFIG_PATH=/usr/local/lib/x86_64-linux-gnu/pkgconfig
  59
  60 cd /the/path/where/you/cloned/this/repo/
  61 cd VNFs/DPPD-PROX/
  62 meson setup build
  63 # Additional options can be specified on the 'meson setup' command line, or
  64 # using 'meson configure' afterwards. See the meson_options.txt file for
  65 # possible options.
  66 ninja -C build/
  67
  68 Legacy DPDK make compilation
  69 ----------------------------
  70 Compilation with make has been supported until DPDK 20.08, and has been removed
  71 in DPDK 20.11.
  72
  73 The following commands require that the following environment variables are
  74 properly defined, as shown in the examples below:
  75 - RTE_SDK:              absolute path to the DPDK sources directory,
  76 - RTE_TARGET:           target (arch-machine-execenv-toolchain format) for
  77                         which we are building DPDK,
  78 - RTE_DEVEL_BUILD:      set it to 'n' to prevent warnings to be considered
  79                         as errors when building DPDK inside a git tree.
  80
  81 Configuration options can be defined, before building DPDK, by means of
  82 appending lines into the config/defconfig_$RTE_TARGET file.
  83
  84 For example, IPSec is supported in PROX (handle_esp.c) since DPDK 17.11,
  85 although it has not been recently verified, but it only gets compiled when
  86 CONFIG_RTE_LIBRTE_PMD_AESNI_MB=y has been defined in DPDK configuration. It also
  87 requires AESNI_MULTI_BUFFER_LIB_PATH environment variable to point to the
  88 "Multi-Buffer Crypto for IPsec" library, which can be downloaded from
  89 https://github.com/intel/intel-ipsec-mb. See doc/guides/cryptodevs/aesni_mb.rst
  90 within DPDK sources directory for more details.
  91
  92 Example: DPDK 20.05 installation with make
  93 ------------------------------------------
  94 cd /your/path/for/dpdk/make/compilation/
  95 git clone http://dpdk.org/git/dpdk
  96 cd dpdk/
  97 git checkout v20.05
  98 export RTE_SDK=$PWD
  99 export RTE_TARGET=x86_64-native-linuxapp-gcc
 100 export RTE_DEVEL_BUILD=n
 101 # Edit config/defconfig_$RTE_TARGET file to define options as needed.
 102 make config T=$RTE_TARGET O=$RTE_TARGET
 103 make O=$RTE_TARGET
 104
 105 Legacy PROX make compilation
 106 ----------------------------
 107 As explained above, PROX Makefile expects RTE_SDK to point to the DPDK sources
 108 directory. If RTE_TARGET is not set, it defaults to x86_64-native-linuxapp-gcc.
 109
 110 cd /the/path/where/you/cloned/this/repo/
 111 cd VNFs/DPPD-PROX/
 112 export RTE_SDK=/your/path/for/dpdk/make/compilation/./dpdk/
 113 export RTE_TARGET=x86_64-native-linuxapp-gcc
 114 export RTE_DEVEL_BUILD=n
 115 make
 116
 117 Running PROX
 118 ------------
 119 After DPDK has been installed and PROX has been compiled, the build subdirectory
 120 has been created and contains the PROX executable. The usage of the application
 121 is shown below. Note that this application assumes that all required ports have
 122 been bound to the DPDK provided igb_uio driver. Refer to the "Getting Started
 123 Guide" (http://doc.dpdk.org/guides/linux_gsg/ or doc/guides/linux_gsg/*.rst in
 124 DPDK sources directory) for more details.
 125
 126 Usage: ./build/prox [-f CONFIG_FILE] [-l LOG_FILE] [-p] [-o DISPLAY] [-v] [-a|-e] \
 127                 [-m|-s|-i] [-n] [-w DEF] [-q] [-k] [-d] [-z] [-r VAL] [-u] [-t]
 128         -f CONFIG_FILE : configuration file to load, ./prox.cfg by default
 129         -l LOG_FILE : log file name, ./prox.log by default
 130         -p : include PID in log file name if default log file is used
 131         -o DISPLAY: Set display to use, can be 'curses' (default), 'cli' or 'none'
 132         -v verbosity : initial logging verbosity
 133         -a : autostart all cores (by default)
 134         -e : don't autostart
 135         -n : Create NULL devices instead of using PCI devices, useful together with -i
 136         -m : list supported task modes and exit
 137         -s : check configuration file syntax and exit
 138         -i : check initialization sequence and exit
 139         -u : Listen on UDS /tmp/prox.sock
 140         -t : Listen on TCP port 8474
 141         -q : Pass argument to Lua interpreter, useful to define variables
 142         -w : define variable using syntax varname=value
 143              takes precedence over variables defined in CONFIG_FILE
 144         -k : Log statistics to file "stats_dump" in current directory
 145         -d : Run as daemon, the parent process will block until PROX is not initialized
 146         -z : Ignore CPU topology, implies -i
 147         -r : Change initial screen refresh rate. If set to a lower than 0.001 seconds,
 148                   screen refreshing will be disabled
 149
 150 While applications using DPDK typically rely on the core mask and the
 151 number of channels to be specified on the command line, this
 152 application is configured using a .cfg file. The core mask and number
 153 of channels is derived from this config. For example, to run the
 154 application from the source directory execute:
 155
 156   user@target:~$ ./build/prox -f ./config/nop.cfg
 157
 158 Provided example configurations
 159 -------------------------------
 160 PROX can be configured either as the SUT (System Under Test) or as the
 161 Traffic Generator. Some example configuration files are provided, both
 162 in the config directory to run PROX as a SUT, and in the gen directory
 163 to run it as a Traffic Generator.
 164 A quick description of these example configurations is provided below.
 165 Additional details are provided in the example configuration files.
 166
 167 Basic configurations, mostly used as sanity check:
 168 - config/nop.cfg
 169 - config/nop-rings.cfg
 170 - gen/nop-gen.cfg
 171
 172 Simplified BNG (Border Network Gateway) configurations, using different
 173 number of ports, with and without QoS, running on the host or in a VM:
 174 - config/bng-4ports.cfg
 175 - config/bng-8ports.cfg
 176 - config/bng-qos-4ports.cfg
 177 - config/bng-qos-8ports.cfg
 178 - config/bng-1q-4ports.cfg
 179 - config/bng-ovs-usv-4ports.cfg
 180 - config/bng-no-cpu-topology-4ports.cfg
 181 - gen/bng-4ports-gen.cfg
 182 - gen/bng-8ports-gen.cfg
 183 - gen/bng-ovs-usv-4ports-gen.cfg
 184
 185 Light-weight AFTR configurations:
 186 - config/lw_aftr.cfg
 187 - gen/lw_aftr-gen.cfg
 188