Building the Media Transport Library requires three parts: building the DPDK library, building the Media Transport Library on top of DPDK, and building the sample application.
Please note that the DPDK dependency remains necessary when utilizing the XDP/kernel socket data path backend. We leverage numerous DPDK APIs, including those for CPU, memory, queues, and mbufs, to construct a highly efficient network processing implementation.
You can do the setup in two ways:
script/ folder. On Ubuntu, they do sections 1 to 3 for you. See Quick Start with the Setup Scripts.Run the scripts as your own user, from the top of the source tree. They use sudo when they install to the system.
Each script prints its options with -h.
sudo apt-get install -y git # a fresh Ubuntu may not have it yet
git clone https://github.com/OpenVisualCloud/Media-Transport-Library.git
cd Media-Transport-Library
./script/install_dependencies.sh # the build packages of section 1.1.1, Ubuntu only
./script/build_dpdk.sh # section 2: download, patch, build and install DPDK
./build.sh # section 3: build and install MTL and the sample apps
sudo ldconfig # section 3: let the loader find the new libraries
build_dpdk.sh builds the DPDK version in versions.env. It does nothing if that version is already installed. Use -f to rebuild it.
Some setups need more components. Add each component to install_dependencies.sh, which then installs its build packages too:
| Component | Packages | Build and install |
|---|---|---|
| Intel E810/E830 out-of-tree driver | ./script/install_dependencies.sh ice |
./script/build_drivers.sh --driver ice, see the E800 Series Driver Guide |
| AF_XDP data path (xdp-tools and libbpf) | ./script/install_dependencies.sh ebpf_xdp |
./script/build_ebpf_xdp.sh, see the XDP guide |
| SVT JPEG XS ST 2110-22 plugin | ./script/install_dependencies.sh jpegxs |
./script/build_jpegxs.sh, see the Plugin Guide |
| ST 2110-22 avcodec plugin | ./script/install_dependencies.sh avcodec |
./script/build_st22_avcodec_plugin.sh, see the avcodec plugin guide |
| FFmpeg with the MTL devices | ./script/install_dependencies.sh ffmpeg |
./script/build_ffmpeg_plugin.sh, see the FFmpeg plugin guide |
| GStreamer plugins | ./script/install_dependencies.sh gstreamer |
./script/build_gstreamer_plugin.sh, see the GStreamer plugin guide |
| Python binding | ./script/install_dependencies.sh python |
./script/build_python.sh, see the Python guide |
| OBS Studio plugin | ./script/install_dependencies.sh obs |
./script/build_obs_plugin.sh, see the OBS plugin guide |
Install the AF_XDP components before you run ./build.sh: MTL finds libxdp and libbpf when it is configured, and without them builds no AF_XDP backend.
Build MTL with ./build.sh before you build a plugin or the Python binding.
This section is optional. It is not the default setup. If you did the steps of the quick start above, MTL and its components are already built and installed into the system. You can skip this section.
By default, each build script installs what it builds into /usr/local, with
sudo. Use this section only when you want to keep the build out of the system.
Set MTL_INSTALL_PREFIX to the directory for MTL, and the scripts install into
that directory instead. The scripts stay in script/. Only the libraries,
programs and plugins that they build go into the directory.
The other components go into directories beside MTL_INSTALL_PREFIX, in the
same parent directory. The CI uses MTL_INSTALL_PREFIX=$PWD/.local_install/mtl,
which gives these directories:
| Script | Installs into |
|---|---|
build.sh |
.local_install/mtl |
script/build_dpdk.sh |
.local_install/dpdk |
script/build_jpegxs.sh |
.local_install/jpegxs |
script/build_ffmpeg_plugin.sh |
.local_install/ffmpeg |
script/build_gstreamer_plugin.sh |
.local_install/gstreamer/gstreamer-1.0 |
script/build_drivers.sh |
.local_install/ice/<kernel release>/<architecture>. The script only builds the .ko file. It does not install or load the driver, because the kernel cannot load a module from this directory. |
script/build_st22_avcodec_plugin.sh |
The directory in MTL_PLUGIN_PREFIX, not in MTL_INSTALL_PREFIX, for example .local_install/plugins |
For example, to install DPDK, MTL and the two ST 2110-22 plugins into .local_install:
export MTL_INSTALL_PREFIX=$PWD/.local_install/mtl
./script/build_dpdk.sh # into .local_install/dpdk
./build.sh # into .local_install/mtl
./script/build_jpegxs.sh # into .local_install/jpegxs, beside them
MTL_PLUGIN_PREFIX=$PWD/.local_install/plugins ./script/build_st22_avcodec_plugin.sh
This directory needs no root, no ldconfig and no LD_LIBRARY_PATH. Each program
and library records the location of the other libraries relative to itself, and
each .pc file points at its own location. So you can move the whole directory,
and it still runs.
.local_install/mtl/bin/nicctl.sh is part of it and uses the dpdk-devbind.py
of .local_install/dpdk. The plugin registry is .local_install/conf/kahawai.json.
Set KAHAWAI_CFG_PATH to it, see plugin.md. The registry holds absolute
paths, so it is the one part of the directory that does not move with it.
These three scripts do not read MTL_INSTALL_PREFIX yet. They always install
into the system with sudo:
| Script | Installs into | Why it cannot use the directory |
|---|---|---|
script/build_ebpf_xdp.sh |
/usr/local, and it links libxdp.pc and libbpf.pc into the pkg-config directory of the system |
build.sh finds libxdp and libbpf only in the pkg-config search path of the system. |
script/build_python.sh |
The site-packages directory of the system python3 |
The script reads the MTL headers from /usr/local/include, so it also needs MTL in the system. |
script/build_obs_plugin.sh |
The obs-plugins directory of the system libobs |
The script has no option to select a different directory. |
MTL does not need these three scripts. They add only the AF_XDP data path, the
Python binding and the OBS plugin. If you do not want them in your system, do
not run them. Without them, build.sh builds MTL without the AF_XDP backend.
.github/scripts/setup_environment.sh runs the scripts above in the correct order. Environment variables select the steps. Each variable is 0 (the default) or 1. The command below installs the packages, the patched E810/E830 driver, DPDK, and MTL:
SETUP_ENVIRONMENT=1 \
SETUP_BUILD_AND_INSTALL_DRIVERS_ICE=1 \
SETUP_BUILD_AND_INSTALL_DPDK=1 \
MTL_BUILD_AND_INSTALL=1 \
./.github/scripts/setup_environment.sh
sudo ldconfig
Leave out SETUP_BUILD_AND_INSTALL_DRIVERS_ICE=1 if your setup has no E810/E830 NIC.
SETUP_BUILD_AND_INSTALL_DPDK=1 rebuilds DPDK on each run, also when the version is already installed.
Run ./.github/scripts/setup_environment.sh -h for the list of all variables, for example SETUP_BUILD_AND_INSTALL_EBPF_XDP, PLUGIN_BUILD_AND_INSTALL_JPEGXS, or ECOSYSTEM_BUILD_AND_INSTALL_FFMPEG_PLUGIN.
The scripts do not set up the runtime: hugepages, VFs, and MtlManager. For that, refer to Running MTL.
sudo apt-get update
sudo apt-get install git gcc meson ninja-build python3 python3-pyelftools pkg-config libnuma-dev libjson-c-dev libpcap-dev libgtest-dev libgmock-dev libssl-dev systemtap-sdt-dev llvm clang flex byacc
Newer Ubuntu and Debian releases enable Python’s externally managed environment
protection (PEP 668), so prefer the distribution packages above instead of
installing pyelftools or ninja with pip.
On Ubuntu, ./script/install_dependencies.sh installs these packages from the distribution, and the SDL2 packages below.
It leaves out flex and byacc, which only section 1.2 needs.
Install below SDL2 packages if you want the display support for RxTxApp.
sudo apt-get install libsdl2-dev libsdl2-ttf-dev
sudo yum install -y dnf-plugins-core
sudo dnf config-manager --set-enabled powertools
sudo yum install git gcc gcc-c++ meson python3 python3-pip pkg-config json-c-devel libpcap-devel gtest-devel openssl-devel numactl-devel libasan systemtap-sdt-devel clang llvm-devel
sudo pip3 install pyelftools
Install below SDL2 packages if you want the display support for RxTxApp.
sudo yum install SDL2-devel
sudo yum install git gcc gcc-c++ python3 python3-pip pkg-config SDL2-devel openssl-devel numactl-devel libasan systemtap-sdt-devel
sudo pip3 install meson ninja pyelftools
RHEL 9 doesn’t provide json-c-devel libpcap-devel gtest-devel package as default, it has to build these three libs from source code, install below dependency and follow section 1.2. Build dependency from source code to build.
sudo yum install cmake flex bison autoconf
sudo pacman -Syu --needed git gcc meson python python-pyelftools pkg-config json-c libpcap gtest openssl numactl
Install below SDL2 packages if you want the display support for RxTxApp.
sudo pacman -Syu --needed sdl2 sdl2_ttf
It’s true that not all operating systems, including RHEL 9, come with all the libraries required for every software package. If you’re trying to install a software that has dependencies not provided by default by your package manager, you might need to install these dependencies manually. Skip these step if your setup has all dependencies resolved.
Refer to below commands for how to build from code.
git clone https://github.com/json-c/json-c.git -b json-c-0.16
cd json-c/
mkdir build
cd build
cmake ../
make
sudo make install
cd ../../
git clone https://github.com/the-tcpdump-group/libpcap.git -b libpcap-1.10.7
cd libpcap/
./autogen.sh
./configure
make
sudo make install
cd ..
git clone https://github.com/google/googletest.git -b v1.13.x
cd googletest/
mkdir build
cd build/
cmake ../
make
sudo make install
cd ../../
The build steps use sudo ninja install to install the build to the system. Some operating systems, including CentOS Stream and RHEL 9, do not have /usr/local/bin/ in the secure_path defaults.
Edit the file /etc/sudoers, find secure_path and append /usr/local/bin
Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin
Reboot the system to let change take effect.
Download Media Transport Library to top folder Directory
git clone https://github.com/OpenVisualCloud/Media-Transport-Library.git
export mtl_source_code=${PWD}/Media-Transport-Library
./script/build_dpdk.sh does the steps 2.1 to 2.3 in one command. It downloads the DPDK version in versions.env, applies the patches, then builds and installs DPDK.
cd $mtl_source_code
./script/build_dpdk.sh
build_dpdk.sh builds DPDK for the CPU count of the build host, at least the DPDK default of 128 (max_lcores, RTE_MAX_LCORE): an MTL lcore ID is the CPU ID, so every CPU MTL uses must be below it.
It uses at most 1024, also for a larger DPDK_MAX_LCORES: MTL supports CPU IDs 0-1023.
For a Docker or CI image that runs on a host with more CPUs than the build machine, set the count of that host:
DPDK_MAX_LCORES=512 ./script/build_dpdk.sh -f
build_dpdk.sh does nothing when the same DPDK version is installed already, so a changed DPDK_MAX_LCORES needs -f.
Build MTL again after DPDK.
Each lcore ID costs 8256 bytes of hugepage memory in every MTL mempool, as each one has a per-lcore cache: a mempool takes 1.0 MiB with the DPDK default of 128, 2.0 MiB with 256, 4.0 MiB with 512 and 8.1 MiB with 1024.
MTL creates a few mempools per port and per session, for example about 160 for 2 redundant ports with 32 TX and 32 RX sessions.
If the host has more CPUs than RTE_MAX_LCORE of the installed DPDK, MTL passes --remap-lcore-ids, as releases up to 26.09 did, and logs the DPDK_MAX_LCORES to rebuild DPDK with: each process then numbers its CPUs from 0, so MTL processes on different CPUs can claim the same lcore.
versions.env in the Media Transport Library source tree holds the DPDK version to use. Read the file to set DPDK_VER, then check out that version.
. $mtl_source_code/versions.env
git clone https://github.com/DPDK/dpdk.git
cd dpdk
git checkout v${DPDK_VER}
git switch -c v${DPDK_VER}
cd ..
Note: point $mtl_source_code to the top source code tree of Media Transport Library.
The patch folder holds one folder per DPDK version. DPDK_VER from step 2.1 selects the correct one.
Some patches in the DPDK versions 22.03 to 23.11 are symlinks to a patch of an older version.
They resolve without an extra step. If your clone is on a file system that cannot hold symlinks,
Git writes each one as a text file that holds the target path, and git am rejects it. To
convert the files, use the symlink step in the Build guide for Windows.
cd dpdk
git am $mtl_source_code/patches/dpdk/${DPDK_VER}/*.patch
An MTL lcore ID is the CPU ID, so DPDK must be built with max_lcores (RTE_MAX_LCORE) above the highest CPU ID of the host where MTL runs.
Use the CPU count of that host, at least the DPDK default of 128 and at most 1024, the most MTL supports; section 2 lists the hugepage memory it costs.
Build MTL again after DPDK.
meson setup build -Dmax_lcores=256 # the CPU count of the host, at least 128
ninja -C build
sudo ninja install -C build
cd ..
Note, please make sure libnuma is installed, confirm it from the log of meson setup build command.
Library numa found: YES
If you see below log from sudo ninja install -C build, it seems you’re encountering an issue where the ninja command isn’t recognized. This problem is likely due to the ninja executable not being in your system’s PATH, refer to ### 1.3
sudo: ninja: command not found
cd $mtl_source_code
./build.sh
sudo ldconfig
sudo ldconfig updates the cache of the runtime linker, so it finds the DPDK and MTL libraries in /usr/local. meson 0.62 and later do not run it after an install. Without it, an app fails to start with an error such as libmtl.so: cannot open shared object file.
Intel I226-V can be used with MTL, but the setup is different from Intel E810-focused environments:
igc driver for normal host networking and PTP validation.igc PMD if you plan to run MTL with DPDK backend.The script skips this step when the igc module is already installed. Otherwise, it
installs the running kernel’s module package from the configured OS repository.
igc PMD) notes from DPDK driver guidanceNo extra MTL compile-time flag is required specifically for I226-V. The key updates are in runtime setup and validation:
igc PMD and that libdpdk is installed correctly.vfio-pci binding for DPDK datapath runs (kernel igc is still fine for non-DPDK paths).Typical post-build checks for I226-V:
# verify NIC and active kernel driver
lspci -nn | grep -i -E "ethernet|intel"
# check DPDK sees the device and driver bindings
sudo dpdk-devbind.py -s
# verify PMD is present in your DPDK test binary
dpdk-testpmd --help
It may get below error caused by PKG_CONFIG_PATH path problem.
lib/meson.build:10:0: ERROR: Dependency "libdpdk" not found, tried pkgconfig
Try below command to find the pc path and add to the PKG_CONFIG_PATH env.
find / -name libdpdk.pc
export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig/:/usr/local/lib/pkgconfig/
Before build, export CC/CXX to clang, see below for example.
export CC=clang CXX=clang++
rm build -rf
./build.sh
Sometimes, you may need to create a portable package that can be used directly on other nodes. Please note that the default steps in section ### 2.3 utilize the -march=native compiler version. This generates native instructions based on local CPU features, some of which may not exist on other devices. In such scenarios, it’s necessary to specifically indicate the CPU instructions you want to support.
Below are the steps to generate a DPDK binary capable of AVX2. Set cpu_instruction_set to haswell during the DPDK meson setup stage.
cd dpdk
rm build -rf
meson setup build -Dcpu_instruction_set=haswell
ninja -C build
sudo ninja install -C build
cd ..
Next, rebuild the Media Transport Library. MTL will reuse the build flags from DPDK.
cd $mtl_source_code
rm build -rf
./build.sh
If you want to enable a AVX512 capable build, just set cpu_instruction_set to skylake-avx512:
meson setup build -Dcpu_instruction_set=skylake-avx512
Use the command below to check the cflags (march) used for the DPDK build:
pkg-config --cflags libdpdk
# below output indicate it use haswell arch
-include rte_config.h -march=haswell -msse4 -I/usr/local/include
Use below command to check the detail compiler flags of one march:
echo | gcc -dM -E - -march=haswell
In case older kernel installed on the OS throws the “Kernel header files not in any of expected locations”
and causes build errors, you can try to fix it with installation of kernel specific packet kernel-devel:
# e.g. for CentOS or RHEL
sudo yum install "kernel-devel-$(uname -r)"
or with:
# e.g. for Ubuntu
sudo apt-get install linux-headers-$(uname -r)
For older kernel version on Red Hat, the issue is that Red Hat uses vault repos. Older versions are stored in the vaults and the correct repository needs to be enabled to install the targeted version.
The exemplary location for Rocky Linux
The exemplary location for the kernel-devel package for Rocky Linux 9.3
The Linux build compiles the MTL meson projects with the hardening options below, and DPDK, libbpf, libxdp, openh264, FFmpeg, the MTL plugin of SVT-JPEG-XS and the Level Zero loader of gpu_direct with the options for C, less the warning options: openh264 and Level Zero are C++, but get no -D_GLIBCXX_ASSERTIONS.
The meson.build of each project adds them with add_project_arguments() and add_project_link_arguments(), and script/build_dpdk.sh, script/build_ebpf_xdp.sh, script/build_ffmpeg_plugin.sh, script/build_jpegxs.sh and script/install_dependencies.sh gpu_direct pass them to the dependencies they build, from hardening_flags() in script/common.sh.
In the dependency builds hardening_flags() applies the _FORTIFY_SOURCE rule of the meson projects: it adds no level when CFLAGS or CPPFLAGS set one or a sanitizer (-fsanitize=), or when the last -O of CFLAGS, then CPPFLAGS, is -O0, as b_sanitize and the meson option optimization at 0 do for the MTL projects.
MTL_HARDENING=0 builds them without the flags, and DPDK and the FFmpeg programs without PIE, for a build that sets its own; the scripts say so in a warning.
| Option | Protection |
|---|---|
-fstack-protector-strong |
Stack buffer overflow canary |
-fstack-clash-protection |
Stack clash |
-fcf-protection=full |
Intel CET shadow stack (SHSTK) and indirect branch tracking (IBT) |
-U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=3, or =2 |
Buffer overflow checks in libc calls. Level 3 needs gcc 12 or clang 9 and glibc 2.34, so gcc 11 (Ubuntu 22.04, RHEL 9) gets 2. Not added when c_args or cpp_args set a level, with the meson option optimization at 0 or plain (buildtypes debug, plain), or with b_sanitize, which the sanitizers don’t support |
-Wformat -Wformat-security -Werror=format-security |
Format string attacks |
-Wimplicit-fallthrough |
A switch case that falls through unmarked. Mark an intended one with __attribute__((fallthrough));, as clang ignores a /* fallthrough */ comment. DPDK’s headers, which use the comment, are included as system headers |
-D_GLIBCXX_ASSERTIONS |
Bounds and precondition checks in libstdc++, for the C++ programs: MtlManager, KahawaiTest, UnitTest, the gpu_direct gtest and the st22 avcodec and FFmpeg plugin tests |
-Wl,-z,relro -Wl,-z,now |
Full RELRO, a read-only GOT |
-Wl,-z,noexecstack |
Non-executable stack |
b_pie=true, and meson’s -fPIC for shared objects |
Position independent code for ASLR |
The -U_FORTIFY_SOURCE removes the level that Ubuntu gcc sets by itself, so -Werror does not stop the build on a redefinition, and the level that the toolchain applies takes its place: 3 with gcc 12 and later and with clang, 2 with gcc 11 (Ubuntu 22.04, RHEL 9, Rocky Linux 9), which cannot apply 3. A level that c_args or cpp_args already set, also through CFLAGS or CPPFLAGS, is kept.
The gcc of Rocky Linux and RHEL enables none of the compiler options by default. So the Rocky Linux 9 image build runs .github/scripts/ci/scan/check-hardening.sh on what build.sh builds there: libmtl, UnitTest, the samples, the sample plugins, MtlManager, KahawaiTest and RxTxApp. It fails on a binary without full RELRO, a non-executable stack, PIE, CET or the stack protector.
The FFmpeg 7.0 assembly is marked SHSTK only, so the build applies ecosystem/ffmpeg_plugin/7.0/0002-x86-add-Intel-CET-IBT-support.patch, which makes it IBT-correct and marks it IBT and SHSTK.
Proceed to Running MTL for further instructions.