P4 in practice: BMv2, tables and stateful constructs

1. The running example: a basic router

The P4 lab uses one application throughout, basic.p4, a basic router, to illustrate the main features of P4₁₆. Its job is the canonical six steps of an IP router, and every step maps onto a piece of the language from chapter 6:

1. Parse the Ethernet and IPv4 headers from the packet.
2. Find the destination in the IPv4 routing table.
3. Update the source and destination MAC addresses.
4. Decrement the time-to-live (TTL) field.
5. Set the egress port.
6. Deparse the headers back into a packet.

The starter code comes with the Ethernet and IPv4 headers already defined and added to the headers struct, but the parser block empty. The coding homework — which is a good self-test of chapter 6 — is to fill it in: define the states, start in start, transition to parse_ethernet, extract the Ethernet header, branch on etherType with a select to parse_ipv4 if it equals the IPv4 type, otherwise finish; and in parse_ipv4, simply extract the IPv4 header.

2. The toolchain under the Makefile

The make targets hide a pipeline of tools, and knowing them is knowing how a P4 program becomes a running switch. In pseudocode the Makefile does:

P4C_ARGS   = --p4runtime-file $(basename $@).p4info --p4runtime-format text
RUN_SCRIPT = ../../utils/run_exercise.py
TOPO       = topology.json

build:   # for each P4 program, generate the BMv2 json
    p4c-bm2-ss --p4v 16 $(P4C_ARGS) -o $@ $<
run:     # build, then launch Mininet with the topology   [default target]
    sudo python $(RUN_SCRIPT) -t $(TOPO)
stop:
    sudo mn -c

The build step, p4c-bm2-ss -o test.json test.p4, produces test.json, a JSON description of the forwarding pipeline compiled from test.p4, required by the BMv2 simple_switch binary. Optionally it also emits a P4Info message — a protobuf describing the data model the control plane will use to generate P4Runtime requests (the subject of chapter 8).

3. Bringing up BMv2 and its CLI

Running the switch is a three-step dance, and each step corresponds to one of the boxes in the BMv2 diagram: prepare interfaces, start the model, start the CLI.

# step 2 — prepare veth interfaces first, then start the software switch
ip link add name veth0 type veth peer name veth1
for iface in "veth0 veth1"; do
    ip link set dev ${iface} up
    sysctl net.ipv6.conf.${iface}.disable_ipv6=1
done

sudo simple_switch --log-console --dump-packet-data 64 \
     -i 0@veth0 -i 1@veth2 ... test.json

# step 3 — start the runtime CLI (talks to the control server over a Thrift TCP socket)
simple_switch_CLI

The interaction with the control plane is stated plainly by the slides: the P4 program defines the packet-processing pipeline, but the rules within a table are entered by the control plane at runtime (via P4Runtime, chapter 8). When a rule matches a packet, its action is invoked with the parameters supplied by the control plane as part of the rule. In the exercises, booting the Mininet instance with make run installs the packet-processing rules in each switch's tables from the sX-commands.txt files, where X is the switch number; the sX-runtime.json files instead drive P4Runtime and refer to specific names of tables, keys and actions as defined in the P4Info file.

4. Installing rules by hand: table_add

Inside simple_switch_CLI you drive the tables directly. The syntax is worth memorising because it reappears verbatim in the industrial lab (chapter 11), where table_add modbus_sec cipher 2 => installs the encryption rules.

RuntimeCmd: show_tables
m_filter
m_table

RuntimeCmd: table_add m_table m_action \
    01:00:00:00:00:00&&&01:00:00:00:00:00 => 1 0
Adding entry to ternary match table m_table
SUCCESS
entry has been added with handle 1

RuntimeCmd: table_delete m_table 1

Three pieces of syntax carry the meaning:

The final piece of the run is traffic. In some exercises a send.py / receive.py pair is used; in others, standard Linux programs like ping; and scapy can build and sniff packets directly:

p = Ethernet()/IP()/UDP()/"Payload"
sendp(p, iface="veth0")
sniff(iface="veth9", prn=lambda x: x.show())

5. Exercise 2: basic tunneling

Tunneling is presented as a main feature for data center networks, mobile core networks (the Evolved Packet Core of chapter 13), network virtualization (VXLAN, GRE — chapter 4), mobility management (Mobile IP) and overlay routing. The mechanism is universal: encapsulate a packet into another by prepending a new header.

The exercise adds tunneling to the basic router by defining a new header type, myTunnel, that encapsulates the IP packet. It carries just two fields:

The key idea in the slides is that once a tunnel header is present the switch does routing on the tunnel header, so that changing the inner IP address will not change the path. The to-do list is a compact tour of everything in chapter 6:

1. Define the myTunnel_t header type and add it to the headers struct.
2. Update the parser to branch on etherType = 0x1212 (tunnel).
3. Define the myTunnel_forward action and the myTunnel_exact table.
4. Update the table-application logic in the ingress apply block.
5. Update the deparser.
6. Add forwarding rules: a myTunnel_ingress rule to encapsulate on the ingress switch, a myTunnel_forward rule to forward, and a myTunnel_egress rule to decapsulate and forward on the egress switch.
7. Read the tunnel ingress and egress counters every 2 seconds.

6. Cloning packets

Making a copy of a packet — for mirroring to an observer, exactly the final-project challenge of chapter 11 — is done with the clone3 primitive. The slides give the action and, in comments, the operational context:

action do_clone_i2e(bit<32> packet) {
  // BMv2 simple_switch can have multiple clone "sessions" at once.
  // Each can be configured to go to an independent output port,
  // via the simple_switch_CLI command mirroring_add.
  // A "mirroring session" and a "clone session" are the same thing.
  //   first parameter:  clone type
  //   second parameter: the session
  //   third parameter:  the metadata to carry across
  clone3(CloneType.I2E, I2E_CLONE_SESSION_ID, standard_metadata);
}

The I2E in CloneType.I2E means ingress-to-egress: the clone is made in ingress and delivered in egress. The clone session, configured with mirroring_add in the CLI, decides which port the copy leaves on. This one primitive is the entire mechanism behind "mirror all Modbus traffic to the observer" in the project challenges.

7. Exercise 3: ECN marking

This exercise is where the pipeline ordering of chapter 6 pays off. The theory came from chapter 5; here it becomes code. Explicit Congestion Notification uses two bits (in the old Type of Service field), and the slides give the four codepoints:

For packets originating from an ECT source, ECN-capable switches set the CE bits upon congestion — for example when the observed queue depth exceeds a threshold (RFC 3168). And here is the crucial fact: the V1Model standard metadata exposes the queue depth as standard_metadata.enq_qdepth, a bit<19> — but it is measured at the traffic manager and only available in egress. That is why the whole exercise happens in the egress control.

The desired behaviour and the P4 recipe:

• If an end host supports ECN, it puts 1 or 2 in ipv4.ecn. For such packets, each switch may change the value to 3 if the queue is larger than a threshold. The receiver copies the value back to the sender, and the sender lowers its rate.
• In P4: split the old TOS into DiffServ and ECN, update the checksum accordingly, and in egress compare the queue length with an ECN_THRESHOLD; if larger, set the ECN bits to 3 (binary 11, congestion encountered) — but only if the original ECN was 1 or 2.

8. Debugging BMv2

BMv2 maintains logs that track in detail how packets are processed, one per switch: /tmp/p4s.s1.log, /tmp/p4s.s2.log, /tmp/p4s.s3.log. You can add information to the logs manually with a dummy debug table that reads the headers and metadata of interest:

control MyIngress(...) {
  table debug {
    key = { std_meta.egress_spec : exact; }
    actions = { }
  }
  apply {
    // ...
    debug.apply();
  }
}

A table with no actions never changes the packet, but the act of building its lookup key is logged, so a line like Looking up key: * std_meta.egress_spec : 2 appears in the switch log. It is the P4 equivalent of a print statement, and it is the pragmatic answer to the FAQ facts from chapter 6 (architecture-dependent parser rejection, architecture-dependent parse depth): when in doubt, read what the switch actually did.

9. Stateful constructs: registers, counters, meters

Chapter 6 said pure P4 cannot keep state across packets and that the answer is external objects. Here are the three, and the distinction between them is the most exam-relevant material in the whole P4 lab.

The framing: stateless objects — variables (metadata) and headers — do not maintain state across packets; stateful objects — tables, and the externs registers/counters/meters — keep state across different packets.

register<bit<48>>(5) hello;   // array of 5 entries
hello.write(1, 0xff);          // reg.write(index, value)
hello.read(res, 1);            // reg.read(result, index)

counter(64, CounterType.packets_and_bytes) c;
apply { c.count((bit<32>)standard_metadata.ingress_port); }
// from the control plane:
//   counter_read MyIngress.c 1
//   -> MyIngress.c[1] = BmCounterValue(packets=1, bytes=658)

meter(16384, MeterType.packets) acl_meter;
action color_my_packets(bit<32> index) {
  acl_meter.execute_meter((bit<32>)index, meta.meta_tag); // meta_tag = colour
}
// then a second table drops or accepts depending on the colour
table m_filter {
  key = { meta.meta_tag: exact; }
  actions = { drop; NoAction; }
}

Choose the right stateful construct for a task with the widget below.

Check your understanding