DOCA SDK Documentation
DOCA SDK Documentation
Breadcrumbs

Loading DPL Applications

NVIDIA DPL programs are deployed to the NVIDIA® BlueField® networking platform (DPU or SuperNIC) using the P4Runtime API. This allows platform-independent, standards-based integration with SDN controllers.

Introduction

The DPL compiler generates a pipeline binary optimized for execution on BlueField. Pipeline loading and control—such as installing the program and populating P4 tables—are handled via the P4Runtime API, an open and well-defined interface.

The P4Runtime server, running on the BlueField device, enables a P4 Controller to:

  • Connect over gRPC

  • Set the ForwardingPipelineConfig (i.e., install the compiled DPL binary and p4info)

  • Query the device for its current pipeline config and table state

  • Maintain runtime P4 tables as defined in the DPL source

This model enables integration with open-source, proprietary, or custom-built controllers in a standardized way.

Prerequisites

Before loading a DPL application, ensure the following services and components are properly set up:

Loading the Application

A DPL application can be loaded using:

In the following example, we'll be using the P4Runtime controller bundled within the DPL Development Container.

Using p4runtime_sh.sh Script

Bash
usage: ./p4runtime_sh.sh [help] [-i <docker image>] [-a <dpl_rtd_ip:port>] -p <program_folder> -d <device ID> [OPTIONS]
For example:
./p4runtime_sh.sh -p /root/hello_packet/_out -a 192.168.1.100:9559 -d 1000

Arguments:

  • -i - The pulled DPL Development Container image.

  • -p - Directory that holds the DPL program compilation outputs (Compiling DPL Applications).

  • -a - Address of the DPL Runtime daemon and the P4Runtime port as specified in the DPL Runtime DPL Service Configuration.

  • -d – ID of the target device

  • --mount - (Optional) Additional volume to mount to the container. Can be used multiple times.

The "-i" and the "-a" arguments are only required if they were not configured in the scripts_config.sh as documented at DPL Installation Guide (Configuring Launch Scripts)

The examples below assumes that everything was pre-configured in scripts_config.sh .

Example Command

Bash
./p4runtime_sh.sh -d 1000 -p /root/hello_packet/_out

p4runtime_sh python application

After successfully loading a program, the script launches an interactive Python shell (p4runtime_sh python application) connected to the P4Runtime server on the dpl-rt-service running on the DPU. 
From here, you can inspect and manage tables entries using this tool. For more details about using the p4runtime_sh application see:

P4Runtime Optimizations

DPL table entries are added via a P4Runtime controller, which may run remotely or locally on BlueField.

  • The standard gRPC-based controller model supports ~50K rule insertions per second

  • For use cases requiring high-speed (1M+) rule insertions, NVIDIA is introducing a bulk insertion API extension to the P4Runtime protobuf specification 

    This feature is planned for future releases.

Troubleshooting

Loading a program might fail when the dpl-rt-service processes the compiled program due to various reasons (mostly configuration issues), in such cases, you might see error message like:

Bash
# ./scripts/p4runtime_sh.sh --device-id 1000 -p tables/_out/
CRITICAL:root:Error when setting config
CRITICAL:root:P4Runtime RPC error (INVALID_ARGUMENT): Error setting program: Failed creating P4 tables

Refer to the following for troubleshooting common issue:

Checkpoint

Guidance/Command

Inspect the dpl-rt-service log for more error details

There are two methods to get the dpl-rt-service log:

  1. Using the dpl_admin utility:

    Bash
    # ./scripts/dpl_admin.sh get-log-recent --number_of_lines 50

  2. Manually logging into the DPU and finding the log file at: /var/log/doca/dpl_rt_service/dpl_rtd.log

Look for the last info and error messages at the end of the log file.

Inspecting the current dpl-rt-service configurations

Using the dpl_admin utility:

Bash
# ./scripts/dpl_admin.sh config

Verify that all required ports are present with the expected IDs. The devices and ports correspond to the /etc/dpl_rt_service/devices.d/*.conf configuration file(s) on the DPU.

Inspecting the DPU Non-volatile configurations (nvconfig)

Using the dpl_admin utility:

Bash
# ./scripts/dpl_admin.sh nv-config

 Check if there are missing required firmware settings per DPL Runtime Service (Firmware Settings)

The dpl-rt-service log contains error message like:

[dpl_port_id_to_ib_port_num] Cannot find port ID (16)

This means that the DPL program refers to a port ID that does not exist in the device configuration files.

Fix the program to use the correct port ID(s), and/or update the /etc/dpl_rt_service/devices.d/*.conf configuration file(s) on the DPU.

The dpl-rt-service log contains error message like:

NV_HWS[table_process_attr:434]: Unified FDB not supported by current FW

This means that the DPU does not have a Firmware version that meets the minimum required version.

Upgrade the DOCA and/or the Firmware version on the DPU to the minimum required version as documented at DPL Runtime Service (Software Prerequisites)


Last updated: