.. Copyright 2021-2024 Intel Corporation SPDX-License-Identifier: Apache-2.0 ======== 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//_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: .. code-block:: bash tdi_pipeline_builder --p4c_conf_file="" \ --tdi_pipeline_config_binary_file="" For example, .. code-block:: bash 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 ~~~~~~ .. code-block:: text 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: : Arguments ~~~~~~~~~ * ``-g GRCP_ADDR`` specifies the address of the P4Rtuntime server, in the format *:*. 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 .. code-block:: bash p4rt-ctl -g 5.5.5.5:9559 set-pipe sample.pb.bin p4Info.txt Using p4rt-ctl -------------- Set forwarding pipeline ~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash p4rt-ctl set-pipe br0 /sample.pb.bin /p4info.txt Get forwarding pipeline ~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash p4rt-ctl get-pipe SWITCH Arguments: * ``SWITCH``: Bridge name. Maps internally to device name. Example: .. code-block:: bash p4rt-ctl get-pipe br0 Add table entry (rule) to forwarding pipeline ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash p4rt-ctl add-entry br0 ipv4_host "dst_ip=1.1.1.1,action=send(10)" Delete table entry (rule) from forwarding pipeline ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash p4rt-ctl del-entry br0 ipv4_host "dst_ip=1.1.1.1" Set default table entry in forwarding pipeline ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash p4rt-ctl set-default-entry br0 ipv4_host "send(10)" Add action profile member to action selector table ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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=". Example: .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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=". Example: .. code-block:: bash p4rt-ctl delete-action-profile-member br0 ingress.as_sl3 "member_id=1" Get action profile member details for action selector table ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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=". Example: .. code-block:: bash p4rt-ctl get-action-profile-member br0 ingress.as_sl3 "member_id=1" Add action profile group entry to action selector table ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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=,reference_members=,max_size=" Example: .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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=". Example: .. code-block:: bash p4rt-ctl delete-action-profile-group br0 ingress.as_sl3 "group_id=1" Get action profile group details for action selector table ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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=". Example: .. code-block:: bash p4rt-ctl get-action-profile-group br0 ingress.as_sl3 "group_id=1" Add rule for ternary match_type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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=,index=". counter_id=0 will display value for all counters added up. For index=UNSET, all cells for specified counter_id will be displayed. Examples: .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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=,index=". Example: .. code-block:: bash p4rt-ctl reset-counter br0 ingress.ipv4_host_counter "counter_id=308545543,index=1" Get direct counter value ~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash p4rt-ctl dump-entries SWITCH [TABLE] Arguments: * ``SWITCH``: Bridge name. Maps internally to device name. * ``TABLE``: Table entry from the p4 file. Example: .. code-block:: bash p4rt-ctl dump-entries br0 Add configuration to meter table ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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: .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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=,meter_index=". Examples: .. code-block:: bash p4rt-ctl get-packet-mod-meter br0 my_control.meter1 "meter_id=2244878476,meter_index=10" Start Packet I/O ~~~~~~~~~~~~~~~~ .. code-block:: bash p4rt-ctl start-pktio SWITCH Arguments: * ``SWITCH``: Bridge name. Maps internally to device name. Examples: .. code-block:: bash 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.