Exercise for L2 multicast (#288)
This commit is contained in:
Tu Dang
Nate Foster
154
exercises/multicast/README.md
Normal file
154
exercises/multicast/README.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# Implementing Multicast
|
||||
|
||||
## Introduction
|
||||
|
||||
The objective of this exercise is to write a P4 program that multicasts packets
|
||||
to a group of ports.
|
||||
|
||||
|
||||
Upon receiving an Ethernet packet, the switch looks up the output port based on
|
||||
the destination MAC address. If it is a miss, the switch broadcast packets on
|
||||
ports belonging to a multicast group (if ingress port appears in the group, the
|
||||
packet will be dropped in the egress pipeline).
|
||||
|
||||
|
||||
Your switch will have a single table, which the control plane will populate with
|
||||
static rules. Each rule will map an Ethernet MAC address to the output port. We
|
||||
have already defined the control plane rules, so you only need to implement the
|
||||
data plane logic of your P4 program.
|
||||
|
||||
We will use the linear topology for this exercise. It is a single switch that
|
||||
connects four hosts as follow:
|
||||
|
||||
h1 h2
|
||||
| |
|
||||
---------------------------- s1
|
||||
| |
|
||||
h3 h4
|
||||
|
||||
Our P4 program will be written for the V1Model architecture implemented on
|
||||
P4.org's bmv2 software switch. The architecture file for the V1Model can be
|
||||
found at: /usr/local/share/p4c/p4include/v1model.p4. This file describes the
|
||||
interfaces of the P4 programmable elements in the architecture, the supported
|
||||
externs, as well as the architecture's standard metadata fields. We encourage
|
||||
you to take a look at it.
|
||||
|
||||
> **Spoiler alert:** There is a reference solution in the `solution`
|
||||
> sub-directory. Feel free to compare your implementation to the
|
||||
> reference.
|
||||
|
||||
## Step 1: Run the (incomplete) starter code
|
||||
|
||||
The directory with this README also contains a skeleton P4 program,
|
||||
`multicast.p4`, which initially drops all packets. Your job will be to extend
|
||||
this skeleton program to properly forward Ethernet packets.
|
||||
|
||||
Before that, let's compile the incomplete `multicast.p4` and bring up a switch
|
||||
in Mininet to test its behavior.
|
||||
|
||||
1. In your shell, run:
|
||||
```bash
|
||||
make run
|
||||
```
|
||||
This will:
|
||||
* compile `multicast.p4`, and
|
||||
* start the sig-topo in Mininet and configure all switches with
|
||||
the appropriate P4 program + table entries, and
|
||||
* configure all hosts with the commands listed in
|
||||
[pod-topo/topology.json](./pod-topo/topology.json)
|
||||
|
||||
2. You should now see a Mininet command prompt. Try to ping between
|
||||
hosts in the topology:
|
||||
```bash
|
||||
mininet> h1 ping h2
|
||||
mininet> pingall
|
||||
```
|
||||
3. Type `exit` to leave each xterm and the Mininet command line.
|
||||
Then, to stop mininet:
|
||||
```bash
|
||||
make stop
|
||||
```
|
||||
And to delete all pcaps, build files, and logs:
|
||||
```bash
|
||||
make clean
|
||||
```
|
||||
|
||||
The ping failed because each switch is programmed according to `multicast.p4`,
|
||||
which drops all packets on arrival. Your job is to extend this file so it
|
||||
forwards packets.
|
||||
|
||||
### A note about the control plane
|
||||
|
||||
A P4 program defines a packet-processing pipeline, but the rules within each
|
||||
table are inserted by the control plane. When a rule matches a packet, its
|
||||
action is invoked with parameters supplied by the control plane as part of the
|
||||
rule.
|
||||
|
||||
In this exercise, we have already implemented the control plane logic for you.
|
||||
As part of bringing up the Mininet instance, the `make run` command will install
|
||||
packet-processing rules in the tables of each switch. These are defined in the
|
||||
`sX-runtime.json` files, where `X` corresponds to the switch number.
|
||||
|
||||
**Important:** We use P4Runtime to install the control plane rules. The
|
||||
content of files `sX-runtime.json` refer to specific names of tables, keys, and
|
||||
actions, as defined in the P4Info file produced by the compiler (look for the
|
||||
file `build/basic.p4.p4info.txt` after executing `make run`). Any changes in the P4
|
||||
program that add or rename tables, keys, or actions will need to be reflected in
|
||||
these `sX-runtime.json` files.
|
||||
|
||||
## Step 2: Implement L2 Multicast
|
||||
|
||||
The `multicast.p4` file contains a skeleton P4 program with key pieces of logic
|
||||
replaced by `TODO` comments. Your implementation should follow the structure
|
||||
given in this file---replace each `TODO` with logic implementing the missing
|
||||
piece.
|
||||
|
||||
A complete `multicast.p4` will contain the following components:
|
||||
|
||||
1. Header type definitions for Ethernet (`ethernet_t`)
|
||||
2. An action to drop a packet, using `mark_to_drop()`.
|
||||
3. **TODO:** An action (called `multicast`) that sends multiple copies of packets
|
||||
to a group of output ports.
|
||||
4. **TODO:** Add the `multicast` action to the list of available actions
|
||||
5. **TODO:** Set `multicast` as default action for table `mac_lookup`
|
||||
|
||||
## Step 3: Run your solution
|
||||
|
||||
Follow the instructions from Step 1. This time, you should be able to
|
||||
successfully ping between `h1`, `h2` and `h3` but not `h4` in the topology.
|
||||
|
||||
6. **TODO:** Add port 4 to the multicast group in file `sig-topo/s1-runtime.json`
|
||||
|
||||
### Food for thought
|
||||
|
||||
Other questions to consider:
|
||||
- How would you enhance your program to respond to ARP requests?
|
||||
- How would you enhance your program to support MAC learning from the controller?
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
There are several problems that might manifest as you develop your program:
|
||||
|
||||
1. `multicast.p4` might fail to compile. In this case, `make run` will
|
||||
report the error emitted from the compiler and halt.
|
||||
|
||||
2. `multicast.p4` might compile but fail to support the control plane rules in
|
||||
the `s1-runtime.json` file that `make run` tries to install using P4Runtime. In
|
||||
this case, `make run` will report errors if control plane rules cannot be
|
||||
installed. Use these error messages to fix your `multicast.p4` implementation.
|
||||
|
||||
3. `multicast.p4` might compile, and the control plane rules might be installed,
|
||||
but the switch might not process packets in the desired way. The `logs/sX.log`
|
||||
files contain detailed logs that describing how each switch processes each
|
||||
packet. The output is detailed and can help pinpoint logic errors in your
|
||||
implementation.
|
||||
|
||||
#### Cleaning up Mininet
|
||||
|
||||
In the latter two cases above, `make run` may leave a Mininet instance
|
||||
running in the background. Use the following command to clean up
|
||||
these instances:
|
||||
|
||||
```bash
|
||||
make stop
|
||||
```
|
||||
Reference in New Issue
Block a user