p4utils.utils.thrift_API module

This module is a modified version of runtime_CLI that performs control plane operations by connecting to the Thrift server running on a capable switch. The main difference between this code and the original one is that this module is an API, whereas the other is a client.

class p4utils.utils.thrift_API.Action(name, id_)

Bases: object

action_str()

num_params()

runtime_data_str()

class p4utils.utils.thrift_API.ActionProf(name, id_)

Bases: object

action_prof_str()

get_action(action_name, suffix_lookup_map)

p4utils.utils.thrift_API.BmMatchParamExact_to_str(self)

p4utils.utils.thrift_API.BmMatchParamLPM_to_str(self)

p4utils.utils.thrift_API.BmMatchParamRange_to_str(self)

p4utils.utils.thrift_API.BmMatchParamTernary_to_str(self)

p4utils.utils.thrift_API.BmMatchParamValid_to_str(self)

p4utils.utils.thrift_API.BmMatchParam_to_str(self)

exception p4utils.utils.thrift_API.CLI_FormatExploreError

Bases: Exception

class p4utils.utils.thrift_API.CounterArray(name, id_)

Bases: object

counter_str()

class p4utils.utils.thrift_API.MatchType

Bases: object

EXACT = 0

LPM = 1

RANGE = 4

TERNARY = 2

VALID = 3

static from_str(x)

static to_str(x)

class p4utils.utils.thrift_API.MeterArray(name, id_)

Bases: object

meter_str()

class p4utils.utils.thrift_API.MeterType

Bases: object

bytes = 1

static from_str(x)

packets = 0

static to_str(x)

class p4utils.utils.thrift_API.ParseVSet(name, id_)

Bases: object

parse_vset_str()

class p4utils.utils.thrift_API.PreType

Bases: object

SimplePre = 1

SimplePreLAG = 2

static from_str(x)

none = 0

static to_str(x)

class p4utils.utils.thrift_API.RegisterArray(name, id_)

Bases: object

register_str()

class p4utils.utils.thrift_API.ResType

Bases: object

action = 2

action_prof = 1

counter_array = 4

static from_str(x)

meter_array = 3

parse_vset = 6

register_array = 5

table = 0

static to_str(x)

class p4utils.utils.thrift_API.SwitchInfo

Bases: object

load_json_config(standard_client=None, json_path=None)

load_json_str(json_str, architecture_spec=None)

reset_config()

class p4utils.utils.thrift_API.Table(name, id_)

Bases: object

get_action(action_name, suffix_lookup_map)

key_str()

num_key_fields()

table_str()

class p4utils.utils.thrift_API.TableType

Bases: object

static from_str(x)

indirect = 1

indirect_ws = 2

simple = 0

static to_str(x)

class p4utils.utils.thrift_API.ThriftAPI(thrift_port, thrift_ip, pre_type, json_path=None)

Bases: object

This class implements a client that connects to a P4 switch control plane and allows to configure it. It establishes a Thrift connection with the switch server that is then used to forward configuration information.

Parameters:

• thrift_port (int) – port number the Thrift server listens on
• thrift_ip (str) – IP the Thrift server listens on
• pre_type (str) – PreType option
• json_path (str) – path to the P4 compiled JSON file (optional)

Possible values for pre_type are the following:

• simple_pre
• simple_pre_lag
• none

switch_info

object containing information about all the P4 structures present in the switch.

Type:SwitchInfo

client

Thrift client instance.

mc_client

Thrift mc client instance.

pre_type

given PreType option.

Type:str

table_entries_match_to_handle

dictionary used to associate table matches with the related handle.

Type:dict

act_prof_add_member_to_group(act_prof_name, mbr_handle, grp_handle)

Adds member to group in an action profile.

Parameters:

• act_prof_name (str) – name of the action profile
• mbr_handle (int) – member handle
• grp_handle (int) – group handle

act_prof_create_group(act_prof_name)

Adds a group to an action pofile.

Parameters:act_prof_name (str) – name of the action profile Returns:group handle. Return type:int

act_prof_create_member(act_prof_name, action_name, action_params=[])

Adds a member to an action profile.

Parameters:

• act_prof_name (str) – name of the action profile
• action_name (str) – name of the action
• action_params (list) – list of action parameters in the order they appear in the P4 code

Returns:

member handle.

Return type:

int

Note

In action_params, action parameters must be str.

act_prof_delete_group(act_prof_name, grp_handle)

Delete a group from an action profile.

Parameters:

• act_prof_name (str) – name of the action profile
• grp_handle (int) – group handle

act_prof_delete_member(act_prof_name, mbr_handle)

Deletes a member in an action profile.

Parameters:

• act_prof_name (str) – name of the action profile
• mbr_handle (int) – member handle

act_prof_dump(act_prof_name)

Displays entries in an action profile.

Parameters:act_prof_name (str) – name of the action profile

act_prof_dump_group(act_prof_name, grp_handle)

Displays some information about a group.

Parameters:

• act_prof_name (str) – name of the action profile
• grp_handle (int) – group handle

act_prof_dump_member(act_prof_name, mbr_handle)

Displays some information about a member.

Parameters:

• act_prof_name (str) – name of the action profile
• mbr_handle (int) – member handle

act_prof_modify_member(act_prof_name, action_name, mbr_handle, action_params=[])

Modifies member in an action profile.

Parameters:

• act_prof_name (str) – name of the action profile
• action_name (str) – name of the action
• mbr_handle (int) – member handle
• action_params (list) – list of action parameters in the order they appear in the P4 code

Returns:

member handle.

Return type:

int

Note

In action_params, action parameters must be str.

act_prof_remove_member_from_group(act_prof_name, mbr_handle, grp_handle)

Removes member from group in action profile.

Parameters:

• act_prof_name (str) – name of the action profile
• mbr_handle (int) – member handle
• grp_handle (int) – group handle

check_act_prof_ws(act_prof)

check_has_pre()

check_indirect(table)

check_indirect_ws(table)

counter_read(counter_name, index)

Reads counter value.

Parameters:

• counter_name (str) – name of the counter
• index (int) – index in the array of counters

Returns:

(byte_count, packet_count) where:

• byte_count is the number of bytes counted;
• packet_count is the number of bytes counted.

Return type:

tuple

counter_reset(counter_name)

Resets counter array.

Parameters:counter_name (str) – name of the counter

counter_write(counter_name, index, pkts=0, byts=0)

Write counter value.

Parameters:

• counter_name (str) – name of the counter
• index (int) – index in the array of counters (first element is at 0)
• pkts (int) – number of packets to write (default: 0)
• byts (int) – number of bytes to write (default: 0)

create_match_to_handle_dict()

dump_action_and_data(action_name, action_data)

dump_action_entry(a_entry)

dump_groups(groups)

dump_members(members)

dump_one_entry(table, entry)

dump_one_group(group)

dump_one_member(member)

get_action_profs()

get_actions()

get_counter_arrays()

get_custom_crc_calcs()

get_handle_from_match(table_name, match_keys, pop=False)

get_meter_arrays()

get_mgrp(s)

get_node_handle(s)

get_parse_vsets()

get_register_arrays()

get_res(type_name, name, res_type)

get_suffix_lookup_map()

get_tables()

static get_thrift_services(pre_type)

load_new_config_file(filename)

Loads new JSON config.

Parameters:filename (str) – path to the P4 compiled JSON file

load_table_entries_match_to_handle()

load_table_to_all_names()

mc_dump()

Dumps entries in multicast engine.

mc_mgrp_create(mgrp)

Creates multicast group.

Parameters:mgrp (int) – multicast group id Returns:multicast group handle. Return type:int

Note

The multicast group handle is equal to the multicast group id.

mc_mgrp_destroy(mgrp)

Destroys multicast group.

Parameters:mgrp (int) – multicast group id

mc_node_associate(mgrp, l1_hdl)

Associates node to multicast group.

Parameters:

• mgrp (int) – multicast group id
• l1_hdl (int) – node handle

mc_node_create(rid, ports, lags=[])

Creates multicast node.

Parameters:

• rid (int) – replication id
• ports (list) – list of port numbers
• lags (list) – list of lags

Returns:

node handle.

Return type:

int

mc_node_destroy(l1_hdl)

Destroys multicast node.

Parameters:l1_hdl (int) – node handle

mc_node_dissociate(mgrp, l1_hdl)

Dissociates node from multicast group.

Parameters:

• mgrp (int) – multicast group handle
• l1_hdl (int) – node handle

mc_node_update(l1_hdl, ports, lags=[])

Updates multicast node.

Parameters:

• l1_hdl (int) – node handle
• ports (list) – list of port numbers
• lags (list) – list of lags

Returns:

node handle.

Return type:

int

mc_set_lag_membership(lag_index, ports)

Sets lag membership of port list.

Parameters:

• lag_index (int) – lag index
• ports (list) – list of port numbers

meter_array_set_rates(meter_name, rates)

Configures rates for an entire meter array.

Parameters:

• meter_name (str) – name of the meter
• rates (list) – [(cir, cburst), (pir, pburst)]

Note

cir and pir use units/second, cbursts and pburst use units where units is bytes or packets, depending on the meter type.

meter_get_rates(meter_name, index)

Retrieves rates for a meter.

Parameters:

• meter_name (str) – name of the meter
• index (int) – index in the array of meters (first element is at 0)

Returns:

[(cir, cburst), (pir, pburst)].

Return type:

list

Note

cir and pir use units/second, cbursts and pburst use units where units is bytes or packets, depending on the meter type.

meter_set_rates(meter_name, index, rates)

Configures rates for a meter.

Parameters:

• meter_name (str) – name of the meter
• index (int) – index in the array of meters (first element is at 0)
• rates (list) – [(cir, cburst), (pir, pburst)]

Note

cir and pir use units/second, cbursts and pburst use units where units is bytes or packets, depending on the meter type.

parse_runtime_data(action, action_params)

port_add(iface_name, port_num, pcap_path='')

Adds a port to the switch (behavior depends on device manager used).

Parameters:

• iface_name (str) – interface name
• port_num (int) – port number
• pcap_path (str) – path where the .pcap files are saved (optional)

port_remove(port_num)

Removes a port from the switch (behavior depends on device manager used).

Parameters:port_num (int) – port number

ports_to_port_map_str(ports, description='port')

print_set_default(table_name, action_name, runtime_data)

print_table_add(match_key, action_name, runtime_data)

pvs_add(pvs_name, value)

Adds a value to a parser value set.

Parameters:

• pvs_name (str) – name of the parser value set
• value (int) – value to add

Warning

BMv2 will not report an error if the value already exists.

pvs_clear(pvs_name)

Removes all values from a parser value set.

Parameters:pvs_name (str) – name of the parser value set

pvs_get(pvs_name)

Retrieves all values from a parser value set.

Parameters:pvs_name (str) – name of the parser value set Returns:values of the parser value set Return type:list

Note

Values are displayed in no particular order, one per line.

pvs_remove(pvs_name, value)

Removes a value from a parser value set.

Parameters:

• pvs_name (str) – name of the parser value set
• value (int) – value to remove

Warning

BMv2 will not report an error if the value does not exist.

register_read(register_name, index=None, show=False)

Reads register value.

Parameters:

• register_name (str) – name of the register
• index (int) – index in the array of registers (if None, the whole array will be read)
• show (bool) – enable verbose output

Returns:

register value or list of values.

Return type:

int or list

register_reset(register_name)

Resets all the cells in the register array to 0.

Parameters:register_name (str) – name of the register

register_write(register_name, index, value)

Writes register value.

Parameters:

• register_name (str) – name of the register
• index (int or list) – index in the array of registers or [start_index, end_index]
• value (int) – value to write

reset_state()

Resets all state in the switch (table entries, registers, …), but P4 config is preserved.

serialize_state(filename)

Serializes the switch state and dumps it to user-specified file.

set_crc16_parameters(name, polynomial, initial_remainder, final_xor_value, reflect_data, reflect_remainder)

Changes the parameters for a custom crc16 hash.

Parameters:

• name (str) – hash name
• polynomial (int) – polynomial
• intial_remainder (int) – initial reminder
• final_xor_value (int) – final xor value
• reflect_data (bool) – reflect data or do not
• reflect_remainder (bool) – reflect remainder or do not

set_crc32_parameters(name, polynomial, initial_remainder, final_xor_value, reflect_data, reflect_remainder)

Changes the parameters for a custom crc32 hash.

Parameters:

• name (str) – name
• polynomial (int) – polynomial
• intial_remainder (int) – initial reminder
• final_xor_value (int) – final xor value
• reflect_data (bool) – reflect data or do not
• reflect_remainder (bool) – reflect remainder or do not

set_crc_parameters_common(name, polynomial, initial_remainder, final_xor_value, reflect_data, reflect_remainder, crc_width=16)

shell(line)

Runs a shell command.

show_actions()

Lists actions defined in the P4 program.

show_ports()

Shows the ports connected to the switch.

show_pvs(line)

Lists parser value sets defined in the P4 program.

show_tables()

Lists tables defined in the P4 program.

swap_configs()

Swap the 2 existing configs, need to have called load_new_config_file() before.

switch_info()

Shows some basic info about the switch.

table_add(table_name, action_name, match_keys, action_params=[], prio=0)

Adds entry to a match table.

Parameters:

• table_name (str) – name of the table
• action_name (str) – name of the action to execute
• match_keys (list) – list of matches in the order they appear in the P4 code
• action_params (list) – list of action parameters in the order they appear in the P4 code
• prio (int) – priority in ternary matches

Returns:

entry handle.

Return type:

int

Note

• In action_params and match_keys, action parameters and match keys must be str.
• A higher prio number indicates that the entry must be given higher priority when performing a table lookup.

table_clear(table_name)

Clears all entries in a match table (direct or indirect), but not the default entry.

Parameters:table_name (str) – name of the table

table_delete(table_name, entry_handle, quiet=False)

Deletes entry from a match table.

Parameters:

• table_name (str) – name of the table
• entry_handle (int) – entry handle
• quiet (bool) – disable verbose output

table_delete_match(table_name, match_keys)

Deletes entry from a table using match keys.

Parameters:

• table_name (str) – name of the table
• match_keys (list) – list of matches in the order they appear in the P4 code

Note

In match_keys, match keys must be str.

Warning

This may not work with ternary matches and priority entries.

table_dump(table_name)

Displays entries in a match-table.

Parameters:table_name (str) – name of the table

table_dump_entry(table_name, entry_handle)

Displays some information about a table entry.

Parameters:

• table_name (str) – name of the table
• entry_handle (int) – entry handle

table_dump_entry_from_key(table_name, match_keys, prio=0)

Displays some information about a table entry using match keys.

Parameters:

• table_name (str) – name of the table
• match_keys (list) – list of matches in the order they appear in the P4 code
• prio (int) – priority in ternary match

Note

In match_keys, match keys must be str.

table_info(table_name)

Shows info about a table.

Parameters:table_name (str) – name of the table

table_modify(table_name, action_name, entry_handle, action_params=[])

Modifies entry of a match table.

Parameters:

• table_name (str) – name of the table
• action_name (str) – name of the action
• entry_handle (int) – entry handle
• action_params (list) – list of action parameters in the order they appear in the P4 code

Returns:

entry handle.

Return type:

int

Note

In action_params, action parameters must be str.

table_modify_match(table_name, action_name, match_keys, action_params=[])

Modifies entry of a match table using match keys.

Parameters:

• table_name (str) – name of the table
• action_name (str) – name of the action
• match_keys (list) – list of matches in the order they appear in the P4 code
• action_params (list) – list of action parameters in the order they appear in the P4 code

Returns:

entry handle.

Return type:

int

Note

In action_params, action parameters must be str.

table_num_entries(table_name)

Returns the number of entries in a match table (direct or indirect).

Parameters:table_name (str) – name of the table Returns:the number of entries in a table. Return type:int

table_reset_default(table_name)

Resets default entry for a match table.

Parameters:table_name (str) – name of the table

table_set_default(table_name, action_name, action_params=[])

Sets default action for a match table.

Parameters:

• table_name (str) – name of the table
• action_name (str) – name of the default action
• action_params (list) – list of parameters for the default action

Note

In action_params, action parameters must be str.

table_set_timeout(table_name, entry_handle, timeout_ms)

Sets a timeout in ms for a given entry; the table has to support timeouts.

Parameters:

• table_name (str) – name of the table
• entry_handle (int) – entry handle
• timeout_ms (int) – entry timeout in ms

table_show_actions(table_name)

Lists one table’s actions as per the P4 program.

Parameters:table_name (str) – name of the table

write_config_to_file(filename)

Retrieves the JSON config currently used by the switch and dumps it to user-specified file.

exception p4utils.utils.thrift_API.UIn_BadIPv4Error

Bases: p4utils.utils.thrift_API.UIn_Error

exception p4utils.utils.thrift_API.UIn_BadIPv6Error

Bases: p4utils.utils.thrift_API.UIn_Error

exception p4utils.utils.thrift_API.UIn_BadMacError

Bases: p4utils.utils.thrift_API.UIn_Error

exception p4utils.utils.thrift_API.UIn_BadParamError(info='')

Bases: p4utils.utils.thrift_API.UIn_Error

exception p4utils.utils.thrift_API.UIn_Error(info='')

Bases: Exception

exception p4utils.utils.thrift_API.UIn_MatchKeyError(info='')

Bases: p4utils.utils.thrift_API.UIn_Error

exception p4utils.utils.thrift_API.UIn_ResourceError(res_type, name)

Bases: p4utils.utils.thrift_API.UIn_Error

exception p4utils.utils.thrift_API.UIn_RuntimeDataError(info='')

Bases: p4utils.utils.thrift_API.UIn_Error

p4utils.utils.thrift_API.bytes_to_string(byte_array)

p4utils.utils.thrift_API.deprecated_act_prof(substitute, with_selection=False, strictly_deprecated=True)

p4utils.utils.thrift_API.enum(type_name, *sequential, **named)

p4utils.utils.thrift_API.handle_bad_input(f)

p4utils.utils.thrift_API.handle_bad_input_mc(f)

p4utils.utils.thrift_API.hex_to_i16(h)

p4utils.utils.thrift_API.hex_to_i32(h)

p4utils.utils.thrift_API.hexstr(v)

p4utils.utils.thrift_API.i16_to_hex(h)

p4utils.utils.thrift_API.i32_to_hex(h)

p4utils.utils.thrift_API.int_to_bytes(i, num)

p4utils.utils.thrift_API.ipv4Addr_to_bytes(addr)

p4utils.utils.thrift_API.ipv6Addr_to_bytes(addr)

p4utils.utils.thrift_API.macAddr_to_bytes(addr)

p4utils.utils.thrift_API.parse_bool(s)

p4utils.utils.thrift_API.parse_match_key(table, key_fields)

p4utils.utils.thrift_API.parse_param(input_str, bitwidth)

p4utils.utils.thrift_API.parse_pvs_value(input_str, bitwidth)

p4utils.utils.thrift_API.parse_runtime_data(action, params)

p4utils.utils.thrift_API.printable_byte_str(s)

p4utils.utils.thrift_API.table_error_name(x)

p4utils.utils.thrift_API.thrift_connect(thrift_ip, thrift_port, services)