DOCA Applications
This page provides an overview of the example DOCA applications implemented on top of NVIDIA® BlueField® DPU.
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 application installs two directories:
bin – contains pre-built binaries alongside runtime configuration files
src – contains the source code and compilation files
The application's binary is located under /opt/mellanox/doca/applications/<application_name>/bin/doca_<application_name>.
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>/src/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
NoteThe generated applications are located under the /tmp/build/ directory, using the following path /tmp/build/<application_name>/src/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 |
✔ |
Allreduce
This application is a collective operation that allows data from many processing units to be collected and merged into a global result before being delivered to all processing units using an operator. The application is implemented using the UCX communication framework, which leverages the DPU's low-latency and high-bandwidth utilization of its network engine.
App Shield Agent
This 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
This 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
This 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
This 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
This 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.
File Compression
This 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
This 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.
Firewall
This application applies network security based on DOCA Flow gRPC and is used for remote programming of the DPU hardware. It leverages DPU capabilities such as building generic execution pipes in hardware, monitoring incoming and outgoing network traffic, and more.
GPU Packet Processing
This 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 Security Gateway
This 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.
NAT
This application, network address translation, switches packets with local IP addresses to global ones and vise versa. It is based on the DOCA Flow library which leverages DPU hardware capabilities such as building generic execution pipes in the hardware, executing specific actions on the traffic, and more.
Programmable Congestion Control
This 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.
Secure Channel
This 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
This 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
This application is used to establish internal switching between representor ports on the DPU. It is based on the the DOCA Flow library which leverages DPU capabilities such as building generic execution pipes in the hardware, and more.
YARA Inspection
This 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.