p4utils.utils.p4runtime_API.api module¶

This module is a modified version of p4runtime_sh.shell that performs low level P4Runtime operations with the server running on a capable switch. It allows to specify the context and the client for each method and class that uses them without falling back to the global ones. Indeed, some changes were needed to manage multiple switches at the same time.

p4utils.utils.p4runtime_API.api.APIVersion(client)[source]¶: Returns the version of the P4Runtime API implemented by the server, using the Capabilities RPC.

class p4utils.utils.p4runtime_API.api.Action(context, action_name=None)[source]¶

Bases: object

Action parameters for P4 actions.

Usage

Set a param value with <self>['<param_name>'] = '<value>'.
You may also use <self>.set(<param_name>='<value>').

msg()[source]¶

set(**kwargs)[source]¶

class p4utils.utils.p4runtime_API.api.ActionProfileGroup(client, context, action_profile_name=None)[source]¶

Bases: p4utils.utils.p4runtime_API.api._P4EntityBase

An action profile group.

Usage

Use <self>.info to display the P4Info entry for the action profile.
Set the group id with <self>.group_id = <expr>. Default is 0.
Set the max size with <self>.max_size = <expr>. Default is 0.
Add members to the group with <self>.add(<member_id>, weight=<weight>, watch=<watch>). weight and watch are optional (default to 1 and 0 respectively).

Example

Typical usage to insert an action profile group:

g = action_profile_group['<action_profile_name>'](group_id=1)
g.add(<member id 1>)
g.add(<member id 2>)
# OR g.add(<member id 1>).add(<member id 2>)

add(member_id=None, weight=1, watch=0)[source]¶: Add a member to the members list.

clear()[source]¶: Empty members list.

read(function=None)[source]¶: Generate a P4Runtime Read RPC. Supports wildcard reads (just leave the appropriate fields unset). If function is None, returns an iterator. Iterate over it to get all the members (as ActionProfileGroup instances) returned by the server. Otherwise, function is applied to all the groups returned by the server.

class p4utils.utils.p4runtime_API.api.ActionProfileMember(client, context, action_profile_name=None)[source]¶

Bases: p4utils.utils.p4runtime_API.api._P4EntityBase

An action profile member.

Usage

Use <self>.info to display the P4Info entry for the action profile.
Set the member id with <self>.member_id = <expr>.
To set the action specification <self>.action = <instance of type Action>.
To set the value of action parameters, use <self>.action['<param name>'] = <expr>.

Example

Typical usage to insert an action profile member:

m = action_profile_member['<action_profile_name>'](action='<action_name>', member_id=1)
m.action['<p1>'] = ...
...
m.action['<pM>'] = ...
# OR m.action.set(p1=..., ..., pM=...)
m.insert

read(function=None)[source]¶: Generate a P4Runtime Read RPC. Supports wildcard reads (just leave the appropriate fields unset). If function is None, returns an iterator. Iterate over it to get all the members (as ActionProfileMember instances) returned by the server. Otherwise, function is applied to all the members returned by the server.

class p4utils.utils.p4runtime_API.api.CloneSessionEntry(client, context, session_id=0)[source]¶

Bases: p4utils.utils.p4runtime_API.api._EntityBase

Clone session entry.

Parameters:	session_id (int) – clone session id

Usage

Add replicas with <self>.add(<eg_port_1>, <instance_1>).add(<eg_port_2>, <instance_2>)...
Access class of service with <self>.cos.
Access truncation length with <self>.packet_length_bytes.

add(egress_port=None, instance=0)[source]¶: Add a replica to the clone session.

read(function=None)[source]¶: Generate a P4Runtime Read RPC to read a single CloneSessionEntry (wildcard reads not supported). If function is None, return a CloneSessionEntry instance (or None if the provided group id does not exist). If function is not None, function is applied to the CloneSessionEntry instance (if any).

class p4utils.utils.p4runtime_API.api.CounterEntry(client, context, counter_name=None)[source]¶

Bases: p4utils.utils.p4runtime_API.api._CounterEntryBase

An entry for a P4 counter.

Usage

Use <self>.info to display the P4Info entry for this counter.
Set the index with <self>.index = <expr>. To reset it (e.g. for wildcard read), set it to None.
Access byte count and packet count with <self>.byte_count / <self>.packet_count.
To read from the counter, use <self>.read().
To write to the counter, use <self>.modify().

read(function=None)[source]¶

Generate a P4Runtime Read RPC. Supports wildcard reads (just leave the index unset). If function is None, returns an iterator. Iterate over it to get all the counter entries (CounterEntry instances) returned by the server. Otherwise, function is applied to all the counter entries returned by the server.

Example

for c in <self>.read():
    print(c)

The above code is equivalent to the following one-liner:

<self>.read(lambda c: print(c))

class p4utils.utils.p4runtime_API.api.DigestEntry(client, context, digest_name)[source]¶

Bases: p4utils.utils.p4runtime_API.api._P4EntityBase

A P4Runtime digest entry.

It is used to configure how the device must generate digest messages.

Usage

The maximum server buffering delay in nanoseconds for an outstanding digest message can be set using <self>.max_timeout_ns = <expr>. By default, this is set to 0, i.e. the server should generate a DigestList message for every digest message generated by the data plane.
The maximum digest list size — in number of digest messages — sent by the server to the client as a single DigestList message can be set using <self>.max_list_size = <expr>. By default, this is set to 1, i.e. the server should generate a DigestList message for every digest message generated by the data plane.
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 can be set using <self>.ack_timeout_ns = <expr>. By default, this is set to 0, i.e. the cache of digests not yet acknowledged must always be an empty set.

read(function=None)[source]¶: Generate a P4Runtime Read RPC. Supports wildcard reads (just leave the appropriate fields unset). If function is None, returns an iterator, otherwise the function is applied to every entry in the iterator.

class p4utils.utils.p4runtime_API.api.DirectCounterEntry(client, context, direct_counter_name=None)[source]¶

Bases: p4utils.utils.p4runtime_API.api._CounterEntryBase

An entry for a P4 direct counter.

Usage

Use <self>.info to display the P4Info entry for this direct counter.
Set the table_entry with <self>.table_entry = <TableEntry instance>. To reset it (e.g. for wildcard read), set it to None. It is the same as: <self>.table_entry = TableEntry({}).
Access byte count and packet count with <self>.byte_count / <self>.packet_count.
To read from the counter, use <self>.read
To write to the counter, use <self>.modify

Note

The TableEntry instance must be for the table to which the direct counter is attached.

read(function=None)[source]¶

Generate a P4Runtime Read RPC. Supports wildcard reads (just leave the index unset). If function is None, returns an iterator. Iterate over it to get all the direct counter entries (DirectCounterEntry instances) returned by the server. Otherwise, function is applied to all the direct counter entries returned by the server.

Example

for c in <self>.read():
    print(c)

The above code is equivalent to the following one-liner:

<self>.read(lambda c: print(c))

class p4utils.utils.p4runtime_API.api.DirectMeterEntry(client, context, direct_meter_name=None)[source]¶

Bases: p4utils.utils.p4runtime_API.api._MeterEntryBase

An entry for a P4 direct meter.

Usage

Use <self>.info to display the P4Info entry for this direct meter.
Set the table_entry with <self>.table_entry = <TableEntry instance>. To reset it (e.g. for wildcard read), set it to None. It is the same as: <self>.table_entry = TableEntry({})
Access meter rates and burst sizes with:
- <self>.cir
- <self>.cburst
- <self>.pir
- <self>.pburst
To read from the meter, use <self>.read.
To write to the meter, use <self>.modify.

Note

The TableEntry instance must be for the table to which the direct meter is attached.

read(function=None)[source]¶

Generate a P4Runtime Read RPC. Supports wildcard reads (just leave the index unset). If function is None, returns an iterator. Iterate over it to get all the direct meter entries (DirectMeterEntry instances) returned by the server. Otherwise, function is applied to all the direct meter entries returned by the server.

Example

for c in <self>.read():
    print(c)

The above code is equivalent to the following one-liner:

<self>.read(lambda c: print(c))

class p4utils.utils.p4runtime_API.api.FwdPipeConfig(p4info, bin)[source]¶

Bases: tuple

bin[source]¶: Alias for field number 1

p4info[source]¶: Alias for field number 0

class p4utils.utils.p4runtime_API.api.GroupMember(member_id=None, weight=1, watch=0)[source]¶

Bases: object

A member in an ActionProfileGroup.

Parameters:	member_id (int) – member id (required) weight (int) – member weigth watch (int) – member watch

class p4utils.utils.p4runtime_API.api.MatchKey(table_name, match_fields)[source]¶

Bases: object

Match key fields for P4 table.

Usage

Set a field value with <self>['<field_name>'] = '...':

For exact match: <self>['<f>'] = '<value>'.
For ternary match: <self>['<f>'] = '<value>&&&<mask>'.
For LPM match: <self>['<f>'] = '<value>/<mask>'.
For range match: <self>['<f>'] = '<start>..<end>'.

Note

If it’s inconvenient to use the whole field name, you can use a unique suffix.

Example

You may also use <self>.set(<f>='<value>') but <f> must not include a . in this case.

clear()[source]¶

set(**kwargs)[source]¶

class p4utils.utils.p4runtime_API.api.MeterEntry(client, context, meter_name=None)[source]¶

Bases: p4utils.utils.p4runtime_API.api._MeterEntryBase

An entry for a P4 meter.

Usage

Use <self>.info to display the P4Info entry for this meter.
Set the index with <self>.index = <expr>. To reset it (e.g. for wildcard read), set it to None.
Access meter rates and burst sizes with:
- <self>.cir
- <self>.cburst
- <self>.pir
- <self>.pburst
To read from the meter, use <self>.read.
To write to the meter, use <self>.modify.

read(function=None)[source]¶

Generate a P4Runtime Read RPC. Supports wildcard reads (just leave the index unset). If function is None, returns an iterator. Iterate over it to get all the meter entries (MeterEntry instances) returned by the server. Otherwise, function is applied to all the meter entries returned by the server.

Example

for c in <self>.read():
    print(c)

The above code is equivalent to the following one-liner:

<self>.read(lambda c: print(c))

class p4utils.utils.p4runtime_API.api.MulticastGroupEntry(client, context, group_id=0)[source]¶

Bases: p4utils.utils.p4runtime_API.api._EntityBase

Multicast group entry.

Parameters:	group_id (int) – multicast group id

Usage

Add replicas with <self>.add(<eg_port_1>, <instance_1>).add(<eg_port_2>, <instance_2>)...

add(egress_port=None, instance=0)[source]¶: Add a replica to the multicast group.

read(function=None)[source]¶: Generate a P4Runtime Read RPC to read a single MulticastGroupEntry (wildcard reads not supported). If function is None, return a MulticastGroupEntry instance (or None if the provided group id does not exist). If function is not None, function is applied to the MulticastGroupEntry instance (if any).

exception p4utils.utils.p4runtime_API.api.NotSupportedYet(what)[source]¶: Bases: p4utils.utils.p4runtime_API.utils.UserError

class p4utils.utils.p4runtime_API.api.Oneshot(context, table_name=None)[source]¶

Bases: object

A oneshot action set for P4 table.

Usage

To add an action to the set, use <self>.add(<Action instance>).
You can also access the set of actions with <self>.actions (which is a Python list).

add(action=None, weight=1, watch=0)[source]¶: Add an action to the oneshot action set.

msg()[source]¶

class p4utils.utils.p4runtime_API.api.OneshotAction(action=None, weight=1, watch=0)[source]¶

Bases: object

An action in a oneshot action set.

Parameters:	action (p4utils.utils.p4runtime_API.api.Action) – action instance (required) weight (int) – action weight watch (int) – action watch

msg()[source]¶

class p4utils.utils.p4runtime_API.api.P4Object(obj_type, obj, context)[source]¶

Bases: object

A wrapper around the P4Info Protobuf message for P4 objects.

Usage

You can access any field from the message with <self>.<field name>.
You can access the name directly with <self>.name.
You can access the id directly with <self>.id.
If you need the underlying Protobuf message, you can access it with msg().

actions()[source]¶: Print list of actions, only for tables and action profiles.

info()[source]¶

msg()[source]¶: Get Protobuf message object.

class p4utils.utils.p4runtime_API.api.P4Objects(obj_type, context)[source]¶

Bases: object

All the P4 objects in the P4 program.

Usage

To access a specific object, use <self>['<name>'].

Example

You can use this class to iterate over all P4 object instances:

for x in <self>:
    print(x.id)

class p4utils.utils.p4runtime_API.api.Replica(egress_port=None, instance=0)[source]¶

Bases: object

A replica is the pair (<port number>, <instance id>). It is used for multicast and clone session programming.

Parameters:	egress_port (int) – outboud packets port instance (int) – instance of the packet replication

class p4utils.utils.p4runtime_API.api.TableEntry(client, context, table_name=None)[source]¶

Bases: p4utils.utils.p4runtime_API.api._P4EntityBase

An entry for a P4 table.

Usage

Use <self>.info to display the P4Info entry for this table.
To set the match key, use <self>.match['<field name>'] = <expr>.
To set the action specification (this is a direct table): <self>.action = <instance of type Action>.
To set the value of action parameters, use <self>.action['<param name>'] = <expr>.
To set the priority, use <self>.priority = <expr>.
To mark the entry as default, use <self>.is_default = True.
If a direct counter is set to this table, then:
- To set the counter spec, use <self>.counter_data.byte_count and/or <self>.counter_data.packet_count.
- To unset it, use <self>.counter_data = None or <self>.clear_counter_data().
If a direct meter is set to this table, then:
- To access the meter config, use <self>.meter_config.<cir|cburst|pir|pburst>.
- To unset it, use <self>.meter_config = None or <self>.clear_meter_config().
Access the member_id with <self>.member_id.
Access the group_id with <self>.group_id.
To add metadata to the entry, use <self>.metadata = <expr>.

Example

Typical usage to insert a table entry:

t = table_entry['<table_name>'](action='<action_name>')
t.match['<f1>'] = ...
...
t.match['<fN>'] = ...
# OR t.match.set(f1=..., ..., fN=...)
t.action['<p1>'] = ...
...
t.action['<pM>'] = ...
# OR t.action.set(p1=..., ..., pM=...)
t.insert

Typical usage to set the default entry:

t = table_entry['<table_name>'](is_default=True)
t.action['<p1>'] = ...
...
t.action['<pM>'] = ...
# OR t.action.set(p1=..., ..., pM=...)
t.modify

Typical usage to insert a table entry if you know the member_id:

t = table_entry['<table_name>']
t.match['<f1>'] = ...
...
t.match['<fN>'] = ...
# OR t.match.set(f1=..., ..., fN=...)
t.member_id = <expr>

clear_action()[source]¶: Clears the action spec for the TableEntry.

clear_counter_data()[source]¶: Clear all counter data, same as <self>.counter_data = None.

clear_match()[source]¶: Clears the match spec for the TableEntry.

clear_meter_config()[source]¶: Clear the meter config, same as <self>.meter_config = None.

read(function=None)[source]¶

Generate a P4Runtime Read RPC. Supports wildcard reads (just leave the appropriate fields unset). If function is None, returns an iterator. Iterate over it to get all the table entries (TableEntry instances) returned by the server. Otherwise, function is applied to all the table entries returned by the server.

Example

for te in <self>.read():
    print(te)

The above code is equivalent to the following one-liner:

<self>.read(lambda te: print(te))

To delete all the entries from a table, simply use:

table_entry['<table_name>'].read(function=lambda x: x.delete())

exception p4utils.utils.p4runtime_API.api.UserUsageError(usage)[source]¶: Bases: p4utils.utils.p4runtime_API.utils.UserError

p4utils.utils.p4runtime_API.api.Write(input_, client)[source]¶: Reads a WriteRequest from a file (text format) and sends it to the server. It rewrites the device id and election id appropriately.

p4utils.utils.p4runtime_API.api.setup(device_id=1, grpc_addr='localhost:9559', election_id=(1, 0), config=None)[source]¶: Establishes the connection to the P4Runtime server.

p4utils.utils.p4runtime_API.api.teardown(client)[source]¶: Tears down the connection to the P4Runtime server.