p4rt-ctl

This document describes how to use P4 Control Plane executables to support P4 programs.

Prerequisites

Before using tdi_pipeline_builder and p4rt-ctl, you need the artifacts generated when a P4 program is compiled.

P4 build artifacts for sample.p4:

  • sample.conf

  • p4info.txt

  • tdi.json

  • context.json

The P4 compiler (P4C) backend supports both PSA and PNA architectures. The compiler emits the pipeline name based on the architecture used in the P4 program:

  • For the PNA architecture, P4C emits the PIPELINE name as “pipe” regardless of the name specified in the P4 program.

  • For the PSA architecture, P4C emits the PIPELINE name specified in the P4 program. Currently it supports only ingress pipelines.

The pipeline name is referenced as:

  • p4_pipeline_name in /usr/share/stratum/<target>/<target>_skip_p4.conf

  • p4_pipeline_name in the sample.conf file

Networking recipe assumes pipeline name is defaulted to “pipe”. If the P4 program is defined for PSA architecture and uses a pipeline name other than “pipe”, we need to manually change the ‘pipeline name’ at all the above places to the ingress pipeline name specified in the p4 file.

To avoid this handcrafting, we recommend using the ingress pipeline name as “pipe” for all PSA programs.

tdi_pipeline_builder

tdi_pipeline_builder is an executable generated when P4 Control Plane is built. It is used to generate a protobuf-based bin file. This pb.bin contains information of tdi-config, context and config which are extracted from sample.conf which is generated via the P4 compiler.

To generate pb.bin:

tdi_pipeline_builder --p4c_conf_file="<path-to-input-sample-file.conf>" \
    --tdi_pipeline_config_binary_file="<path-to-output-file.pb.bin>"

For example,

tdi_pipeline_builder --p4c_conf_file=/home/mydir/sample.conf \
    --tdi_pipeline_config_binary_file=/home/mydir/sample.pb.bin

Important

You need to execute this command from the parent directory of relative paths mentioned in tdi-config/context/config parameters of sample.conf

p4rt-ctl Tool

p4rt-ctl is an executable generated when P4 Control Plane is built. It connects to the P4Runtime server in infrap4d via gRPC for enabling P4Runtime capabilities.

Each CLI command connects to gRPC ports opened by server and sends a protobuf based message. Refer to p4runtime.proto for more details on type of messages and services that are available for a p4runtime client.

For information on security and enabling TLS on gRPC ports, refer to guides/security-guide.md

Syntax

Usage: p4rt-ctl [OPTIONS] COMMAND [ARG...]

positional arguments:
  command               Subcommand to run

optional arguments:
  -h, --help            show this help message and exit
  -g, --grpc_addr       GRPC_ADDR P4Runtime gRPC server address
                        format: <server IP>:<port>

Arguments

  • -g GRCP_ADDR specifies the address of the P4Rtuntime server, in the format <server IP>:<port>. This is an optional parameter. The default value is 127.0.0.1:9559. If the P4Runtime server is not running locally, you can specify the address using this option.

    For example, if the server is listening on 5.5.5.5:9559, the command to set the pipeline will be

    p4rt-ctl -g 5.5.5.5:9559 set-pipe sample.pb.bin p4Info.txt

Using p4rt-ctl

Set forwarding pipeline

p4rt-ctl set-pipe SWITCH PROGRAM P4INFO

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • PROGRAM: Binary file generated by tdi_pipeline_builder.

  • P4INFO: P4Info.txt file generated by the P4 compiler.

Example:

p4rt-ctl set-pipe br0 <path>/sample.pb.bin <path>/p4info.txt

Get forwarding pipeline

p4rt-ctl get-pipe SWITCH

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

Example:

p4rt-ctl get-pipe br0

Add table entry (rule) to forwarding pipeline

p4rt-ctl add-entry SWITCH TABLE FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • TABLE: table_name present in the p4info.txt file.

  • FLOW: Parameters for the TABLE entry. Format: match_field_key=value action=action_name(value).

Example:

p4rt-ctl add-entry br0 ipv4_host "dst_ip=1.1.1.1,action=send(10)"

Delete table entry (rule) from forwarding pipeline

p4rt-ctl del-entry SWITCH TABLE KEY

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • TABLE: table_name present in p4info.txt file.

  • KEY: match_field_key parameter in TABLE. Format: match_field_key=value.

Example:

p4rt-ctl del-entry br0 ipv4_host "dst_ip=1.1.1.1"

Set default table entry in forwarding pipeline

p4rt-ctl set-default-entry SWITCH TABLE ACTION

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • TABLE: Name of a table present in the p4info.txt file.

  • ACTION: Action parameter for TABLE. Format: action_name(value).

Example:

p4rt-ctl set-default-entry br0 ipv4_host "send(10)"

Add action profile member to action selector table

add-action-profile-member SWITCH ACTION_PROFILE FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • ACTION_PROFILE: Action profile name from the p4 file.

  • FLOW: Action for the table to which ACTION_PROFILE refers. Format: “action=action_name(value),member_id=<number>”.

Example:

p4rt-ctl add-action-profile-member br0 ingress.as_sl3
         "action=ingress.send(0),member_id=1"

Delete action profile member from action selector table

p4rt-ctl delete-action-profile-member SWITCH ACTION_PROFILE FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • ACTION_PROFILE: Action profile name from the p4 file.

  • FLOW: Member ID specified when entry was added to profile. Format: “member_id=<number>”.

Example:

p4rt-ctl delete-action-profile-member br0 ingress.as_sl3 "member_id=1"

Get action profile member details for action selector table

p4rt-ctl get-action-profile-member SWITCH ACTION_PROFILE FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • ACTION_PROFILE: Action profile name from the p4 file.

  • FLOW: Member ID specified when entry was added to profile. Format: “member_id=<number>”.

Example:

p4rt-ctl get-action-profile-member br0 ingress.as_sl3 "member_id=1"

Add action profile group entry to action selector table

p4rt-ctl add-action-profile-group SWITCH ACTION_PROFILE FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • ACTION_PROFILE: Action profile name from the p4 file.

  • FLOW: Maps group with list of members. Format: “group_id=<group number>,reference_members=<member1,member2,..>,max_size=<maxsize of members this group can have>”

Example:

p4rt-ctl add-action-profile-group br0 ingress.as_sl3 "group_id=1,reference_members=(1),max_size=128"

Delete action profile group entry from action selector table

p4rt-ctl delete-action-profile-group SWITCH ACTION_PROFILE FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • ACTION_PROFILE: Action profile name from the p4 file.

  • FLOW: Group ID specified when entry was added to table. Format: “group_id=<number>”.

Example:

p4rt-ctl delete-action-profile-group br0 ingress.as_sl3 "group_id=1"

Get action profile group details for action selector table

p4rt-ctl get-action-profile-group SWITCH ACTION_PROFILE FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • ACTION_PROFILE: Action profile name from the p4 file.

  • FLOW: Group ID specified when entry was added to table. Format: “group_id=<number>”.

Example:

p4rt-ctl get-action-profile-group br0 ingress.as_sl3 "group_id=1"

Add rule for ternary match_type

p4rt-ctl add-entry SWITCH TABLE FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • TABLE: table_name present in p4info.txt file.

  • FLOW: Parameters for TABLE entry. Since we are programming a match_type ternary, we expect user to provide priority as well. ‘priority’ is a case sensitive field expected from user. Mask for ternary or WCM match field is expected in x.x.x.x format for IPv4, or a decimal or hexadecimal value. Format: “match_field_key=value,priority=value,action=action_name(value)”.

Example:

p4rt-ctl add-entry br0 filter "src_ip=192.168.15.0/255.255.255.0,priority=100,action=drop"

Delete rule for ternary match_type

p4rt-ctl del-entry SWITCH TABLE KEY

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • TABLE: table_name present in p4info.txt file.

  • KEY: match_field_key parameters specified when entry was added to TABLE. Since match_type is ternary, we expect user to provide previously configured priority as well. ‘priority’ is a case sensitive field expected from user. Mask for ternary or WCM match field is expected in x.x.x.x format for IPv4, or a decimal or hexadecimal value. Format: “match_field_key=value,priority=value”.

Example:

p4rt-ctl del-entry br0 ingress.ipv4_wcm "hdr.ipv4.dst_addr=192.168.1.0/255.255.255.0,priority=10"

Get indirect counter value

p4rt-ctl get-counter SWITCH COUNTER_TABLE COUNTER_FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • COUNTER_TABLE: Specifies counter table entry from the p4 file.

  • COUNTER_FLOW: Counter ID (generated ID by p4c; see tdi.json file) and counter table index. Format: “counter_id=<number>,index=<number>”. counter_id=0 will display value for all counters added up. For index=UNSET, all cells for specified counter_id will be displayed.

Examples:

p4rt-ctl get-counter br0 ingress.ipv4_host_counter "counter_id=308545543,index=1"

p4rt-ctl get-counter br0 ingress.ipv4_host_counter "counter_id=0,index=1"

Reset indirect counter value

p4rt-ctl reset-counter SWITCH COUNTER_TABLE COUNTER_FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • COUNTER_TABLE: counter table entry from the p4 file.

  • COUNTER_FLOW: counter ID (generated ID by p4c; see tdi.json file) and counter table index. Format: “counter_id=<number>,index=<number>”.

Example:

p4rt-ctl reset-counter br0 ingress.ipv4_host_counter "counter_id=308545543,index=1"

Get direct counter value

p4rt-ctl get-direct-counter SWITCH TABLE KEY

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • TABLE: table_name present in p4info.txt file.

  • KEY: match_field_key parameter of the TABLE. Format: match_field_key=value.

Examples:

p4rt-ctl get-direct-counter br0 my_control.e_fwd "hdrs.mac[vmeta.common.depth].da="0x000000000461",hdrs.mac[vmeta.common.depth].sa="0x9ebace98d9d3"" // Egress/Tx

p4rt-ctl get-direct-counter br0 my_control.i_fwd "hdrs.mac[vmeta.common.depth].da="0x000000000361",hdrs.mac[vmeta.common.depth].sa="0x9ebace98d9d3"" // Ingress/Rx

Get flow dump entries

p4rt-ctl dump-entries SWITCH [TABLE]

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • TABLE: Table entry from the p4 file.

Example:

p4rt-ctl dump-entries br0

Add configuration to meter table

add-meter-config SWITCH METER_TBL METER_CONFIGURATION

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • METER_TBL: Meter table.

  • METER_CONFIGURATION: Configuration for meter table.

Example:

p4rt-ctl add-meter-config br0 my_control.meter1 "meter_id=2244878476,meter_index=10,meter_config=policer_meter_prof_id=0,policer_spec_cir_unit=1,policer_spec_cbs_unit=1,policer_spec_eir_unit=1,policer_spec_ebs_unit=1,policer_spec_cir=1000,policer_spec_cbs=1500,policer_spec_eir=1000,policer_spec_ebs=1500"

Add table entry (rule) for direct meter

p4rt-ctl add-entry SWITCH TABLE FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • TABLE: table_name present in the p4info.txt file.

  • FLOW: Parameters for the TABLE entry. Format: match_field_key=value config_data=value action=action_name(value).

Example:

p4rt-ctl add-entry br0 my_control.i_fwd "hdrs.mac[vmeta.common.depth].da="0x000000000193",hdrs.mac[vmeta.common.depth].sa="0x9ebace99d1d2",config_data=policer_meter_prof_id=0,policer_spec_cir_unit=0,policer_spec_cbs_unit=1,policer_spec_eir_unit=0,policer_spec_ebs_unit=1,policer_spec_cir=100,policer_spec_cbs=1500,policer_spec_eir=100,policer_spec_ebs=1500,action=my_control.send_with_policer_meter3(17)"

Get direct meter value

p4rt-ctl get-direct-meter SWITCH TABLE KEY

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • TABLE: table_name present in p4info.txt file.

  • KEY: match_field_key parameter of the TABLE. Format: match_field_key=value.

Examples:

p4rt-ctl get-direct-meter br0 my_control.i_fwd "hdrs.mac[vmeta.common.depth].da="0x000000000193",hdrs.mac[vmeta.common.depth].sa="0x9ebace99d1d2""

Get indirect meter value

p4rt-ctl get-packet-mod-meter SWITCH METER_TABLE METER_FLOW

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

  • METER_TABLE: Specifies meter table entry from the p4 file.

  • METER_FLOW: Meter ID (generated ID by p4c; see tdi.json file) and meter table index. Format: “meter_id=<number>,meter_index=<number>”.

Examples:

p4rt-ctl get-packet-mod-meter br0 my_control.meter1 "meter_id=2244878476,meter_index=10"

Start Packet I/O

p4rt-ctl start-pktio SWITCH

Arguments:

  • SWITCH: Bridge name. Maps internally to device name.

Examples:

p4rt-ctl start-pktio br0

Known Issues

  1. SWITCH parameter specified in p4rt-ctl commands is not utilized in current releases. It accepts any kind of value.

  2. counter_id=0 in p4rt-ctl get-counter for indirect counters is not supported in current release. Flow counters index=unset or index=0 does not give cumulative byte count.

  3. Runtime validation of value for each key in p4rt-ctl is not supported.