DOCA SDK Documentation
DOCA SDK Documentation
Breadcrumbs

DPL Nspect

This page describes the DPL Nspect tool, which is used to inspect DPL programs loaded onto the NVIDIA BlueField DPU.

Introduction

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

DPL Nspect Execution

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 Commands and Flags

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 on Virtual Devices

    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]. 

    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: 

    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

DPL Nspect Commands

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.

image-2025-4-21_16-24-12.png

Commands and Flags Summary

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








✔

Last updated: