P4 Runtime Controller

DPL applications are deployed to the NVIDIA® BlueField® networking platform (DPU or SuperNIC) via the P4Runtime API. Since DPL is derived from the P4-16 language, it is compatible with the P4Runtime specification, enabling standard runtime interaction with the compiled DPL pipeline

Introduction

The P4 Runtime shell (p4runtime_sh) is a Python-based CLI tool used to interact with this API. It is primarily used for loading DPL programs, testing match-action tables, and debugging pipeline behavior.

• Loading simple DPL programs

• Testing match-action tables

• Debugging pipeline behavior

The shell can be invoked using the launch script provided in the DPL Development container.

Basic Information and Inspection

These commands allow you to view the high-level structure of your loaded P4 program.

• Retrieves the content of p4info.txt for the currently loaded DPL program:

  Python

  p4info
  

• Lists all available tables:

  tables

• Displays information about a specific table:

  tables["<P4_TABLE_NAME>"]

• Lists all defined actions:

  actions

• Shows parameters and sizes for a specific action:

  actions["<P4_ACTION_NAME>"]

Working with P4 Table Entries

Specifying Match Keys

When creating or modifying entries, you must define the match keys. The syntax depends on the match type defined in your DPL program.

Adding Entries

To add a standard entry, you must define the table, the action, the match keys, and the action parameters.

• Regular entry:

  te = table_entry["<P4_TABLE_NAME>"](action="<P4_ACTION_NAME>")
  te.match["<MATCH_KEY_NAME>"] = "<MATCH_VALUE>"
  te.action["<PARAMETER_NAME>"] = "<PARAMETER_VALUE>"
  te.insert()

• Entry with idle timeout:

  te = table_entry["<P4_TABLE_NAME>"](action="<P4_ACTION_NAME>")
  te.match["<MATCH_KEY_NAME>"] = "<MATCH_VALUE>"
  te.action["<PARAMETER_NAME>"] = "<PARAMETER_VALUE>"
  te.idle_timeout_ns = 3000000000 # Example: 3 seconds
  te.insert()

Reading Entries

• Read a specific entry:

  te = table_entry["<P4_TABLE_NAME>"]
  te.match["<MATCH_KEY_NAME>"] = "<MATCH_VALUE>"
  te.read(lambda te: print(te))

• Read all entries in a table:

  te = table_entry["<P4_TABLE_NAME>"]
  te.is_default = False
  te.read(lambda te: print(te))

• Read time since last hit:

  Only for tables with idle-timeout enabled.

  te = table_entry["<P4_TABLE_NAME>"]
  te.time_since_last_hit.elapsed_ns = 0 # Enable reading timestamp
  te.match["<MATCH_KEY_NAME>"] = "<MATCH_VALUE>"
  te.read(lambda te: print(te))

Deleting Entries

• Delete a specific entry:

  te = table_entry["<P4_TABLE_NAME>"]
  te.match["<MATCH_KEY_NAME>"] = "<MATCH_VALUE>"
  te.delete()

• Delete all entries in a table:

  te = table_entry["<P4_TABLE_NAME>"]
  te.read(lambda te: te.delete())

Managing Default Entries

• Read default entry:

  te = table_entry["<P4_TABLE_NAME>"]
  te.is_default = True
  te.read(lambda te: print(te))

• Read default entry with counter: 

  te = table_entry["<P4_TABLE_NAME>"]
  te.is_default = True
  te.counter_data.byte_count = 0
  te.read(lambda te: print(te))

• Modify default action:

  te = table_entry["<P4_TABLE_NAME>"](action="<P4_ACTION_NAME>")
  te.is_default = True
  te.action["<PARAMETER_NAME>"] = "<PARAMETER_VALUE>"
  te.modify()

Working with Counters

Direct Counters

Direct counters are attached to specific table entries.

• List counters: direct_counters

• Read specific entry counter:

  Python

  ce = DirectCounterEntry("<P4_DIRECT_COUNTER_NAME>")
  ce.table_entry.match["<KEY_NAME>"] = "<VALUE>"
  ce.read(lambda ce: print(ce))
  

• Read default entry counter: Set ce.table_entry.is_default = True before reading.

• Clear specific counter: Set ce.packet_count = 0 and call ce.modify().

• Clear all counters:

  Python

  for dc in direct_counters:
      ce = DirectCounterEntry(dc.name)
      ce.packet_count = 0
      ce.modify()
  

Indirect Counters

Indirect counters are accessed by index.

• List counters: counters

• Read specific index:

  Python

  ce = counter_entry["<P4_INDIRECT_COUNTER_NAME>"]
  ce.index = <INDEX>
  ce.read(lambda ce: print(ce))
  

• Clear specific index: Set ce.byte_count = 0 and ce.packet_count = 0, then call ce.modify().

Working with Meters

Direct Meters

• List meters: direct_meters

• Read specific meter:

  Python

  me = DirectMeterEntry("<P4_DIRECT_METER_NAME>")
  me.table_entry.match["<KEY>"] = "<VALUE>"
  me.read(lambda me: print(me))
  

• Configure meter: Set config values (cir, cburst, pir, pburst) and call me.modify().

Indirect Meters

• List meters: meters

• Read specific index:

  Python

  me = meter_entry["<P4_INDIRECT_METER_NAME>"]
  me.index = <INDEX>
  me.read(lambda me: print(me))
  

• Clear meter: Set me.cir = 0 (and other rates) and call me.modify().

Packet I/O and Notifications

Packet In (Sniffing)

To capture packets sent from the DPL Runtime to the Controller:

packet_in.sniff(lambda m: print(m), timeout=10)

Packet Out (Sending)

To send packets from the Controller to the DPL Runtime. You typically use scapy to build the packet first.

# 1. Build packet string (using Scapy or raw bytes)
my_pkt = b'<PACKET_BYTE_STRING>' 

# 2. Send packet with metadata
# Repeat metadata args for every metadata defined in P4
packet_out(payload=my_pkt, <METADATA_NAME>="<VALUE>").send()

Idle Timeout Notifications

To receive notifications for entry timeouts (requires nv_support_timeout in DPL source):

idle_timeout_notification.sniff(lambda m: print(m), timeout=10)

Last updated: December 08, 2025