diff --git a/README.md b/README.md index 18a60c3..7fae846 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # tutorials P4 language tutorials -**Make sure that you edit [env.sh] (env.sh) to point to your local copy of - [bmv2] (https://github.com/p4lang/behavioral-model) and [p4c-bm] - (https://github.com/p4lang/p4c-bm). You may want to follow the instructions - [here] - (https://github.com/p4lang/tutorials/tree/master/SIGCOMM_2015#obtaining-required-software) +**Make sure that you edit [env.sh](env.sh) to point to your local copy of + [bmv2](https://github.com/p4lang/behavioral-model) and + [p4c-bm](https://github.com/p4lang/p4c-bm). You may want to follow the + instructions + [here](https://github.com/p4lang/tutorials/tree/master/SIGCOMM_2015#obtaining-required-software) to make sure that your environment is setup correctly.** diff --git a/SIGCOMM_2015/README.md b/SIGCOMM_2015/README.md index 8db53e8..2b1281f 100644 --- a/SIGCOMM_2015/README.md +++ b/SIGCOMM_2015/README.md @@ -29,9 +29,9 @@ The original webpage for the tutorial can be found This repository include 2 exercises we presented at SIGCOMM: *Source Routing* and *Flowlet Switching*. Both exercises assume that you possess basic networking knowledge and some familiarity with the P4 language. Please take a look at the -[P4 language spec] (http://p4.org/spec/) and at the example `simple_router` -target [on p4lang] -(https://github.com/p4lang/p4factory/tree/master/targets/simple_router/p4src). +[P4 language spec](http://p4.org/spec/) and at the example `simple_router` +target [on +p4lang](https://github.com/p4lang/p4factory/tree/master/targets/simple_router/p4src). *Source Routing* asks you to write a P4 program from scratch to implement a custom source routing protocol. *Flowlet Switching* is more difficult: you will start from a simple P4 routing program (with ECMP) and implement a version of @@ -95,9 +95,8 @@ P4. We will call this protocol EasyRoute. You will be designing the P4 program from scratch, although you are of course welcome to reuse code from other targets in p4lang. To test your implementation, you will create a Mininet network and send messages between hosts. We provide a skeleton program: -[source_routing/p4src/source_routing.p4] -(source_routing/p4src/source_routing.p4), you need to implement the parser and -the ingress control flow. +[source_routing/p4src/source_routing.p4](source_routing/p4src/source_routing.p4), +you need to implement the parser and the ingress control flow. ### Description of the EasyRoute protocol @@ -187,8 +186,7 @@ is used to add an entry to a table You can look at example commands in the `flowlet_switching` directory: [flowlet_switching/commands.txt](flowlet_switching/commands.txt) and match them with the corresponding P4 tables -[flowlet_switching/p4src/simple_router.p4] -(flowlet_switching/p4src/simple_router.p4). +[flowlet_switching/p4src/simple_router.p4](flowlet_switching/p4src/simple_router.p4). ### Testing your code @@ -270,7 +268,7 @@ To compile and run the starter code, simply use `./run_demo.sh`. This time we will not be using Mininet, we will instead generate simple TCP test packets and send them individually to the switch to observe how it behaves. `run_demo.sh` will start the switch and populate the tables using the CLI commands from -[flowlet_switching/commands.txt] (flowlet_switching/commands.txt). +[flowlet_switching/commands.txt](flowlet_switching/commands.txt). When the switch is running, you can send test packets with `sudo ./run_test.py`. Note that this script will take a few seconds to complete. The @@ -304,13 +302,13 @@ destination of our test packet. ### What you need to do -1. Update the provided [P4 program] (flowlet_switching/p4src/simple_router.p4) -to perform TCP flowlet switching. In our case, it requires adding 2 tables to -the ingress pipeline. Remember that you can omit the 'reads' attribute for a -table. In this case, providing you configure the default action of the table -correctly, the default action will always be performed. +1. Update the provided [P4 program](flowlet_switching/p4src/simple_router.p4) to +perform TCP flowlet switching. In our case, it requires adding 2 tables to the +ingress pipeline. Remember that you can omit the 'reads' attribute for a table. +In this case, providing you configure the default action of the table correctly, +the default action will always be performed. -2. Update [commands.txt] (flowlet_switching/commands.txt) to configure your new +2. Update [commands.txt](flowlet_switching/commands.txt) to configure your new tables. 3. Run the above test again. Observe how the list of ports alternate between 1 diff --git a/examples/TLV_parsing/README.md b/examples/TLV_parsing/README.md index 2d4796d..a7c74a3 100644 --- a/examples/TLV_parsing/README.md +++ b/examples/TLV_parsing/README.md @@ -48,9 +48,9 @@ So in a nutshell, all this P4 program does is: We provide a small demo to let you test the program. It consists of the following scripts: -- [run_switch.sh] (run_switch.sh): compile the P4 program and starts the switch, +- [run_switch.sh](run_switch.sh): compile the P4 program and starts the switch, also configures the data plane by running the CLI [commands] (commands.txt). -- [send_one.py] (send_one.py): send an IPv4 packet with options +- [send_one.py](send_one.py): send an IPv4 packet with options To run the demo: - start the switch and configure the tables: `sudo ./run_switch.sh`. diff --git a/examples/action_profile/README.md b/examples/action_profile/README.md index bc2e140..2ff3f45 100644 --- a/examples/action_profile/README.md +++ b/examples/action_profile/README.md @@ -12,7 +12,7 @@ between P4 tables is not supported in bmv2. As always, you can start the switch with `./run_switch.sh` (and wait until `READY` is displayed). We program the dataplane with the following CLI commands -(from [commands.txt] (commands.txt)): +(from [commands.txt](commands.txt)): ``` 01. table_indirect_create_group ecmp_group diff --git a/examples/axon/README.md b/examples/axon/README.md index 58b47a3..a12aa2f 100644 --- a/examples/axon/README.md +++ b/examples/axon/README.md @@ -69,13 +69,13 @@ entries. We provide a small demo to let you test the program. It consists of the following scripts: -- [run_demo.sh] (run_demo.sh): compiles the P4 program, starts the switch, - configures the data plane by running the CLI [commands] - (commands.txt), and starts the mininet console. -- [receive.py] (receive.py): listens for Axon formatted packets. This - command is intended to be run by a mininet host. -- [send.py] (send.py): sends Axon formatted packets from one host to - another. This command is intended to be run by a mininet host. +- [run_demo.sh](run_demo.sh): compiles the P4 program, starts the switch, + configures the data plane by running the CLI [commands](commands.txt), and + starts the mininet console. +- [receive.py](receive.py): listens for Axon formatted packets. This command is + intended to be run by a mininet host. +- [send.py](send.py): sends Axon formatted packets from one host to another. + This command is intended to be run by a mininet host. To run the demo: ./run_demo.sh will compile your code and create the Mininet network described diff --git a/examples/copy_to_cpu/README.md b/examples/copy_to_cpu/README.md index a45ca85..f85f04f 100644 --- a/examples/copy_to_cpu/README.md +++ b/examples/copy_to_cpu/README.md @@ -13,7 +13,7 @@ The P4 program does the following: to `0xab`) - the original packet is dropped in the egress pipeline -Take a look at the [P4 code] (p4src/copy_to_cpu.p4). The program is very short +Take a look at the [P4 code](p4src/copy_to_cpu.p4). The program is very short and should be easy to understand. You will notice that we use a mirror session id of `250` in the program. This number is not relevant in itself, but needs to be consistent between the P4 program and the runtime application. @@ -22,16 +22,16 @@ be consistent between the P4 program and the runtime application. We provide a small demo to let you test the program. It consists of the following scripts: -- [run_switch.sh] (run_switch.sh): compile the P4 program and starts the switch, - also configures the data plane by running the CLI [commands] (commands.txt) -- [receive.py] (receive.py): sniff packets on port 3 (veth7) and print a hexdump +- [run_switch.sh](run_switch.sh): compile the P4 program and starts the switch, + also configures the data plane by running the CLI [commands](commands.txt) +- [receive.py](receive.py): sniff packets on port 3 (veth7) and print a hexdump of them -- [send_one.py] (send_one.py): send one simple IPv4 packet on port 0 (veth1) +- [send_one.py](send_one.py): send one simple IPv4 packet on port 0 (veth1) -If you take a look at [commands.txt] (commands.txt), you'll notice the following +If you take a look at [commands.txt](commands.txt), you'll notice the following command: `mirroring_add 250 3`. This means that all the cloned packets with mirror id `250` will be sent to port `3`, which is our de facto *CPU port*. This -is the reason why [receive.py] (receive.py) listens for incoming packets on port +is the reason why [receive.py](receive.py) listens for incoming packets on port `3`. To run the demo: diff --git a/examples/meter/README.md b/examples/meter/README.md index eeadd65..44b1e33 100644 --- a/examples/meter/README.md +++ b/examples/meter/README.md @@ -3,8 +3,8 @@ ## Description This program illustrates as simply as possible how to use meters in P4 with -bmv2. bmv2 uses two-rate three-color meters as described [here] -(https://tools.ietf.org/html/rfc2698). +bmv2. bmv2 uses two-rate three-color meters as described +[here](https://tools.ietf.org/html/rfc2698). For each incoming packet the `m_table` table is applied and the appropriate meter (based on the packet's source MAC address) is executed. Based on the @@ -17,16 +17,15 @@ to port 2 of the switch. After that, the packet will go through a second table, `m_filter`, which can either be a no-op or drop the packet based on how the packet was tagged by the -meter. If you take a look at the [runtime commands] (commands.txt) we wrote for +meter. If you take a look at the [runtime commands](commands.txt) we wrote for this example, you will see that we configure the table to drop all the packets for which the color is not *GREEN* (i.e. all packets for which `meta.meter_tag` is not `0`). -The [commands.txt] (commands.txt) file also gives you the meter -configuration. In this case, the first rate is 0.5 packets per second, with a -burst size of 1, and the second rate is 10 packets per second, with a burst size -of 1 also. Feel free to play with the numbers, but these play nicely with the -demonstration below. +The [commands.txt](commands.txt) file also gives you the meter configuration. In +this case, the first rate is 0.5 packets per second, with a burst size of 1, and +the second rate is 10 packets per second, with a burst size of 1 also. Feel free +to play with the numbers, but these play nicely with the demonstration below. Note that we use an `indirect` meter array, because `direct` ones are not supported yet by bmv2. @@ -35,9 +34,9 @@ supported yet by bmv2. We provide a small demo to let you test the program. It consists of the following scripts: -- [run_switch.sh] (run_switch.sh): compile the P4 program and starts the switch, - also configures the data plane by running the CLI [commands] (commands.txt). -- [send_and_receive.py] (send_and_receive.py): send packets periodically on port +- [run_switch.sh](run_switch.sh): compile the P4 program and starts the switch, + also configures the data plane by running the CLI [commands](commands.txt). +- [send_and_receive.py](send_and_receive.py): send packets periodically on port 0 and listen for packets on port 2. To run the demo: diff --git a/examples/resubmit/README.md b/examples/resubmit/README.md index 54a7331..21713a7 100644 --- a/examples/resubmit/README.md +++ b/examples/resubmit/README.md @@ -8,7 +8,7 @@ pipeline. For more information, please refer to the P4 specification. The P4 program only consists of an ingress pipeline, with 2 tables: `t_ingress_1` and `t_ingress_2`. When a packet enters the pipeline, the -following happens (based on the P4 program and the [commands.txt] (commands.txt) +following happens (based on the P4 program and the [commands.txt](commands.txt) files): - the packet hits `table_ingress_1` and the egress port is set to 2. - the packet hits `table_ingress_2`, `mymeta.f1` is set to 1 and the @@ -22,7 +22,7 @@ files): We provide a small demo to let you test the program. It consists of the following scripts, which you need to run one after the other, in 2 separate terminals: -- [run_switch.sh] (run_switch.sh): compile the P4 program and starts the switch, - also configures the data plane by running the CLI [commands] (commands.txt). -- [send_and_receive.py] (send_and_receive.py): send a packet on port 0 (veth1), +- [run_switch.sh](run_switch.sh): compile the P4 program and starts the switch, + also configures the data plane by running the CLI [commands](commands.txt). +- [send_and_receive.py](send_and_receive.py): send a packet on port 0 (veth1), wait for the forwarded packet on port 3 (veth7). diff --git a/examples/simple_nat/README.md b/examples/simple_nat/README.md index 9abbfac..9d671a1 100644 --- a/examples/simple_nat/README.md +++ b/examples/simple_nat/README.md @@ -3,8 +3,8 @@ ## Description This program implements a very basic full-cone NAT for TCP traffic (over -IPv4). According to [Wikipedia] -(https://en.wikipedia.org/wiki/Network_address_translation#Methods_of_translation), +IPv4). According to +[Wikipedia](https://en.wikipedia.org/wiki/Network_address_translation#Methods_of_translation), a full-cone NAT is defined as follows: Once an internal address (iAddr:iPort) is mapped to an external address @@ -43,7 +43,7 @@ the packet is forwarded appropriately. The most important part of the program is the `nat` table. If you understand what this table is doing, the rest of the program is mostly IPv4 forwarding. You -should also take a long look at [nat_app.py] (nat_app.py), which manages the +should also take a long look at [nat_app.py](nat_app.py), which manages the mappings and dynamically adds rules to the `nat` table. We use 11 as the CPU port. There is a special CPU veth pair (`cpu-veth-0` / diff --git a/workshop_05_2016/ecmp/README.md b/workshop_05_2016/ecmp/README.md index ccd85df..e620b83 100644 --- a/workshop_05_2016/ecmp/README.md +++ b/workshop_05_2016/ecmp/README.md @@ -3,7 +3,7 @@ ## Introduction simple_router.p4 is a very simple P4 program which does L3 routing. All the P4 -code can be found in the [p4src/simple_router.p4] (p4src/simple_router.p4) +code can be found in the [p4src/simple_router.p4](p4src/simple_router.p4) file. In this exercise we will try to build ECMP on top of the starter code. We will be assuming the following network topology: @@ -33,9 +33,9 @@ packets. veth pairs required for the demo.* To compile and run the starter code, simply use `./run_demo.sh`. The -[run_demo.sh] (run_demo.sh) script will run the P4 compiler (for bmv2), start -the switch and populate the tables using the CLI commands from [commands.txt] -(commands.txt). +[run_demo.sh](run_demo.sh) script will run the P4 compiler (for bmv2), start the +switch and populate the tables using the CLI commands from +[commands.txt](commands.txt). When the switch is running, you can send test packets with `sudo ./run_test.py`. Note that this script will take a few seconds to complete. The @@ -46,16 +46,17 @@ working yet. ## What you need to do -1. In this exercise, you need to update the provided [P4 program] -(p4src/simple_router.p4) to perform ECMP. When you are done, each incoming TCP -test packet should be forwarded to either port 1 or port 2, based on the result -of a crc16 hash computation performed on the TCP 5-tuple (`ipv4.srcAddr`, -`ipv4.dstAddr`, `ipv4.protocol`, `tcp.srcPort`, `tcp.dstPort`). You will need to -refer to the [P4 spec] (http://p4.org/wp-content/uploads/2015/04/p4-latest.pdf) -to familiarize yourself with the P4 constructs you will need. +1. In this exercise, you need to update the provided [P4 +program](p4src/simple_router.p4) to perform ECMP. When you are done, each +incoming TCP test packet should be forwarded to either port 1 or port 2, based +on the result of a crc16 hash computation performed on the TCP 5-tuple +(`ipv4.srcAddr`, `ipv4.dstAddr`, `ipv4.protocol`, `tcp.srcPort`, +`tcp.dstPort`). You will need to refer to the [P4 +spec](http://p4.org/wp-content/uploads/2015/04/p4-latest.pdf) to familiarize +yourself with the P4 constructs you will need. -2. Once you are done with the P4 code, you will need to update [commands.txt] -(commands.txt) to configure your new tables. +2. Once you are done with the P4 code, you will need to update +[commands.txt](commands.txt) to configure your new tables. 3. After that you can run the above test again. Once again, you will observe that all packets go to the same egress port. Don't panic :)! This is because all @@ -74,8 +75,8 @@ simple_router.p4>`. first one requires 2 tables and the use of the `modify_field_with_hash_based_offset` primitive. The second one uses a single table with an action profile. You can read about -`modify_field_with_hash_based_offset` and action profiles in the [P4 spec] -(http://p4.org/wp-content/uploads/2015/04/p4-latest.pdf). +`modify_field_with_hash_based_offset` and action profiles in the [P4 +spec](http://p4.org/wp-content/uploads/2015/04/p4-latest.pdf). 3. If you choose to use the first way (with 2 tables), your first table will match on the destination IP address and be in charge of computing an index