Simple P4Runtime tutorial for starters
See Japanese document.
The code and data in this repository were created as an easy starting point for first-timers using P4 Runtime to control a P4 Switch. It is assumed that you have some knowledge of P4 and P4 Runtime. I hope it will be a good entry point for people who are trying it out for the first time.
In this tutorial, you will try three things:.
- Packet-Out Processing
- Packet-In Processing
- Adding Entries to the Table
These experiments are performed in the following environments:
- Use P4 Runtime Shell as controller
- Use Mininet corresponding to P4 Runtime as switch
- Use open source p4c for P4 compilation
We have everything that runs in a Docker environment. At the first try, just use what is described in this document.
In this tutorial, all experiments are performed in a Docker environment.
Docker Hub: yutakayasuda/p4c_python3
The original p4lang/p4c somehow python3 did not work properly. Am I doing something wrong??
Docker Hub: opennetworking/p4mn GitHub: opennetworkinglab/p4mn-docker
Docker Hub: yutakayasuda/p4runtime-shell-dev GitHub: yyasuda/p4runtime-shell
The Original P4Runtime Shell did not include an implementation for Packet I/O, so added it and built it with Dockerfile.dev. And less and vim are added for convenience during development.
All set. Here are the steps. I recommend that you try them in order.
Tutorial 0: Preparing the Environment
The P4 switch program must be compiled before the experiment. Then start Mininet and start the P4 Runtime Shell, which is the controller replacement. Then connect them.
Tutorial 1: Packet-Out Processing
The P4 Runtime Shell acting as a controller sends a Packet-Out message to the switch in the Mininet environment. Verify that the packet arriving at the host connected to the port you specify as the Out destination.
Tutorial 2: Packet-In Processing
When a packet arrives with an unknown MAC address as the destination, the prepared P4 program will send it to the controller as a Packet-In. Here we see that if a host attached to the switch sends a ping packet, it becomes a Packet-In and is received by the P4 Runtime Shell.
Tutorial 3: Adding Entries to the Table
Packet I/O processing is performed using StreamMessageRequest / StreamMessageResponse messages of P4Runtime. P4 Runtime also has a WriteRequest message that can be used to update the contents of the P4 Runtime Entity, such as tables. Here, you register the MAC address in a table. And verify that a ping packet from the host attached to the switch outputs to the specified port accordingly.
Tutorial 4: Packet Round Trip
After Tutorial 3, add another entry to the table to verify that the ping packets are correctly going back and forth between the two hosts.
This tutorial did not go into depth into the internal structure of the system, but instead focused on providing a straightforward entry point. I think you will dig in there next. Here are some of the most useful documents I've read so far.
-
P4Runtime Specification v1.1.0 [HTML] [PDF] (See; 6.4.6. ControllerPacketMetadata, 16.1. Packet I/O)
-
P4Runtime proto p4/v1/p4runtime.proto (See around WriteReuqest / StreamMessageRequest / StreamMessageResponse)
-
P4Runtime proto p4/config/v1/p4info.proto (Pay attention to ControllerPacketMetadata)
-
Some documents about Protocol Buffer
-
P416 Portable Switch Architecture (PSA) v1.1 [HTML] [PDF] In the above P4 Runtime Specification, there are some statements that P4 Runtime assumes PSA to some extent, such as section 1.2 In Scope. I didn't have anything to do with PSA specific things in this tutorial, but it's worth reading if you're interested.
CPU port information is at the beginning of ether_switch.p4. If necessary, update it and recompile.
#define CPU_PORT 255If you don't know the CPU port number of the switch you are testing, P4Runtime-CPUport-finder may help.