DOCA File Compression Application Guide

This document provides a file compression implementation on top of the NVIDIA® BlueField® DPU.

Introduction

The file compression application exhibits how to use the DOCA Compress API to compress and decompress data using hardware acceleration as well as sending and receiving it using the DOCA Comch API.

The application's logic includes both a client and a server:

Client side – the application opens a file, compresses it, and sends the checksum of the source file with the compressed data to the server
Server side – the application saves the received file in a buffer, decompresses it, and compares the received checksum with the calculated one

System Design

The file compression application client runs on the host and the server runs on the DPU.

Application Architecture

The file compression application runs on top of the DOCA Comm Channel API to send and receive the file from the host and to the DPU.

Connection is established on both sides by DOCA Comm Channel API.
Client compresses the data:When compress engine is available – submits compress job with DOCA Compress API and sends the result to the serverWhen compress engine is unavailable – compresses the data in software
Client sends the number of messages needed to send the compressed content of the file.
Client sends data segments in size of up to 4080 bytes.
Server saves the received data in a buffer and submits a decompress job.
Server sends an ACK message to the client when all parts of the file are received successfully.
Server compares the received checksum to the calculated checksum.
Server writes the decompressed data to an output file.

DOCA Libraries

This application leverages the following DOCA libraries:

Refer to their respective programming guide for more information.

Compiling the Application

Please refer to the DOCA Installation Guide for Linux for details on how to install BlueField-related software.

DOCA reference applications are installed with full source code and build instructions. This allows you to compile them as-is or modify the source code to create custom versions.

For more information about the applications as well as development and compilation tips, refer to the DOCA Reference Applications page.

The source code for the application is located in the following directory:

/opt/mellanox/doca/applications/file_compression/

Compiling All Applications

All DOCA applications are defined under a single meson project. So, by default, the compilation includes all of them.

To build all the applications together, run:

cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build

doca_file_compression is created under /tmp/build/file_compression/.

Compiling File Compression Application Only

To directly build only the file compression application:

cd /opt/mellanox/doca/applications/
meson /tmp/build -Denable_all_applications=false -Denable_file_compression=true
ninja -C /tmp/build

doca_file_compression is created under /tmp/build/file_compression/.

Alternatively, the user may set the desired flags in the meson_options.txt file instead of providing them in the compilation command line:

Edit the following flags in /opt/mellanox/doca/applications/meson_options.txt:Set enable_all_applications to falseSet enable_file_compression to true
Run the following compilation commands:
```
cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build
```
doca_file_compression is created under /tmp/build/file_compression/.

Running the Application

Application Execution

The file compression application is provided in source form. Therefore, a compilation is required before the application can be executed.

Application usage instructions:

Usage: doca_file_compression [DOCA Flags] [Program Flags]

DOCA Flags:
  -h, --help                        Print a help synopsis
  -v, --version                     Print program version information
  -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  --log-filter                      Filter logs from specific modules, separated by comma
  -j, --json <path>                 Parse command line flags from an input json file

Program Flags:
  -p, --pci-addr                    DOCA Comm Channel device PCI address
  -r, --rep-pci                     DOCA Comm Channel device representor PCI address
  -f, --file                        File to send by the client / File to write by the server
  -t, --timeout                     Application timeout for receiving file content messages, default is 5 sec

This usage printout can be printed to the command line using the -h (or --help) options:

./doca_file_compression -h

For additional information, refer to section "DOCA File Compression Application Guide | Command Line Flags".

CLI example for running the application on BlueField:
```
./doca_file_compression -p 03:00.0 -r 3b:00.0 -f received.txt
```
Both the DOCA Comm Channel device PCIe address (03:00.0) and the DOCA Comm Channel device representor PCIe address (3b:00.0) should match the addresses of the desired PCIe devices.
CLI example for running the application on the host:
```
./doca_file_compression -p 3b:00.0 -f send.txt
```
The DOCA Comm Channel device PCIe address (3b:00.0) should match the address of the desired PCIe device.

Command Line Flags

General Flags

Short Flag	Long Flag	Description
`-h`	`--help`	Prints a help synopsis and exits
`-v`	`--version`	Prints program version information and exits
`-l`	`--log-level`	Sets the numeric log level for the application: `10` – DISABLE `20` – CRITICAL `30` – ERROR `40` – WARNING `50` – INFO `60` – DEBUG `70` – TRACE (requires compilation with TRACE support)
N/A	`--sdk-log-level`	Sets the SDK numeric log level using the same 10-70 scale as above
N/A	`--log-filter`	Filters logs from specific modules (comma-separated list)
`-j`	`--json`	Parses command-line flags from a specified input JSON file

Refer to DOCA Arg Parser for more information regarding the supported flags and execution modes.

Program Flags

Short Flag	Long Flag	Description
`f`	`file`	For client – path to the file to be sent For server – path to write the file into This is a mandatory flag.
`p`	`pci-addr`	Comm Channel DOCA device PCIe address This is a mandatory flag.
`r`	`rep-pci`	Comm Channel DOCA device representor PCIe address This flag is mandatory only on the DPU.

Short Flag

Long Flag

Description

f

file

For client – path to the file to be sent
For server – path to write the file into

This is a mandatory flag.

p

pci-addr

Comm Channel DOCA device PCIe address

This is a mandatory flag.

r

rep-pci

Comm Channel DOCA device representor PCIe address

This flag is mandatory only on the DPU.

Troubleshooting

Refer to the NVIDIA BlueField Platform Software Troubleshooting Guide for any issue encountered with the compilation, installation, or execution of the DOCA applications.

Application Code Flow

Parse application argument.
1. Initialize arg parser resources and register DOCA general parameters.
  doca_argp_init();
2. Register file compression application parameters.
  register_file_compression_params();
3. Parse the arguments.
  doca_argp_start();
  1. Parse app parameters.
Set endpoint attributes.
```
set_endpoint_properties();
```
1. Set maximum message size of 4080 bytes.
2. Set maximum number of messages allowed.
Create comm channel endpoint.
```
doca_comm_channel_ep_create();
```
1. Create endpoint for client/server.
Run client/server main logic.
```
file_compression_client/server();
```
Clean up the file compression application.
```
file_compression_cleanup();
```
1. Free all application resources.
Arg parser destroy.
```
doca_argp_destroy()
```

References

/opt/mellanox/doca/applications/file_compression/

Last updated: May 27, 2026