Compiling DPL Applications

This page describes how to use the NVIDIA DPL compiler to build DPL applications.

Introduction

DOCA Programming Language (DPL) sample applications serve as educational resources that demonstrate how to program on the NVIDIA BlueField networking platform (DPU or SuperNIC) using DPL.

The NVIDIA DPL compiler (nvp4c) is provided as an executable within a self-contained Docker image. This image is available to partners via the NVIDIA NGC platform. To access it, log in to NVIDIA NGC and download the latest DPL Docker containers.

Installation

For system requirements, refer to DPL Runtime Service.
For compiler installation instructions refer to the DPL Installation Guide.
For information about the development environment, refer to the DOCA Pipeline Programming Model and the DPL System Overview.

Dependencies

BlueField-3 DPU or CX-9 SuperNIC
Ubuntu 22.04 hosts (x86) or greater
A P4Runtime controller based on API version 1.4.0 or greater

Compiling Applications

The DPL compiler is provided with all its dependencies in the dpl-dev container. For details on how to obtain and install the Docker images refer to the DPL Installation Guide.

A script command, dpl nvp4c, is provided to execute the DPL compiler from the dpl-dev container:

dpl nvp4c --target [doca|doca-bf3|doca-cx9] nvp4c_args* program.p4

--target – the DPL target architecture
dplp4c_args – arguments to be passed to the compiler (e.g., program.p4)

The following example compiles hello_packet using DPL:

user@host:~/p4-samples/doca/hello_packet$ dpl nvp4c --target doca hello_packet.p4
Generating compiler output in "_out"

The following files in this example are produced in the _out directory:

File name	Description
`compiler.log`	Log of any compiler warnings or errors to the specified program
`hello_packet.dplconfig`	Binary blob, containing all the data needed for the DPL Runtime daemon to load the program
`hello_packet.p4info.txt`	P4Runtime protobuf file, in text format

Additional nvp4c specific arguments include:

--help                                  Print this help message
--version                               Print compiler version
-I path                                 Specify include path (passed to preprocessor)
-D arg=value                            Define macro (passed to preprocessor)
-U arg                                  Undefine macro (passed to preprocessor)
-E                                      Preprocess only, do not compile (prints program on stdout)
-M                                      Output `make` dependency rule only (passed to preprocessor)
-MD                                     Output `make` dependency rule to file as side effect (passed to preprocessor)
-MF file                                With -M, specify output file for dependencies (passed to preprocessor)
-MG                                     with -M, suppress errors for missing headers (passed to preprocessor)
-MP                                     with -M, add phony target for each dependency (passed to preprocessor)
-MT target                              With -M, override target of the output rule (passed to preprocessor)
-MQ target                              Like -Mt, override target but quote special characters (passed to preprocessor)
--nocpp                                 Skip preprocess, assume input file is already preprocessed.
--Wdisable[=diagnostic]                 Disable a compiler diagnostic, or disable all warnings if no diagnostic is specified.
--Winfo[=diagnostic]                    Report an info message for a compiler diagnostic.
--Wwarn[=diagnostic]                    Report a warning for a compiler diagnostic, or treat all info messages as warnings if no diagnostic is specified.
--Werror[=diagnostic]                   Report an error for a compiler diagnostic, or treat all warnings as errors if no diagnostic is specified.
--maxErrorCount errorCount              Set the maximum number of errors to display before failing.
--target target                         Compile for the specified target device.
--metrics metric1[,metric2]             Select which code metrics will be collected.
                                        Valid options: all, loc, cyclomatic, halstead, unused-code, duplicit-code,
                                        nesting-depth, header-general, header-manipulation, header-modification,
                                        match-action, parser, inlined, extern.
--odir out_directory                    Write output to out directory
--enable feature[,feature]*|--help      Enable a feature, or comma-separated list of features
--disable feature[,feature]*|--help     Disable a feature, or comma-separated list of features
-g                                      Enable debugging via dplnspect. Equivalent to --debug-mode=auto
--debug-mode debug_mode                 Enable debugging via DPLnspect. Options: extern, auto
--log filename                          [Compiler debugging] Compiler log file name
--list-pass-params                      List known pass parameters and exit
--pass-param pass.key=value             Pass parameter (repeatable). Example: --pass-param merge_adjacent_hwtables.max_merges=256
-v logLevel                             [Compiler debugging] Backend log level
-T fileLogSpec                          [Compiler debugging] Backend logging level per file

The binary <sample_name>. is created under _out/<sample_name>.dplconfig.

The P4Runtime file is created under _out/<sample_name>.p4info.txt.

Compiling Applications in Debug Mode

To enable packet debugging, you must ensure the following:

Compile your DPL program with the --debug-mode=extern flag. This enables using the debug flow.
Ensure you have at least one nv_send_debug_pkt() call in your DPL program. A debug packet will be emitted where nv_send_debug_pkt() is placed, and represents the program state at that point.
Alternatively, compile your DPL program using --debug-mode=auto (equivalent to -g).
auto automatically inserts debug points before each statement in each control's apply block, and at the end of each P4 action block. The user can still manually place calls to nv_send_debug_pkt() in a P4 action.

Packet debugging is supported for packets received from a wire port (RX direction) and for packets sent by the CPU (TX direction).

You may optionally include a cookie in your nv_send_debug_pkt() call (e.g., nv_send_debug_pkt(8w0x42)). This cookie can help distinguish between different debug extern calls and will appear in the debugging output.

If nv_send_debug_pkt() is placed in an apply block and debug-mode=auto, the user's specified debug point will override the automatic debug point.

Last updated: May 27, 2026