DPL Debugger
This section describes the DPL Debugger Tools, used to debug pipeline packets that DPL programs are processing in NVIDIA® BlueField®.
The debugger works only with DPL programs that are compiled with -g flag.
The DPL Debugger is a GUI application that can run a debug session or open a pre-recorded (through dpl_nspect debug) debug session file.
Debug session shows the flow of network packets throughout a DPL program's pipeline and lets the developer trace the details of each packet's course. See the documentation on the extern function nv_send_debug_pkt.
Running dpl_debugger.sh with no additional arguments will open the GUI application.
The pre-recorded debug session file is a tar.gz archive and is the output of a recorded debug session created with the dpl_nspect debug command.
Option 1: Specify the file to open when running the debugger from the command line.
dpl_debugger.sh hello_packet.tar.gz
Option 2: Click File → Open Debug Session File and select your file.
Running a debug session from the debugger is possible and has the advantage of processing and inspecting the packets at runtime.
Click Debug → Open Debug Session File and select your file.
Set the DPU address and port (the default port is 9560), and the connection timeout if required (0 = no timeout), and click Connect.
Select the desired device to debug and click Start
After a debug session is started from the debugger GUI application, all the debug points (i.e., calls to nv_send_debug_pkt) in the program are DISABLED by default and don't affect the pipeline of the packet. When a packet hits an enabled debug point, it is sent to the debugger, displayed, and can be injected back to the same point in the pipeline on user demand.
Enabling and disabling debug points is done the same as in traditional debugger GUI applications - open the source file of the program and click on the left margin next to a line with a call to nv_send_debug_pkt.
hello_packet.p4
The following program was used for the screen captures in this section
/*
* SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
* SPDX-License-Identifier: LicenseRef-NvidiaProprietary
*
* NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
* property and proprietary rights in and to this material, related
* documentation and any modifications thereto. Any use, reproduction,
* disclosure or distribution of this material and related documentation
* without an express license agreement from NVIDIA CORPORATION or
* its affiliates is strictly prohibited.
*/
#include <doca_model.p4>
#include <doca_headers.p4>
#include <doca_externs.p4>
#include <doca_parser.p4>
/*
* This basic application demonstrates a simple match/action pipeline using NVIDIA
* DOCA P4 Target Architecture.
* - Match on destination MAC address
* - Forward or drop the packet
*/
control hello_packet(
inout nv_headers_t headers,
in nv_standard_metadata_t std_meta,
inout nv_empty_metadata_t user_meta,
inout nv_empty_metadata_t pkt_out_meta
) {
NvCounter(4, NvCounterType.PACKETS_AND_BYTES) hello_counter;
action drop() {
hello_counter.count(1);
nv_drop();
}
action forward(bit<32> port) {
nv_send_debug_pkt();
nv_send_to_port(port);
}
table forward_table {
key = {
headers.ethernet.src_addr : exact;
}
actions = {
drop;
forward;
NoAction;
}
default_action = forward(3);
const entries = {
(48w0x001111111111) : forward(1);
(48w0x002222222222) : forward(2);
(48w0x00dddddddddd) : drop();
(48w0x00aaaaaaaaaa) : NoAction();
(48w0x00bbbbbbbbbb) : NoAction();
}
}
apply {
hello_counter.count(0);
if (headers.ipv4.isValid()) {
nv_send_debug_pkt();
forward_table.apply();
}
drop();
}
}
NvDocaPipeline(
nv_fixed_parser(),
hello_packet()
) main;
send_hello_packet
The following script was used for sending traffic
Assume port "p1" is connected via loopback to port "p0".
from scapy.all import IP, TCP, Ether, Packet, Raw, sendp
packet = (Ether(src='00:11:11:11:11:11', dst='ff:ff:ff:ff:ff:ff') /
IP() /
TCP(sport=100, dport=100, seq=1001, flags='P') /
Raw(load=b'This is a hello_packet packet payload.'))
sendp(packet, "p1", count=1)
When a packet hits an enabled debug point, it is sent to the debugger and displayed. A red icon is shown to indicate that the packet is paused by the debugger. Clicking the packet reveals the packet data, state, and pipeline. A green arrow is shown to indicate the current debug-point the packet is paused on.
To inject the packet back to the same point at the pipeline, click Debug → Continue.
Note that there could be multiple paused packets. This operation continues all currently paused packets.
In this example, the packet hits an additional breakpoint, and a new row in the "Debug Points" widget is displayed.
Continuing the packet once again causes the "Pause" icon to disappear, as there are no more debug points in the rest of the packet's pipeline.
Packet List
Displays the packets that were sent to the debugger. Selecting a packet in the list reveals the debug-points visited by the packet.
The list can be cleared by clicking File → Remove all packets.
Debug Points
Each row represents a single debug point hit. Selecting a debug point reveals the packet data, state, and pipeline at the time the packet hit the debug point.
Filter
Packets can be filtered by:
Table name
Action
Match Type
Match Value
Ingress port
Packet Size
Protocol
Click the '+' button to add a filter, and the Apply button to apply the filters.
Variables
Shows the variables defined in the program, and their respective values at the time the selected debug-point was hit.
Packet State
Shows low level variables such as registers and controller meta.
For this version, Samplers and Parser Bitmap are not supported (always zero)
Packet Dissector
Shows the parsed packet.
Hex Dump
Shows a raw hex dump of the packet.
Source Code
Source files can be opened by clicking File → Open Source File. Additionally, sources are displayed when clicking objects that have a correlation to a source location (e.g., debug points, tables, actions, etc...).
The debugger seeks the DPL source file using the search paths defined in the Settings, or by browsing manually for the file.
Pipeline
Shows the pipeline of the packet and the selected debug-point.
Parser
Shows the complete parser graph of the program, and outlines how the selected packet is parsed. The graph consists of both flex nodes which the DPL programmer instigated and static (fixed) nodes which are inherent part of the hardware.
Log
Shows the internal logs of the DPL Runtime daemon. The logs can be filtered by severity levels.
System Info
When an object with a correlation to a source location is clicked, the debugger searches in the source directories for the source file and display it.
Click File → Preferences menu and set the location of the DPL program sources.
