DPL Nspect
This page describes the DPL Nspect tool, which is used to inspect DPL programs loaded onto the NVIDIA BlueField DPU.
DPL Nspect is a CLI tool that allows you to:
View the dynamic state of DPL program components, including tables, entries, keys, actions, and counters
Record a debug session and generate an archive that can be opened in the DPL Debugger
Dump the state of a DPL program into an archive for offline analysis
Running dpl_nspect.sh without arguments displays the basic usage information. For a more detailed usage guide, use the -h or --help arguments. This argument also provides command-specific usage details (for example, dpl_nspect.sh [command] -h).
dpl_nspect --help
usage: dpl_nspect [-h] [-v] [-ll] [-ni] [-nh] -a ADDRESS [-d DEVICE_IDS] [-t TIMEOUT] [--cacert PATH_TO_CA_CERT] [--cert PATH_TO_CERT] [--private-key PATH_TO_KEY]
[--csv | --json]
{system-info,devices,tables,query,graph,config,counters,hw-steering,debug} ...
options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-ll, --low-level Display low level internal information. (default: False)
-ni, --non-interactive
Disable interactive output mode. (default: False)
-nh, --no-hints Disable hints for further information.
You may set the DPL_NSPECT_DISABLE_HINTS environment variable instead of using this flag:
"export DPL_NSPECT_DISABLE_HINTS=1" (default: False)
-a ADDRESS, --address ADDRESS
The dpl_nspect server socket address of the form IPv4/IPv6* [address][:port]
IPv6*: To use with a port the address must be enclosed in literal square brackets.
Example: ipv6:[2607:f8b0:400e:c00::ef]:443 or ipv6:[::]:1234
The address/port can be assigned to and read from the environment variable: DPL_NSPECT_SERVER_ADDRESS. (default: None)
-d DEVICE_IDS, --device-ids DEVICE_IDS
Comma separated list of device ID's to be used, e.g. 1000,2000.
Retrieves data for all devices if not specified. (default: None)
-t TIMEOUT, --timeout TIMEOUT
[Optional] gRPC channel connectivity timeout. (default: 0)
commands:
For further info run dpl_nspect <command> -h
{system-info,devices,tables,query,graph,config,counters,hw-steering,debug}
system-info Display system information, e.g. HW Model, OS, OFED.
devices List the configured virtual devices.
tables List tables of programs loaded on the DPU.
query List table entries, keys and actions.
graph Display a graph of the Pipeline, using DOT language.
This graph can be graphically rendered using DOT renderers, such as online DOT graphics visualizer websites
config Get/Set the device configuration.
counters Display counters details and values.
hw-steering Display HW Steering rules dump.
debug Start a debug recording session.
Authentication:
Mutually inclusive arguments for secure connection using SSL authentication
--cacert PATH_TO_CA_CERT
CA certificate path for secure connections (default: None)
--cert PATH_TO_CERT Client certificate path for mutual authentication (default: None)
--private-key PATH_TO_KEY
Client private key path for mutual authentication (default: None)
Output format:
Mutually exclusive arguments for setting the command's output format.
--csv Set command output to use CSV format. (default: False)
--json Set command output to use JSON format. (default: False)
Connecting to a Host
DPL Nspect requires a connection to a local or remote host where the dpl_nspect_server is running. The host address and port can be configured using the environment variable. For example: DPL_NSPECT_SERVER_ADDRESS=127.0.0.1:9560.
Command Output
The output format of executed commands varies depending on the command. In some cases, the output can be modified using additional arguments to enable integration with automated scripts.
dpl_nspect offers various commands for interacting with the DPL program and BlueField:
system-info– Displays BlueField system information, including hardware model, OS name and version, and OFED versiondevices– Lists all configured devices on BlueField, including their ID, name, virtual devices, and the loaded DPL program nameNoteVirtual devices are software abstractions representing real or emulated hardware components. They provide a standardized interface for applications to interact with BlueField resources, regardless of the underlying physical hardware. For example:
Virtual network interfaces (VNIs) – Logical representations of physical NICs, allowing multiple virtual networks to share a single physical interface
Virtual processing units (VPUs) – Software-defined processing units within BlueField that can be allocated to applications for tasks like packet processing or security offloading
Virtual storage devices – Software-defined representations of physical storage, offering flexibility in managing and allocating storage resources
counters– Displays details and values of DPL counters, including the associated table, offset, and valuetables– Lists the P4 tables of DPL programs loaded on BlueField, detailing their keys, actions, counters, and references to the program's source locationquery– Lists P4 table entries, showing keys, actions, and the priority of each key setgraph– Generates a DPL pipeline graph using DOT language, which can be rendered with DOT-compatible visualization toolshw-steering– Displays a hardware steering rules dump, providing a low-level view of hardware entriesdebug– starts a debug session
Help Flags
To display details of dpl_nspect options usage use any of the following flags:
help,-h,--help– Displays the help message and exits
Output Control Flags
The following optional flags can be used independently to modify command output format and behavior:
-ll,--low-level(default: false) – Displays low-level internal information (DOCA HWS implementation)-ni,--non-interactive(default: false) – Disables interactive output mode. Interactive mode outputs data in chunks similar to the Linuxlesscommand, making it easier to analyze large outputs. Disabling this mode may be necessary when runningdpl_nspectcommands in automated scripts.-nh,--no-hints– Disables hints for additional information--csv(default: false) – Outputs command results in CSV format--json(default: false) – Outputs command results in JSON formatFlags for the
dpl_nspect counterscommand:--top-packets TOP_PACKETS(default: false) – Displays the top entries with the highest packet counter values--top-bytes TOP_BYTES(default: false) – Displays the top entries with the highest byte counter values
Flags for the
dpl_nspect graphcounters command:--url(default: false) – Encodes the output as a URL that can be directly pasted into a web browser for quick rendering using online visualization tools--type– Specifies the type of graph to generate
Filter Control Flags
The following flags allow filtering of data based on specific criteria:
-d DEVICE_IDS, --device_ids DEVICE_IDS(default: None) – Specifies a comma-separated list of device IDs to filter, e.g.,1000,2000. If not specified, data is retrieved for all devices.--table_ids TABLE_IDS(default:[]) – Filters results by specific table IDs--table_names TABLE_NAMES(default:[]) – Filters results by specific table names--counter-names COUNTER_NAMES(default:[]) – Filters results by specific counter names--indices INDICES(default:[]) – Filters results by specific entry indices
Control Flags for Connecting to BlueField
-a ADDRESS,--address ADDRESS– Specifies thedpl_nspect_serversocket address in the format[IPv4/IPv6][:port].InfoFor IPv6 addresses, if a port is specified, the address must be enclosed in square brackets. Examples:
ipv6:[2607:f8b0:400e:c00::ef]:443ipv6:[::]:1234
This parameter is mandatory, unless the environment variable
DPL_NSPECT_SERVER_ADDRESSis set with the address and port. For example:DPL_NSPECT_SERVER_ADDRESS=
127.0.0.1:9560--timeout TIMEOUT(default:0) – Specifies the connectivity timeout (optional)
Misc Flags
--version,-V– Displays the program's version number and exits
This section provides examples of commands and their respective outputs.
hello_packet.p4
/*
* 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_send_debug_pkt();
nv_drop();
}
action forward(bit<32> port) {
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()) {
forward_table.apply();
}
drop();
}
}
NvDocaPipeline(
nv_fixed_parser(),
hello_packet()
) main;
dpl_nspect system-info
╔════════════════════════════╦════════════════════════════════════════════════════════════════════════════════════════════╗
║ DESCRIPTION ║ VALUE ║
╠════════════════════════════╬════════════════════════════════════════════════════════════════════════════════════════════╣
║ DOCA version ║ 3.0.0053-1 ║
╠════════════════════════════╬════════════════════════════════════════════════════════════════════════════════════════════╣
║ DPL Runtime daemon version ║ Not found ║
╠════════════════════════════╬════════════════════════════════════════════════════════════════════════════════════════════╣
║ Debug Schema Version ║ Device ID: 1000, doctype: /nvp4c/devtools/base/v8, target_doctype: /nvp4c/devtools/doca/v1 ║
╠════════════════════════════╬════════════════════════════════════════════════════════════════════════════════════════════╣
║ Linux OS version ║ "Ubuntu 22.04.4 LTS" ║
╠════════════════════════════╬════════════════════════════════════════════════════════════════════════════════════════════╣
║ OFED Version ║ OFED-internal-25.04-0.4.8: ║
╠════════════════════════════╬════════════════════════════════════════════════════════════════════════════════════════════╣
║ RDMA Core Version ║ 99999P4.2410mlnx54-1.P4.119.gfd2cb7991d54 ║
╚════════════════════════════╩════════════════════════════════════════════════════════════════════════════════════════════╝
dpl_nspect devices
╔══════╦══════════════════╦═══════════════════════════════════════════════════════════════════════╦══════════════╦════════════╦═════════════╗
║ ID ║ P4 CONTROLLER ID ║ NAME PORT IB PORT REG_C0 MAC ║ PROGRAM ║ FW VERSION ║ HW MODEL ║
╠══════╬══════════════════╬═══════════════════════════════════════════════════════════════════════╬══════════════╬════════════╬═════════════╣
║ 1000 ║ 9876 ║ ens6f0np0 0 50 0x10000/0xffff0000 00:00:00:00:00:00 ║ hello_packet ║ 32.45.0364 ║ BlueField-3 ║
║ ║ ║ ║ ║ ║ ║
║ ║ ║ ens6f0npf0vf0 1 2 0x30000/0xffff0000 00:00:00:00:00:00 ║ ║ ║ ║
║ ║ ║ ║ ║ ║ ║
║ ║ ║ ens6f0npf0vf1 2 3 0x40000/0xffff0000 00:00:00:00:00:00 ║ ║ ║ ║
║ ║ ║ ║ ║ ║ ║
║ ║ ║ ens6f0npf0vf2 3 4 0x50000/0xffff0000 00:00:00:00:00:00 ║ ║ ║ ║
║ ║ ║ ║ ║ ║ ║
║ ║ ║ ens6f0npf0vf3 4 5 0x60000/0xffff0000 00:00:00:00:00:00 ║ ║ ║ ║
╚══════╩══════════════════╩═══════════════════════════════════════════════════════════════════════╩══════════════╩════════════╩═════════════╝
dpl_nspect counters
╔═════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ DEVICE: 1000, NV_COUNTER: hello_packet.hello_counter, SCOPE: hello_packet, TYPE: Pkts/Bts, SIZE: 4 ║
╠══════════╦══════════════════════════════════════════════════════════════════════════════════╦═══════════════════╣
║ IDX ║ ORIGIN ENTRY ID ║ VALUE ║
╠══════════╬══════════════════════════════════════════════════════════════════════════════════╬═══════════════════╣
║ 0 ║ hello_packet.apply ║ (0, 0) ║
╠══════════╬══════════════════════════════════════════════════════════════════════════════════╬═══════════════════╣
║ 1 ║ hello_packet.apply ║ (0, 0) ║
║ ║ ║ ║
║ ║ forward_table 3 ║ ║
╠══════════╬══════════════════════════════════════════════════════════════════════════════════╬═══════════════════╣
║ ║ INDICES IN USE: 2 ║ ║
╚══════════╩══════════════════════════════════════════════════════════════════════════════════╩═══════════════════╝
dpl_nspect tables
╔═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ DEVICE: 1000 ║
╠══════════╦════════════════════════════╦═══════════════════════════╦══════════════════════╦═════════╦═════════╦════════════════════╣
║ ID ║ TABLE ║ KEYS ║ ACTIONS ║ COUNTER ║ ENTRIES ║ SOURCE ║
╠══════════╬════════════════════════════╬═══════════════════════════╬══════════════════════╬═════════╬═════════╬════════════════════╣
║ 50144908 ║ hello_packet.forward_table ║ headers.ethernet.src_addr ║ hello_packet.drop ║ ║ 6 ║ hello_packet.p4:43 ║
║ ║ ║ ║ hello_packet.forward ║ ║ ║ ║
║ ║ ║ ║ NoAction ║ ║ ║ ║
╚══════════╩════════════════════════════╩═══════════════════════════╩══════════════════════╩═════════╩═════════╩════════════════════╝
dpl_nspect query
╔═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ DEVICE: 1000, TABLE ID: 50144908, TABLE NAME: hello_packet.forward_table, SOURCE: hello_packet.p4:43 ║
╠══════════╦══════╦════════════════════════════════════════════════════════╦═══════════════════════╦════════════════════════════════════════╣
║ ENTRY ID ║ PRIO ║ KEY TYPE VALUE MASK ║ ACTION ║ COUNTERS ║
╠══════════╬══════╬════════════════════════════════════════════════════════╬═══════════════════════╬════════════════════════════════════════╣
║ 0 ║ 0 ║ ALWAYS_HIT ║ hello_packet.forward( ║ ║
║ ║ ║ ║ port=0x3) ║ ║
╠══════════╬══════╬════════════════════════════════════════════════════════╬═══════════════════════╬════════════════════════════════════════╣
║ 1 ║ 0 ║ headers.ethernet.src_addr exact 0x1111111111 ║ hello_packet.forward( ║ ║
║ ║ ║ ║ port=0x1) ║ ║
╠══════════╬══════╬════════════════════════════════════════════════════════╬═══════════════════════╬════════════════════════════════════════╣
║ 2 ║ 0 ║ headers.ethernet.src_addr exact 0x2222222222 ║ hello_packet.forward( ║ ║
║ ║ ║ ║ port=0x2) ║ ║
╠══════════╬══════╬════════════════════════════════════════════════════════╬═══════════════════════╬════════════════════════════════════════╣
║ 3 ║ 0 ║ headers.ethernet.src_addr exact 0xdddddddddd ║ hello_packet.drop() ║ hello_packet.hello_counter[1] = (0, 0) ║
╠══════════╬══════╬════════════════════════════════════════════════════════╬═══════════════════════╬════════════════════════════════════════╣
║ 4 ║ 0 ║ headers.ethernet.src_addr exact 0xaaaaaaaaaa ║ NoAction() ║ ║
╠══════════╬══════╬════════════════════════════════════════════════════════╬═══════════════════════╬════════════════════════════════════════╣
║ 5 ║ 0 ║ headers.ethernet.src_addr exact 0xbbbbbbbbbb ║ NoAction() ║ ║
╚══════════╩══════╩════════════════════════════════════════════════════════╩═══════════════════════╩════════════════════════════════════════╝
dpl_nspect --csv tables
"DEVICE: 1000"
"ID","TABLE","KEYS","ACTIONS","COUNTER","ENTRIES","SOURCE"
"50144908","hello_packet.forward_table","headers.ethernet.src_addr","hello_packet.drop
hello_packet.forward
NoAction","","6","hello_packet.p4:43"
dpl_nspect --json tables
[
[
{
"DEVICE": 1000
},
{
"ID": 50144908,
"TABLE": "hello_packet.forward_table",
"KEYS": [
"headers.ethernet.src_addr"
],
"ACTIONS": [
"hello_packet.drop",
"hello_packet.forward",
"NoAction"
],
"COUNTER": "",
"ENTRIES": 6,
"SOURCE": {
"filename": "/tmp/programs/hello_packet.p4",
"line": 43,
"column": 11
}
}
]
]
dpl_nspect --low-level graph
Requires the --low-level flag
digraph hello_packet_pipeline {
graph [compound=true nodesep=0.1]
node [height=0 width=0]
// Legend
subgraph cluster_legend {
graph [fontsize="6pt" label=Legend]
control [label=Control color=blue fontsize="6pt" id=control shape=rectangle]
table [label=Table color=orange fontsize="6pt" id=table shape=rectangle]
ll_table [label=<<B>Low Level Table ID</B><BR/>[Origin(s)]> fontsize="6pt" id=ll_table shape=diamond]
legend_invis [height=0 id=legend_invis shape=point style=invis width=0]
ll_root_table [label=<<B>Root LL Table</B>> color=green fontsize="6pt" id=ll_root_table shape=diamond]
ll_unreachable_table [label=<<B>Unreachable LL Table</B>> color=red fontsize="6pt" id=ll_unreachable_table shape=diamond]
default_rule_invis_tail [fontsize="6pt" height=0 id=default_rule_invis_tail shape=point style=invis width=0]
default_rule_invis_head [fontsize="6pt" height=0 id=default_rule_invis_head shape=point style=invis width=0]
default_rule_invis_tail -> default_rule_invis_head [label="Default Rule" arrowsize="0.5px" fontsize="6pt" id="default_rule_invis_tail-default_rule_invis_head" style=dashed]
subgraph rank_0 {
rank=same
control [id=control]
default_rule_invis_head [id=default_rule_invis_head]
default_rule_invis_tail [id=default_rule_invis_tail]
ll_root_table [id=ll_root_table]
ll_table [id=ll_table]
ll_unreachable_table [id=ll_unreachable_table]
table [id=table]
}
}
// Pipeline Stage: main
subgraph cluster_hello_packet {
graph [color=blue label=hello_packet shape=rectangle]
legend_invis [height=0 id=legend_invis shape=point style=invis width=0]
88 [label=<<B>88</B><BR/>[hello_packet]> color=green id=88 shape=diamond]
95 [label=<<B>95</B><BR/>[hello_packet]> id=95 shape=diamond]
50 [label=<<B>50</B><BR/>[hello_packet, hello_packet.forward_table]> id=50 shape=diamond]
67 [label=<<B>67</B><BR/>[hello_packet, tbl_drop]> id=67 shape=diamond]
79 [label=<<B>79</B><BR/>[hello_packet, tbl_drop]> id=79 shape=diamond]
75 [label=<<B>75</B><BR/>[hello_packet, tbl_drop]> id=75 shape=diamond]
DROP [fontcolor=red id=DROP shape=box]
71 [label=<<B>71</B><BR/>[hello_packet, tbl_drop]> id=71 shape=diamond]
62 [label=<<B>62</B><BR/>[hello_packet, hello_packet.forward_table]> id=62 shape=diamond]
58 [label=<<B>58</B><BR/>[hello_packet, hello_packet.forward_table]> id=58 shape=diamond]
54 [label=<<B>54</B><BR/>[hello_packet, hello_packet.forward_table]> id=54 shape=diamond]
84 [label=<<B>84</B><BR/>[hello_packet]> color=red id=84 shape=diamond]
legend_invis -> 88 [id="legend_invis-88" style=invis]
88 -> 95 [id="88-95"]
95 -> 50 [id="95-50"]
50 -> 67 [id="50-67"]
67 -> 79 [id="67-79"]
79 -> 75 [id="79-75"]
79 -> DROP [id="79-DROP"]
67 -> 71 [id="67-71"]
71 -> DROP [id="71-DROP"]
50 -> 62 [id="50-62"]
62 -> 58 [id="62-58"]
62 -> DROP [id="62-DROP"]
50 -> 54 [id="50-54"]
54 -> DROP [id="54-DROP"]
95 -> 67 [id="95-67"]
84 -> DROP [id="84-DROP"]
subgraph rank_0 {
rank=same
84 [id=84]
88 [id=88]
}
subgraph rank_1 {
rank=same
95 [id=95]
DROP [id=DROP]
}
subgraph rank_2 {
rank=same
50 [id=50]
67 [id=67]
}
subgraph rank_4 {
rank=same
58 [id=58]
71 [id=71]
79 [id=79]
}
subgraph rank_5 {
rank=same
75 [id=75]
}
subgraph rank_3 {
rank=same
54 [id=54]
62 [id=62]
}
}
}
dpl_nspect --low-level graph --url
--url – generates an HTTP URL link to the graph, in dot format, rendered using GraphvizOnline.
Some command flags are universally applicable to all commands, while others are applicable to only specific commands.
The following table outlines commands and applicable flags:
system-info | devices | counters | tables | query | graph | hw-steering | debug | |
--address | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
--time-out | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
--non-interactive | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
--no-hints | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
--csv | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
--json | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
--device-ids | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
--low-level | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
--table-ids | ✔ | ✔ | ✔ | |||||
--table_names | ✔ | ✔ | ✔ | |||||
--counter-names | ✔ | |||||||
--indices | ✔ | |||||||
--top-packets | ✔ | |||||||
--top-bytes | ✔ | |||||||
--url | ✔ | |||||||
--type | ✔ | |||||||
--output-file | ✔ | |||||||
--debug-device-id | ✔ |