DOCA Applications
This page provides an overview of the example DOCA applications implemented on top of NVIDIA® BlueField® DPU.
All of the DOCA reference applications described in this section are governed under the BSD-3 software license agreement.
DOCA applications are an educational resource provided as a guide on how to program on the NVIDIA BlueField networking platform using DOCA API.
For instructions regarding the development environment and installation, refer to the NVIDIA DOCA Developer Guide and the NVIDIA DOCA Installation Guide for Linux respectively.
For questions, comments, and feedback, please contact us at DOCA-Feedback@exchange.nvidia.com.
Installation
DOCA applications are installed under /opt/mellanox/doca/applications
with each application having its own dedicated folder. Each directory contains the source code and compilation files for the matching application.
Prerequisites
The DOCA SDK references (samples and applications) require the use of meson, with a minimal version requirement of 0.61.2. Since this version is usually more advanced than what is provided by the distribution provider, it is recommended to install meson directly through pip instead of through upstream packages:
$ sudo
pip3 install
meson==0.61.2
Compilation
As applications are shipped alongside their sources, developers may want to modify some of the code during their development process and then recompile the applications. The files required for the compilation are the following:
/opt/mellanox/doca/applications/meson.build
– main compilation file for a project that contains all the applications/opt/mellanox/doca/applications/meson_options.txt
– configuration file for the compilation process/opt/mellanox/doca/applications/<application_name>/meson.build
– application-specific compilation definitions
To recompile all the reference applications:
Move to the applications directory:
cd /opt/mellanox/doca/applications
Prepare the compilation definitions:
meson /tmp/build
Compile all the applications:
ninja -C /tmp/build
InfoThe generated applications are located under the
/tmp/build/
directory, using the following path/tmp/build/<application_name>/doca_<application_name>
.
Compilation against DOCA's SDK relies on environment variables which are automatically defined per user session upon login. For more information, please refer to section "Meson Complains About Missing Dependencies" in the NVIDIA DOCA Troubleshooting Guide.
Developer Configurations
When recompiling the applications, meson compiles them by default in "debug" mode. Therefore, the binaries would not be optimized for performance as they would include the debug symbol. For comparison, the application binaries shipped as part of DOCA's installation are compiled in "release" mode. To compile the applications in something other than debug, please consult Meson's configuration guide.
The applications also offer developers the ability to use the DOCA log's TRACE
level (DOCA_LOG_TRC
) on top of the existing DOCA log levels. Enabling the TRACE
log level during compilation activates various developer log messages left out of the release compilation. Activating the TRACE
log level may be done through enable_trace_log
in the meson_options.txt
file, or directly from the command line:
Prepare the compilation definitions to use the trace log level:
meson /tmp/build -Denable_trace_log=
true
Compile the applications:
ninja -C /tmp/build
The following table maps DOCA reference applications to the libraries they make use of.
Application Category |
Application |
Library Category |
|||||||||||
BareMetal/Virtualized Cloud |
Secure Cloud Gateway |
Cloud Storage |
Monitoring |
Streaming |
HPC |
||||||||
Network |
|||||||||||||
✔ |
|||||||||||||
✔ |
|||||||||||||
✔ |
|||||||||||||
Security |
✔ |
✔ |
|||||||||||
✔ |
|||||||||||||
✔ |
|||||||||||||
✔ |
|||||||||||||
✔ |
✔ |
||||||||||||
Data Path Acceleration |
✔ |
||||||||||||
✔ |
|||||||||||||
✔ |
|||||||||||||
Storage |
✔ |
✔ |
|||||||||||
✔ |
✔ |
||||||||||||
✔ |
✔ |
||||||||||||
HPC |
✔ |
App Shield Agent
The DOCA App Shield Agent application describes how to build secure process monitoring and is based on the DOCA APSH library, which leverages DPU capabilities such as regular expression (RXP) acceleration engine, hardware-based DMA, and more.
DMA Copy
The DOCA DMA Copy application describes how to transfer files between the DPU and the host. The application is based on the direct memory access (DMA) library, which leverages hardware acceleration for data copy for both local and remote memory.
DPA All-to-all
The DOCA DPA All-to-all application is a collective operation that allows data to be copied between multiple processes. This application is implemented using DOCA DPA, which leverages the d ata path accelerator (DPA ) inside of the BlueField-3 which offloads the copying of the data to the DPA and leaves the CPU free for other computations.
DPA L2 Reflector
The DOCA DPA L2 Reflector application uses the data path accelerator (DPA) engine to intercept network traffic and swap the source and destination MAC addresses of each packet. It is based on the FlexIO API which leverages DPU capabilities such as high-speed DPA.
East-West Overlay Encryption
The DOCA East-West Overlay Encryption application (IPsec) sets up encrypted connections between different devices and works by encrypting IP packets and authenticating the packets' originator. It is based on a strongSwan solution which is an open-source IPsec-based VPN solution.
Ethernet L2 Forwarding
The DOCA Ethernet L2 Forwarding application is a DOCA Ethernet based application that forwards traffic from a single RX port to a single TX port and vice versa, leveraging DOCA's task/event batching feature for enhanced performance.
File Compression
The DOCA File Compression application shows how to compress and decompress data using hardware acceleration and to send and receive it. The application is based on the DOCA Compress and DOCA Comm-Channel libraries.
File Integrity
The DOCA File Integrity application shows how to send and receive files in a secure way using the hardware Crypto engine. It is based on the DOCA SHA and DOCA Comm-Channel libraries.
GPU Packet Processing
The DOCA GPU Packet Processing application shows how to combine DOCA GPUNetIO, DOCA Ethernet, and DOCA Flow to manage ICMP, UDP, TCP and HTTP connections with a GPU-centric approach using CUDA kernels without involving the CPU in the main data path.
IPsec Gateway
The DOCA IPsec Gateway application demonstrates how to insert rules related to IPsec encryption and decryption based on the DOCA Flow and IPsec libraries, which leverage the DPU's hardware capability for secure network communication.
Programmable Congestion Control
The DOCA Programmable Congestion Control application, programmable congestion control, is based on the DOCA PCC library and allows users to design and implement their own congestion control algorithm, giving them good flexibility to work out an optimal solution to handle congestion in their clusters.
PSP Gateway
The DOCA PSP Gateway application demonstrates how to exchange keys between application instances and insert rules controlling PSP encryption and decryption using the DOCA Flow library.
Secure Channel
The DOCA Secure Channel application is used to establish a secure, network-independent communication channel between the host and the DPU based on the DOCA Comm Channel library.
Simple Forward VNF
The DOCA Simple Forward VNF application is a forwarding application that takes VXLAN traffic from a single RX port and transmits it on a single TX port. It is based on the DOCA Flow library which leverages DPU capabilities such as building generic execution pipes in the hardware, and more.
Switch
The DOCA Switch application is used to establish internal switching between representor ports on the DPU. It is based on the DOCA Flow library which leverages DPU capabilities such as building generic execution pipes in the hardware, and more.
UROM RDMO
The DOCA UROM RDMO application demonstrates how to execute an Active Message outside the context of the target process. It is based on the DOCA UROM (Unified Resources and Offload Manager) library as a framework to launch UROM workers on the DPU and using the UCX communication framework, which leverages the DPU's low-latency and high-bandwidth utilization of its network engine.
YARA Inspection
The DOCA YARA Inspection application describes how to build YARA rule inspection for processes and is based on the DOCA APSH library, which leverages DPU capabilities such as the regular expression (RXP) acceleration engine, hardware-based DMA, and more.