DOCA Documentation v2.5.2 LTS

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.

Info

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:

  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/<application_name>/src/doca_<application_name>.

Note

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:

  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.

Application Category

Application

Library Category

BareMetal/Virtualized Cloud

Secure Cloud Gateway

Cloud Storage

Monitoring

Streaming

HPC

Flow

DPA

DMA

FlexIO SDK

PCC

App Shield

IPsec

SHA

Compress

Telemetry

GPUNetIO

Comm Channel

UCX

Network

GPU Packet Processing

NAT

Simple Forward VNF

Switch

Security

App Shield Agent

East-west Overlay Encryption

Firewall

IPsec Security Gateway

Secure Channel

YARA Inspection

Data Path Acceleration

DPA All-to-all

DPA L2 Reflector

PCC

Storage

DMA Copy

File Compression

File Integrity

HPC

Allreduce

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.

© Copyright 2024, NVIDIA. Last updated on Jul 10, 2024.