DOCA Reference Applications

This page provides an overview of the DOCA reference applications implemented on top of NVIDIA® BlueField®.

All of the DOCA reference applications described in this section are governed under the BSD-3 software license agreement.

DOCA reference 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.

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. This version is already included as part of the packages provided by most Linux distributions, hence it is recommended to simply install it from packages:

• Ubuntu/Debian:

  Copy

  Copied!

              
  
              
  $ sudo apt install meson
          

• RHEL:

  Copy

  Copied!

              
  
              
  $ sudo yum install meson
          

In the rare case in which the version provided by the distribution is lower than the minimal required version of 0.61.2, one can install meson directly through pip instead of through packages:

            

            
$ sudo pip3 install meson==0.61.2
        

Unlike the package installation, in the case of installation through pip, users should also remember to install their compiler of choice as it won't be installed automatically.

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//meson.build – application-specific compilation definitions

To recompile all the reference applications:

1. Move to the applications directory:

   Copy

   Copied!

               
   
               
   cd /opt/mellanox/doca/applications
           

2. Prepare the compilation definitions:

   Copy

   Copied!

               
   
               
   meson /tmp/build
           

3. Compile all the applications:

   Copy

   Copied!

               
   
               
   ninja -C /tmp/build
           

   Info

   The generated applications are located under the /tmp/build/ directory, using the following path /tmp/build//doca_.

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:

1. Prepare the compilation definitions to use the trace log level:

   Copy

   Copied!

               
   
               
   meson /tmp/build -Denable_trace_log=true
           

2. Compile the applications:

   Copy

   Copied!

               
   
               
   ninja -C /tmp/build
           

The following table maps DOCA reference applications to the libraries they make use of.

App Shield Agent

The DOCA App Shield Agent reference 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 reference 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 reference 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.

East-West Overlay Encryption

The DOCA East-West Overlay Encryption reference 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 reference application 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 reference 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 reference 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 reference 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 reference 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.

NVMe Emulation

The DOCA NVMe Emulation reference application exhibits how to use the DOCA DevEmu PCI Generic API along with SPDK to emulate an NVMe PCIe function using hardware acceleration to fully emulate the storage device.

Programmable Congestion Control

The DOCA Programmable Congestion Control reference application 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 reference 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 reference 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 reference 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.

Storage Zero Copy

The DOCA Storage Zero Copy reference applications demonstrate a way to leverage hardware acceleration to implement a simple data storage solution that allows for data to be stored and retrieved efficiently without any unnecessary copying of data.

Switch

The DOCA Switch reference 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 reference 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 reference 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.