p4utils.utils.sswitch_p4runtime_API module¶

This module provides a P4Runtime API for the Simple Switch target. It builds on the generic P4Runtime API. The methods listed here were designed to be as close as possible (in the naming and in the signature) to those used in the ThriftAPI, so that passing to one method to the other is easier for the user.

class p4utils.utils.sswitch_p4runtime_API.CounterType[source]¶

Bases: enum.Enum

Counter type according to P4 Runtime Specification. See here for details.

both = 3[source]¶

bytes = 1[source]¶

packets = 2[source]¶

unspecified = 0[source]¶

class p4utils.utils.sswitch_p4runtime_API.SimpleSwitchP4RuntimeAPI(device_id, grpc_port, grpc_ip='0.0.0.0', p4rt_path=None, json_path=None)[source]¶

Bases: object

For a better documentation of the primitives and the assumptions used, please take a look at:

Parameters:	device_id (int) – switch id grpc_port (int) – the port the switch gRPC server is listening on grpc_ip (int) – the IP the switch gRPC server is listening on p4rt_path (str) – path to the P4Runtime Info file json_path (str) – path to the P4 JSON compiled file
Raises:	`FileNotFoundError` – if `p4rt_path` or `json_path` are not specified, or invalid and the client cannot retrieve the relevant informations from the P4Runtime server.

client[source]¶

P4Runtime client instance.

Type:	`P4RuntimeClient`

context[source]¶

P4Runtime context containing the information about all the P4 objects.

Type:	`Context`

counter_read(counter_name, index)[source]¶

Reads counter value.

Parameters:

counter_name (str) – name of the counter
index (int) – index of the counter to read (first element is at 0)

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

Note

P4Runtime does not distinguish between the different counter types, i.e. counters are always considered of PACKETS_AND_BYTES and both values are returned. It is user’s responsability to use only the correct value (see here).

counter_reset(counter_name)[source]¶

Resets all the counters values.

Parameters:	counter_name (str) – name of the counter
Returns:	True in case of success, None otherwise.
Return type:	bool

counter_write(counter_name, index, pkts=0, byts=0)[source]¶

Writes counter values. If no values are specified, the counter is reset.

Parameters:	counter_name (str) – name of the counter index (int) – index of the counter to write (first element is at `0`) pkts (int) – number of packets to write (default: `0`) byts (int) – number of bytes to write (default: `0`)
Returns:	True in case of success, None otherwise.
Return type:	bool

There are three types of counters:

BYTES, only the field byts is written and the value of pkts is ignored.
PACKETS, only the field pkts is written and the value of byts is ignored.
PACKETS_AND_BYTES, both byts and pkts are written.

cs_create(session_id, ports=[], instances=None, cos=0, packet_length=0)[source]¶

Adds a packet cloning session.

Parameters:	session_id (int) – clone session id ports (list) – list of port numbers to add to the clone session (each port number is `int`) instances (list) – list of instances of the corresponding ports (each instance is `int`) cos (int) – Class of Service (see here) packet_lentgth (int) – maximal packet length in bytes (after which, packets are truncated)
Returns:	True in case of success, None otherwise.
Return type:	bool

A replica is logically a tuple (port, instance) which has to be unique within the same multicast group. Instances can be explicitly assigned to ports by passing the list instances to this function. If the list instances is not specified, then the instance number is set to 0 for all the replicas by default.

Note

By default, packet_length is set to 0 i.e. no truncation happens and cos is set to 0 (normal packet classification). If ports is an empty list, then the packets are not cloned to any port.

cs_destroy(session_id)[source]¶

Removes a packet cloning session.

Parameters:	session_id (int) – clone session id
Returns:	True in case of success, None otherwise.
Return type:	bool

cs_get_replicas(session_id)[source]¶

Gets replicas which belog to a clone session.

Parameters:	session_id (int) – clone session id
Returns:	`(ports, instances)` where: `ports` is a list of port numbers of the clone session; `instances` is a list of instances of the corresponding ports.
Return type:	tuple

A replica is logically a tuple (port, instance) which has to be unique within the same multicast group.

cs_set_replicas(session_id, ports=[], instances=None, cos=0, packet_length=0)[source]¶

Configures a packet cloning session.

Parameters:	session_id (int) – clone session id ports (list) – list of port numbers to add to the clone session (each port number is `int`) instances (list) – list of instances of the corresponding ports (each instance is `int`) cos (int) – Class of Service (see here) packet_lentgth (int) – maximal packet length in bytes (after which, packets are truncated)
Returns:	True in case of success, None otherwise.
Return type:	bool

A replica is logically a tuple (port, instance) which has to be unique within the same multicast group. Instances can be explicitly assigned to ports by passing the list instances to this function. If the list instances is not specified, then the instance number is set to 0 for all the replicas by default.

Note

By default, the packet_length is set to 0 i.e. no truncation happens and cos is set to 0 (normal packet classification). If ports is an empty list, then the packets are not cloned to any port.

digest_enable(digest_name, max_timeout_ns=0, max_list_size=1, ack_timeout_ns=0)[source]¶

Enables and configure the digests generation of the switch.

Parameters:	digest_name (str) – name of the digest (the name is shown in the P4 runtime information file generated by the compiler) max_timeout_ns (int) – the maximum server buffering delay in nanoseconds for an outstanding digest message max_list_size (int) – the maximum digest list size (in number of digest messages) sent by the server to the client as a single `DigestList` Protobuf message ack_timeout_ns (int) – the timeout in nanoseconds that a server must wait for a digest list acknowledgement from the client before new digest messages can be generated for the same learned data
Returns:	True in case of success, None otherwise.
Return type:	bool

By default, max_timeout_ns is set to 0, i.e. the server should generate a DigestList message for every digest message generated by the data plane.

By default, max_list_size is set to 1, i.e. the server should generate a DigestList message for every digest message generated by the data plane.

By default, ack_timeout_ns is set to 0, i.e. the cache of digests not yet acknowledged must always be an empty set.

Note

P4Runtime only supports named digests, i.e. those declared in P4 with the following syntax: digest<named_struct_type>(1, {struct_field_1, struct_field_2, ...}) where named_struct_type must be explicited and previously defined. The name of the digest for the configuration’s sake is the name of the struct type (i.e. named_struct_type).

digest_get_conf(digest_name)[source]¶

Enables and configure the digests generation of the switch.

Parameters:	digest_name (str) – name of the digest (the name is shown in the P4 runtime information file generated by the compiler)
Returns:	`(max_timeout_ns, max_list_size, ack_timeout_ns)` where: `max_timeout_ns` is the maximum server buffering delay in nanoseconds for an outstanding digest message; `max_list_size` is the maximum digest list size (in number of digest messages) sent by the server to the client as a single DigestList Protobuf message; `ack_timeout_ns` is the timeout in nanoseconds that a server must wait for a digest list acknowledgement from the client before new digest messages can be generated for the same learned data.
Return type:	tuple

Note

P4Runtime only supports named digests, i.e. those declared in P4 with the following syntax: digest<named_struct_type>(1, {struct_field_1, struct_field_2, ...}) where named_struct_type must be explicited and previously defined. The name of the digest for the configuration’s sake is the name of the struct type (i.e. named_struct_type).

digest_set_conf(digest_name, max_timeout_ns=0, max_list_size=1, ack_timeout_ns=0)[source]¶

Configures the digests generation of the switch.

Parameters:	digest_name (str) – name of the digest (the name is shown in the P4 runtime information file generated by the compiler) max_timeout_ns (int) – the maximum server buffering delay in nanoseconds for an outstanding digest message max_list_size (int) – the maximum digest list size (in number of digest messages) sent by the server to the client as a single `DigestList` Protobuf message ack_timeout_ns (int) – the timeout in nanoseconds that a server must wait for a digest list acknowledgement from the client before new digest messages can be generated for the same learned data
Returns:	True in case of success, None otherwise.
Return type:	bool

By default, max_timeout_ns is set to 0, i.e. the server should generate a DigestList message for every digest message generated by the data plane.

By default, max_list_size is set to 1, i.e. the server should generate a DigestList message for every digest message generated by the data plane.

By default, ack_timeout_ns is set to 0, i.e. the cache of digests not yet acknowledged must always be an empty set.

Note

P4Runtime only supports named digests, i.e. those declared in P4 with the following syntax: digest<named_struct_type>(1, {struct_field_1, struct_field_2, ...}) where named_struct_type must be explicited and previously defined. The name of the digest for the configuration’s sake is the name of the struct type (i.e. named_struct_type).

direct_counter_read(direct_counter_name, match_keys, prio=0)[source]¶

Reads direct counter values.

Parameters:

direct_counter_name (str) – name of the direct counter
match_keys (list) – values to match (each value is a str) used to identify the entry
prio (int) – priority in ternary match (used to identify the table entry to which the direct counter is attached)

Returns:

(byte_count, packet_count) where:

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

Return type:

tuple

Note

P4Runtime does not distinguish between the different counter types, i.e. counters are always considered of PACKETS_AND_BYTES and both values are returned. It is user’s responsability to use only the correct value (see here).

direct_counter_reset(direct_counter_name)[source]¶

Resets all the direct counters values.

Parameters:	direct_counter_name (str) – name of the direct counter
Returns:	True in case of success, None otherwise.
Return type:	bool

direct_counter_write(direct_counter_name, match_keys, prio=0, pkts=0, byts=0)[source]¶

Writes direct counter values. If no values are specified, the counter is reset.

Parameters:	direct_counter_name (str) – name of the direct counter match_keys (list) – values to match (each value is a `str`) used to identify the entry prio (int) – priority in ternary match (used to identify the table entry to which the direct counter is attached) pkts (int) – number of packets to write (default: 0) byts (int) – number of bytes to write (default: 0)
Returns:	True in case of success, None otherwise.
Return type:	bool

Note

There are three types of counters:

BYTES, only the field byts is written and the value of pkts is ignored.
PACKETS, only the field pkts is written and the value of byts is ignored.
PACKETS_AND_BYTES, both byts and pkts are written.

direct_meter_array_set_rates(direct_meter_name, rates)[source]¶

Configures rates for an entire direct meter array.

Parameters:	direct_meter_name (str) – name of the direct meter rates (list) – `[(cir, cburst), (pir, pburst)]`
Returns:	True in case of success, None otherwise.
Return type:	bool

Note

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

direct_meter_get_rates(direct_meter_name, match_keys, prio=0)[source]¶

Retrieves rates for a direct meter.

Parameters:	direct_meter_name (str) – name of the direct meter match_keys (list) – values to match (each value is a `str`) used to identify the entry prio (int) – priority in ternary match (used to identify the table
Returns:	`[(cir, cburst), (pir, pburst)]` if meter is configured, None otherwise
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.

direct_meter_set_rates(direct_meter_name, match_keys, prio=0, rates=None)[source]¶

Configures rates for a single direct meter entry.

Parameters:	direct_meter_name (str) – name of the direct meter match_keys (list) – values to match (each value is a `str`) used to identify the entry prio (int) – priority in ternary match (used to identify the table entry to which the direct meter is attached) rates (list) – `[(cir, cburst), (pir, pburst)]` (default: None, i.e. all packets are marked as green)
Returns:	True in case of success, None otherwise.
Return type:	bool

Note

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

get_digest_list(timeout=None)[source]¶

Retrieves DigestList and send back acknowledgment.

Parameters:	timeout (int) – time to wait for packet
Returns:	`DigestList` Protobuf Message or None if the timeout has expired and no packet has been received.

Note

See here for further details. If timeout is set to None, the function will wait indefinitely.

mc_get_replicas(mgrp)[source]¶

Gets replicas which belog to a multicast group.

Parameters:	mgrp (int) – multicast group id
Returns:	`(ports, instances)` where: `ports` is a list of port numbers of the multicast group; `instances` is list of instances of the corresponding ports.
Return type:	tuple

A replica is logically a tuple (port, instance) which has to be unique within the same multicast group. Instances can be explicitly assigned to ports by passing the list instances to this function. If the list instances is not specified, then the instance number is set to 0 for all the replicas by default.

Note

mgrp must be greater than 0.

mc_mgrp_create(mgrp, ports=[], instances=None)[source]¶

Creates multicast group.

Parameters:	mgrp (int) – multicast group id ports (list) – list of port numbers to add to the multicast group (each port number is a `int`) instances (list) – list of instances of the corresponding ports (each instance is a `int`)
Returns:	True in case of success, None otherwise.
Return type:	bool

A replica is logically a tuple (port, instance) which has to be unique within the same multicast group. Instances can be explicitly assigned to ports by passing the list instances to this function. If the list instances is not specified, then the instance number is set to 0 for all the replicas by default.

Note

mgrp must be larger than 0. If ports is an empty list, then the packets are not multicasted to any port.

mc_mgrp_destroy(mgrp)[source]¶

Destroys multicast group.

Parameters:	mgrp (int) – multicast group id
Returns:	True in case of success, None otherwise.
Return type:	bool

Note

mgrp must be larger than 0.

mc_set_replicas(mgrp, ports=[], instances=None)[source]¶

Sets replicas for multicast group.

Parameters:	mgrp (int) – multicast group id ports (list) – list of port numbers to add to the multicast group (each port number is a `int`) instances (list) – list of instances of the corresponding ports (each instance is a `int`)
Returns:	True in case of success, None otherwise.
Return type:	bool

A replica is logically a tuple (port, instance) which has to be unique within the same multicast group. Instances can be explicitly assigned to ports by passing the list instances to this function. If the list instances is not specified, then the instance number is set to 0 for all the replicas by default.

Note

mgrp must be larger than 0. If ports is an empty list, then the packets are not multicasted to any port.

meter_array_set_rates(meter_name, rates)[source]¶

Configures rates for an entire meter array.

Parameters:	meter_name (str) – name of the meter rates (list) – `[(cir, cburst), (pir, pburst)]`
Returns:	True in case of success, None otherwise.
Return type:	bool

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)[source]¶

Retrieves rates for a meter.

Parameters:	meter_name (str) – name of the meter index (int) – index of the meter to read (first element is at `0`)
Returns:	`[(cir, cburst), (pir, pburst)]` if meter is configured, None otherwise.
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)[source]¶

Configures rates for a single meter entry.

Parameters:	meter_name (str) – name of the meter rates (list) – `[(cir, cburst), (pir, pburst)]` (default: None, i.e. all packets are marked as GREEN) index (int) – index of the meter to set (first element is at `0`)
Returns:	True in case of success, None otherwise.
Return type:	bool

Note

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

parse_action_param(action_name, action_params)[source]¶

parse_match_key(table_name, key_fields)[source]¶

reset_state()[source]¶

Resets the gRPC server of switch by establishing a new ForwardingPipelineConfig.

For further details about this method, please check this. Indeed, this method sends to the server a SetForwardingPipelineConfigRequest with action VERIFY_AND_COMMIT.

This method is buggy, please read the following warnings.

Warning

Due to some bug in the implementation of the gRPC server, this command does not fully erase all the forwarding state of the switch, but only resets the server.

Note

It is recommended to use p4utils.utils.thrift_API.ThriftAPI.reset_state() to reset the forwarding states. Moreover, if you only use the ThriftAPI to reset the switch, the gRPC server will not be reset.
To do things properly, both methods need to be called (the one from ThriftAPI and the one from SimpleSwitchP4RuntimeAPI).

table_add(table_name, action_name, match_keys, action_params=[], prio=0, rates=None, pkts=None, byts=None)[source]¶

Adds entry to a match table.

Parameters:	table_name (str) – name of the table action_name (str) – action to execute on hit match_keys (list) – values to match (each value is a `str`) action_params (list) – parameters passed to action (each parameter is a `str`) prio (int) – priority in ternary match rates (list) – `[(cir, cburst), (pir, pburst)]` (if None, the meter is set to its default behavior, i.e. marks all packets as GREEN) pkts (int) – number of packets to write (if None, the count is not changed) byts (int) – number of bytes to write (if None, the count is not changed)
Returns:	True in case of success, None otherwise.
Return type:	bool

There are different kinds of matches:

For exact match: <value>
For ternary match: <value>&&&<mask>
For LPM match: <value>/<mask>
For range match: <start>..<end>

There are three types of counters:

BYTES, only the field byts is written and the value of pkts is ignored.
PACKETS, only the field pkts is written and the value of byts is ignored.
PACKETS_AND_BYTES, both byts and pkts are written.

There are two types of meters:

BYTES, rates must be expressed in number of bytes per second.
PACKETS, rates must be expressed in number of packets per second.

Note

The rates field only applies if there is a direct meter attached to the table.
The pkts and byts fields only apply if there is a direct counter attached to the table.
The prio field must be set to a non-zero value if the match key includes a ternary match or to zero otherwise.
A higher prio number indicates that the entry must be given higher priority when performing a table lookup (see here for details).

table_clear(table_name)[source]¶

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

Parameters:	table_name (str) – name of the table
Returns:	True in case of success, None otherwise.
Return type:	bool

table_delete_match(table_name, match_keys, prio=None)[source]¶

Deletes an existing entry in a table.

Parameters:	table_name (str) – name of the table match_keys (list) – values to match (each value is a `str`) prio (int) – priority in ternary match
Returns:	True in case of success, None otherwise.
Return type:	bool

table_modify_match(table_name, action_name, match_keys, action_params=[], prio=0, rates=None, pkts=None, byts=None)[source]¶

Modifies entry in a table.

Parameters:	table_name (str) – name of the table action_name (str) – action to execute on hit match_keys (list) – values to match (each value is a `str`) action_params (list) – parameters passed to action (each parameter is a `str`) prio (int) – priority in ternary match rates (list) – `[(cir, cburst), (pir, pburst)]` (if None, the meter is set to its default behavior, i.e. marks all packets as GREEN) pkts (int) – number of packets to write (if None, the count is not changed) byts (int) – number of bytes to write (if None, the count is not changed)
Returns:	True in case of success, None otherwise.
Return type:	bool

There are three types of counters:

BYTES, only the field byts is written and the value of pkts is ignored.
PACKETS, only the field pkts is written and the value of byts is ignored.
PACKETS_AND_BYTES, both byts and pkts are written.

There are two types of meters:

BYTES, rates must be expressed in number of bytes per second.
PACKETS, rates must be expressed in number of packets per second.

Note

The rates field only applies if there is a direct meter attached to the table.
The pkts and byts fields only apply if there is a direct counter attached to the table.
When modifying the default entry, the configurations for its direct resources will be reset to their defaults, according to this.
The prio field must be set to a non-zero value if the match key includes a ternary match or to zero otherwise.
A higher prio number indicates that the entry must be given higher priority when performing a table lookup (see here for details).

table_reset_default(table_name)[source]¶

Resets default action for a match table.

Parameters:	table_name (str) – name of the table
Returns:	True in case of success, None otherwise.
Return type:	bool

Note

When resetting the default entry, the configurations for its direct resources will be reset to their defaults (see here).

table_set_default(table_name, action_name, action_params=[])[source]¶

Sets default action for a match table.

Parameters:	table_name (str) – name of the table action_name (str) – action to execute on hit action_params (list) – parameters passed to action (each parameter is a `str`)
Returns:	True in case of success, None otherwise.
Return type:	bool

Note

When setting the default entry, the configurations for its direct resources will be reset to their defaults, according to this.

Warning

For the current implementation, the specification is not followed and direct resources are not reset when modifying a table entry.

teardown()[source]¶: Tears down gRPC connection with the switch server.

p4utils.utils.sswitch_p4runtime_API.handle_bad_input(f)[source]¶

Handles bad input.

Parameters:	f (types.FunctionType) – function or method to handle