bfrt_helper.bfrt

BfRtHelper 

class BfRtHelper(device_id, client_id, bfrt_info)[source]

Bases: object

Barefoot Runtime gRPC Helper Class

create_subscribe_request(learn: bool = True, timeout: bool = True, port_change: bool = True, request_timeout: int = 10)[source]

Create a subscribe request for registering with a device.

After a gRPC connection has been established between a client and the Barefoot Runtime server, a subscribe request must be issued by the client in order for the runtime to act on commands issued by the client as well as send and receive any other messages.

Parameters:

learn (bool, optional) – Enable learn notifications. Provided through digest messages from the gRPC stream channel. Default is True.
timeout (bool, optional) – Receive timeout notifications. Default is True.
port_change (bool, optional) – Receive port state change notifications. Default is True.
request_timeout (int, optional) – Default is 10.

create_write_request(program_name: str, atomicity=0, target: dict = {})[source]

Creates a basic write request with no updates.

This creates the base gRPC object for the majority of runtime program manipulation.

The optional target parameter contains any of the following:

pipe_id : The id of the pipe to apply the write. Tofino devices may contain multiple “pipes”, which in turn are comprised of multiple ports. Each pipe is capable of being loaded with it’s own P4 program that acts independently from other pipes. An ID is therefore necessary to identify it.
direction: The Tofino Native Architecture has a concept of ingress and egress pipelines. It is possible (AFAWK) that a single control can be associated with both ingress and egress pipelines, but their “instantiation” will contain tables unique to the direction.
prsr_id: TODO

The default argument for this is equivalent to:

{
    'pipe_id': 0xFFFF, # All pipes
    'direction': 0xFF, # All directions
    'prsr_id': 0xFF # TODO
}

Parameters:

program_name (str) – The name of the program to target.
atomicity (WriteRequest.Atomicity) – Controls the behaviour of a write request with respect to batched updates, i.e., whether any errors are ignored, errors cause rollbacks of previously submitted writes in the batch, or whether the write is treated as a single atomic transaction.
target (dict) – An optionally provided dictionary that maps parser identifier information.

Returns:

bfruntime_pb2.WriteRequest

create_key_field(table_name: str, field_name: str, data: Field)[source]

Generates key field component of a gRPC message

The performs a lookup of the key id (as messages contain a table ID and not the name) using the BfRtInfo object and also type checks the match type.

Parameters:

table_name (str) – Name of table to target
field_name (str) – Name of specific key field
data (Field) – Field data supplied as in instance of a Field object.

Returns:

bfruntime_pb2.KeyField

Raises:

UnknownKeyField – If the BfRtInfo object did not contain a a valid key field for the given table and field names.
MismatchedMatchType – If the match types (e.g. Exact) does not match the match type defined for the field actually present in the table.

create_table_write(program_name, table_name, key, action_name=None, action_params=None, update_type=1)[source]

Create a match-action table write request

Note

This does not support batched writes.

Parameters:

program_name (str) – Name of program to target.
table_name (str) – Name of table within the program. Depending on how the program has been compiled, you may need to prefix this name with “pipe”, e.g. “pipe.IngressControl.table”.
key (dict) – Dictionary of match field names to their match. The keys should be strings, and the value should be an instance of a Match (e.g. Exact) constructed with the correct field type as defined in the program.
action_name (str) – Name of the action to execute on a match.
action_params (dict) – Dictionary of parameter names and their values to pass to the executed action. As before, the key should be a string, but the value should derive from Field.
update_type (Update.Type) – The type of operation to take place, e.g., INSERT, MODIFY, DELETE. The default value of 1 corresponds to Update.Type.INSERT.

create_table_data_write(program_name: str, table_name, key, data, update_type=1)[source]

Create a table write for arbitrary tables.

It is possible to write to many other tables exposed to the runtime interface which can be used to manipulate copy to cpu settings, multicast groups, port settings etc.

While these tables can be considered as “ordinary” database tables, they are still manipulated by the same mechanisms as a match-action update.

Note

This does not support batched writes.

Parameters:

program_name (str) – Name of program to target.
table_name (str) – Name of table within the program. Depending on how the program has been compiled, you may need to prefix this name with “pipe”, e.g. “pipe.IngressControl.table”.
key (dict) – Dictionary of match field names to their match. The keys should be strings, and the value should be an instance of a Match (e.g. Exact) constructed with the correct field type as defined in the program.
data (Field) – The data to be added to the table. Like match-action updates, this can be expressed handily with a Field. This may could involve a StringField, however a use case for this hasn’t been firmly established.
update_type (Update.Type) – The type of operation to take place, e.g., INSERT, MODIFY, DELETE. The default value of 1 corresponds to Update.Type.INSERT.

create_table_read(program_name, table_name, key)[source]

create_copy_to_cpu(program_name, port)[source]: Create a for copying data to the CPU

Warning

Experimental.

create_set_pipeline_request(program_name, bfrt_path, context_path, binary_path)[source]

create_get_pipeline_request()[source]

Exceptions 

UnknownAction 

class UnknownAction(table_name, action_name)[source]

Bases: Exception

Exception raised when an action for a given table could not be found.

Parameters:

table_name (str) – String containing the name of the table.
action_name (str) – String containing the name of the action.

UnknownActionParameter 

class UnknownActionParameter(table_name: str, action_name: str, param_name: str)[source]

Bases: Exception

Exception raised when a action parameter for a given table could not be found.

Some tables have associated parameters with them; these are optional. These are applied to an action, for example (in P4):

action send_to_multicast_group(MulticastGroupId_t group) {
    ingress_metadata.multicast_grp_a = group;
}

Parameters:

table_name (str) – String containing the name of the table.
action_name (str) – String containing the name of the action.
param_name (str) – String containing the name of the parameter.

UnknownTable 

class UnknownTable(table_name: str)[source]

Bases: Exception

Exception raised when a given table could not be found.

Parameters:: table_name (str) – String containing the name of the table.

UnknownKeyField 

class UnknownKeyField(table_name: str, field_name: str)[source]

Bases: Exception

Exception raised when a key field for a given table could not be found.

A key field is a part of the match construct, and includes a name and data. When a table is executed, the key field names are used to retrieve a value with the same name as defined in either metadata or headers. This value is compared with the key field’s data on the basis of the fields defined match type:

table multicast {
    key = {
        hdr.vlan.id: exact;
    }
    actions = {
        send_to_multicast_group;
    }
    const entries = {
        100: send_to_multicast_group;
    }
}

In this example, a key is defined to match on a vlan id which has been parsed into the program’s headers. The key field’s name in this case is hdr.vlan.id and it’s match type is exact. If the name of this field is not defined, in some operations this exception will be raised.

Parameters:

table_name (str) – String containing the name of the table.
action_name (str) – String containing the name of the action.

MismatchedMatchType 

class MismatchedMatchType(field_name: str, field_data: Field, expected: str)[source]

Bases: Exception

Exception raised when the match for a key field declared in a request does not match that which is defined in the table.

The current accepted match types are:

LongestPrefixMatch

Exact

Ternary

Parameters:

field_name (str) – The name of the field in question.
field_data (Field) – The instance of the incorrect field.
expected (str) – The name of the expected data type.

MismatchedDataSize 

class MismatchedDataSize(expected: int, observed: int)[source]

Bases: Exception

Exception raised when the data size of a field in a request does not match that which is registered to the table.

Most fields have an associated bitwidth. This is defined in the P4 program, and is presented in the BfRt info file if generated. While we can’t do strict type checking, we can compare the bitwidths of the input and target fields (any field registered in this library, or defined by the user, will be equivalent to any other field with the same bitwidth).

Parameters:

expected (int) – Bitwidth of field as defined by P4 program.
observed (int) – Bitwidth of field presented by the user.

InvalidActionParameter 

class InvalidActionParameter(table_name: str, action_name: str, param_name: str, reason: str)[source]: Bases: Exception