2 ## Copyright (c) 2010-2020 Intel Corporation
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
8 ## http://www.apache.org/licenses/LICENSE-2.0
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.
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...
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
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.
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
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.
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.
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
60 cd /the/path/where/you/cloned/this/repo/
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
68 Legacy DPDK make compilation
69 ----------------------------
70 Compilation with make has been supported until DPDK 20.08, and has been removed
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.
81 Configuration options can be defined, before building DPDK, by means of
82 appending lines into the config/defconfig_$RTE_TARGET file.
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.
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
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
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.
110 cd /the/path/where/you/cloned/this/repo/
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
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.
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)
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
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:
156 user@target:~$ ./build/prox -f ./config/nop.cfg
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.
167 Basic configurations, mostly used as sanity check:
169 - config/nop-rings.cfg
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
185 Light-weight AFTR configurations:
187 - gen/lw_aftr-gen.cfg