What can I help you with?
DOCA Documentation v3.0.0

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

Copy
Copied!
            

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 version

  • devices – Lists all configured devices on BlueField, including their ID, name, virtual devices, and the loaded DPL program name

    Note

    Virtual 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 value

  • tables – Lists the P4 tables of DPL programs loaded on BlueField, detailing their keys, actions, counters, and references to the program's source location

  • query – Lists P4 table entries, showing keys, actions, and the priority of each key set

  • graph – Generates a DPL pipeline graph using DOT language, which can be rendered with DOT-compatible visualization tools

  • hw-steering – Displays a hardware steering rules dump, providing a low-level view of hardware entries

  • debug – 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 Linux less command, making it easier to analyze large outputs. Disabling this mode may be necessary when running dpl_nspect commands 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 format

  • Flags for the dpl_nspect counters command:

    • --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 graph counters 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 the dpl_nspect_server socket address in the format [IPv4/IPv6][:port].

    Info

    For IPv6 addresses, if a port is specified, the address must be enclosed in square brackets. Examples:

    • ipv6:[2607:f8b0:400e:c00::ef]:443

    • ipv6:[::]:1234

  • This parameter is mandatory, unless the environment variable DPL_NSPECT_SERVER_ADDRESS is set with the address and port. For example:

    Copy
    Copied!
                

    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

Copy
Copied!
            

/* * 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

Copy
Copied!
            

╔════════════════════════════╦════════════════════════════════════════════════════════════════════════════════════════════╗ ║ 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

Copy
Copied!
            

╔══════╦══════════════════╦═══════════════════════════════════════════════════════════════════════╦══════════════╦════════════╦═════════════╗ ║ 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

Copy
Copied!
            

╔═════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗ ║ 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

Copy
Copied!
            

╔═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗ ║ 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

Copy
Copied!
            

╔═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗ ║ 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

Copy
Copied!
            

"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

Copy
Copied!
            

[ [ { "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

Copy
Copied!
            

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.

image-2025-4-21_16-24-12-version-1-modificationdate-1745241852223-api-v2.png

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

© Copyright 2025, NVIDIA. Last updated on May 5, 2025.