Final edits for SIGCOMM tutorial (#191)

* Final updates for SIGCOMM '18

* Final updates for SIGCOMM '18

exercises/other/calc/Makefile

@@ -0,0 +1,5 @@
+BMV2_SWITCH_EXE = simple_switch_grpc
+NO_P4 = true
+P4C_ARGS = --p4runtime-file $(basename $@).p4info --p4runtime-format text
+
+include ../../utils/Makefile

exercises/other/calc/README.md

@@ -0,0 +1,107 @@
+# Implementing a P4 Calculator
+
+## Introduction
+
+The objective of this tutorial is to implement a basic calculator
+using a custom protocol header written in P4. The header will contain
+an operation to perform and two operands. When a switch receives a
+calculator packet header, it will execute the operation on the
+operands, and return the result to the sender.
+
+## Step 1: Run the (incomplete) starter code
+
+The directory with this README also contains a skeleton P4 program,
+`calc.p4`, which initially drops all packets.  Your job will be to
+extend it to properly implement the calculator logic.
+
+As a first step, compile the incomplete `calc.p4` and bring up a
+switch in Mininet to test its behavior.
+
+1. In your shell, run:
+   ```bash
+   make
+   ```
+   This will:
+   * compile `calc.p4`, and
+  
+   * start a Mininet instance with one switches (`s1`) connected to
+     two hosts (`h1`, `h2`).
+   * The hosts are assigned IPs of `10.0.1.1` and `10.0.1.2`.
+
+2. We've written a small Python-based driver program that will allow
+you to test your calculator. You can run the driver program directly
+from the Mininet command prompt:
+
+```
+mininet> h1 python calc.py 
+> 
+```
+
+3. The driver program will provide a new prompt, at which you can type
+basic expressions. The test harness will parse your expression, and
+prepare a packet with the corresponding operator and operands. It will
+then send a packet to the switch for evaluation. When the switch
+returns the result of the computation, the test program will print the
+result. However, because the calculator program is not implemented,
+you should see an error message.
+
+```
+> 1+1
+Didn't receive response
+>
+```
+
+## Step 2: Implement Calculator
+
+To implement the calculator, you will need to define a custom
+calculator header, and implement the switch logic to parse header,
+perform the requested operation, write the result in the header, and
+return the packet to the sender.
+
+We will use the following header format:
+
+             0                1                  2              3
+      +----------------+----------------+----------------+---------------+
+      |      P         |       4        |     Version    |     Op        |
+      +----------------+----------------+----------------+---------------+
+      |                              Operand A                           |
+      +----------------+----------------+----------------+---------------+
+      |                              Operand B                           |
+      +----------------+----------------+----------------+---------------+
+      |                              Result                              |
+      +----------------+----------------+----------------+---------------+
+ 
+
+-  P is an ASCII Letter 'P' (0x50)
+-  4 is an ASCII Letter '4' (0x34)
+-  Version is currently 0.1 (0x01)
+-  Op is an operation to Perform:
+ -   '+' (0x2b) Result = OperandA + OperandB
+ -   '-' (0x2d) Result = OperandA - OperandB
+ -   '&' (0x26) Result = OperandA & OperandB
+ -   '|' (0x7c) Result = OperandA | OperandB
+ -   '^' (0x5e) Result = OperandA ^ OperandB
+ 
+
+We will assume that the calculator header is carried over Ethernet,
+and we will use the Ethernet type 0x1234 to indicate the presence of
+the header.
+
+Given what you have learned so far, your task is to implement the P4
+calculator program. There is no control plane logic, so you need only
+worry about the data plane implementation.
+
+A working calculator implementation will parse the custom headers,
+execute the mathematical operation, write the result in the result
+field, and return the packet to the sender.
+
+## Step 3: Run your solution
+
+Follow the instructions from Step 1.  This time, you should see the
+correct result:
+
+```
+> 1+1
+2
+>
+```

exercises/other/calc/calc.p4

@@ -0,0 +1,250 @@
+/* -*- P4_16 -*- */
+
+/*
+ * P4 Calculator
+ *
+ * This program implements a simple protocol. It can be carried over Ethernet
+ * (Ethertype 0x1234).
+ *
+ * The Protocol header looks like this:
+ *
+ *        0                1                  2              3
+ * +----------------+----------------+----------------+---------------+
+ * |      P         |       4        |     Version    |     Op        |
+ * +----------------+----------------+----------------+---------------+
+ * |                              Operand A                           |
+ * +----------------+----------------+----------------+---------------+
+ * |                              Operand B                           |
+ * +----------------+----------------+----------------+---------------+
+ * |                              Result                              |
+ * +----------------+----------------+----------------+---------------+
+ *
+ * P is an ASCII Letter 'P' (0x50)
+ * 4 is an ASCII Letter '4' (0x34)
+ * Version is currently 0.1 (0x01)
+ * Op is an operation to Perform:
+ *   '+' (0x2b) Result = OperandA + OperandB
+ *   '-' (0x2d) Result = OperandA - OperandB
+ *   '&' (0x26) Result = OperandA & OperandB
+ *   '|' (0x7c) Result = OperandA | OperandB
+ *   '^' (0x5e) Result = OperandA ^ OperandB
+ *
+ * The device receives a packet, performs the requested operation, fills in the 
+ * result and sends the packet back out of the same port it came in on, while 
+ * swapping the source and destination addresses.
+ *
+ * If an unknown operation is specified or the header is not valid, the packet
+ * is dropped 
+ */
+
+#include <core.p4>
+#include <v1model.p4>
+
+/*
+ * Define the headers the program will recognize
+ */
+
+/*
+ * Standard Ethernet header 
+ */
+header ethernet_t {
+    bit<48> dstAddr;
+    bit<48> srcAddr;
+    bit<16> etherType;
+}
+
+/*
+ * This is a custom protocol header for the calculator. We'll use 
+ * etherType 0x1234 for it (see parser)
+ */
+const bit<16> P4CALC_ETYPE = 0x1234;
+const bit<8>  P4CALC_P     = 0x50;   // 'P'
+const bit<8>  P4CALC_4     = 0x34;   // '4'
+const bit<8>  P4CALC_VER   = 0x01;   // v0.1
+const bit<8>  P4CALC_PLUS  = 0x2b;   // '+'
+const bit<8>  P4CALC_MINUS = 0x2d;   // '-'
+const bit<8>  P4CALC_AND   = 0x26;   // '&'
+const bit<8>  P4CALC_OR    = 0x7c;   // '|'
+const bit<8>  P4CALC_CARET = 0x5e;   // '^'
+
+header p4calc_t {
+    bit<8>  op;
+/* TODO
+ * fill p4calc_t header with P, four, ver, op, operand_a, operand_b, and res
+   entries based on above protocol header definition.
+ */
+}
+
+/*
+ * All headers, used in the program needs to be assembled into a single struct.
+ * We only need to declare the type, but there is no need to instantiate it,
+ * because it is done "by the architecture", i.e. outside of P4 functions
+ */
+struct headers {
+    ethernet_t   ethernet;
+    p4calc_t     p4calc;
+}
+
+/*
+ * All metadata, globally used in the program, also  needs to be assembled 
+ * into a single struct. As in the case of the headers, we only need to 
+ * declare the type, but there is no need to instantiate it,
+ * because it is done "by the architecture", i.e. outside of P4 functions
+ */
+ 
+struct metadata {
+    /* In our case it is empty */
+}
+
+/*************************************************************************
+ ***********************  P A R S E R  ***********************************
+ *************************************************************************/
+parser MyParser(packet_in packet,
+                out headers hdr,
+                inout metadata meta,
+                inout standard_metadata_t standard_metadata) {    
+    state start {
+        packet.extract(hdr.ethernet);
+        transition select(hdr.ethernet.etherType) {
+            P4CALC_ETYPE : check_p4calc;
+            default      : accept;
+        }
+    }
+    
+    state check_p4calc {
+        /* TODO: just uncomment the following parse block */
+        /* 
+        transition select(packet.lookahead<p4calc_t>().p,
+        packet.lookahead<p4calc_t>().four,
+        packet.lookahead<p4calc_t>().ver) {
+            (P4CALC_P, P4CALC_4, P4CALC_VER) : parse_p4calc;
+            default                          : accept;
+        }
+        */
+    }
+    
+    state parse_p4calc {
+        packet.extract(hdr.p4calc);
+        transition accept;
+    }
+}
+
+/*************************************************************************
+ ************   C H E C K S U M    V E R I F I C A T I O N   *************
+ *************************************************************************/
+control MyVerifyChecksum(inout headers hdr,
+                         inout metadata meta) {
+    apply { }
+}
+
+/*************************************************************************
+ **************  I N G R E S S   P R O C E S S I N G   *******************
+ *************************************************************************/
+control MyIngress(inout headers hdr,
+                  inout metadata meta,
+                  inout standard_metadata_t standard_metadata) {
+    action send_back(bit<32> result) {
+        /* TODO
+         * - put the result back in hdr.p4calc.res
+         * - swap MAC addresses in hdr.ethernet.dstAddr and
+         *   hdr.ethernet.srcAddr using a temp variable
+         * - Send the packet back to the port it came from
+             by saving standard_metadata.ingress_port into
+             standard_metadata.egress_spec
+         */ 
+    }
+    
+    action operation_add() {
+        /* TODO call send_back with operand_a + operand_b */
+    }
+    
+    action operation_sub() {
+        /* TODO call send_back with operand_a - operand_b */
+    }
+    
+    action operation_and() {
+        /* TODO call send_back with operand_a & operand_b */
+    }
+    
+    action operation_or() {
+        /* TODO call send_back with operand_a | operand_b */
+    }
+
+    action operation_xor() {
+        /* TODO call send_back with operand_a ^ operand_b */
+    }
+
+    action operation_drop() {
+        mark_to_drop();
+    }
+    
+    table calculate {
+        key = {
+            hdr.p4calc.op        : exact;
+        }
+        actions = {
+            operation_add;
+            operation_sub;
+            operation_and;
+            operation_or;
+            operation_xor;
+            operation_drop;
+        }
+        const default_action = operation_drop();
+        const entries = {
+            P4CALC_PLUS : operation_add();
+            P4CALC_MINUS: operation_sub();
+            P4CALC_AND  : operation_and();
+            P4CALC_OR   : operation_or();
+            P4CALC_CARET: operation_xor();
+        }
+    }
+            
+    apply {
+        if (hdr.p4calc.isValid()) {
+            calculate.apply();
+        } else {
+            operation_drop();
+        }
+    }
+}
+
+/*************************************************************************
+ ****************  E G R E S S   P R O C E S S I N G   *******************
+ *************************************************************************/
+control MyEgress(inout headers hdr,
+                 inout metadata meta,
+                 inout standard_metadata_t standard_metadata) {
+    apply { }
+}
+
+/*************************************************************************
+ *************   C H E C K S U M    C O M P U T A T I O N   **************
+ *************************************************************************/
+
+control MyComputeChecksum(inout headers hdr, inout metadata meta) {
+    apply { }
+}
+
+/*************************************************************************
+ ***********************  D E P A R S E R  *******************************
+ *************************************************************************/
+control MyDeparser(packet_out packet, in headers hdr) {
+    apply {
+        packet.emit(hdr.ethernet);
+        packet.emit(hdr.p4calc);
+    }
+}
+
+/*************************************************************************
+ ***********************  S W I T T C H **********************************
+ *************************************************************************/
+
+V1Switch(
+MyParser(),
+MyVerifyChecksum(),
+MyIngress(),
+MyEgress(),
+MyComputeChecksum(),
+MyDeparser()
+) main;

exercises/other/calc/calc.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python
+
+import argparse
+import sys
+import socket
+import random
+import struct
+import re
+
+from scapy.all import sendp, send, srp1
+from scapy.all import Packet, hexdump
+from scapy.all import Ether, StrFixedLenField, XByteField, IntField
+from scapy.all import bind_layers
+import readline
+
+class P4calc(Packet):
+    name = "P4calc"
+    fields_desc = [ StrFixedLenField("P", "P", length=1),
+                    StrFixedLenField("Four", "4", length=1),
+                    XByteField("version", 0x01),
+                    StrFixedLenField("op", "+", length=1),
+                    IntField("operand_a", 0),
+                    IntField("operand_b", 0),
+                    IntField("result", 0xDEADBABE)]
+
+bind_layers(Ether, P4calc, type=0x1234)
+
+class NumParseError(Exception):
+    pass
+
+class OpParseError(Exception):
+    pass
+
+class Token:
+    def __init__(self,type,value = None):
+        self.type = type
+        self.value = value
+
+def num_parser(s, i, ts):
+    pattern = "^\s*([0-9]+)\s*"
+    match = re.match(pattern,s[i:])
+    if match:
+        ts.append(Token('num', match.group(1)))
+        return i + match.end(), ts
+    raise NumParseError('Expected number literal.')
+
+
+def op_parser(s, i, ts):
+    pattern = "^\s*([-+&|^])\s*"
+    match = re.match(pattern,s[i:])
+    if match:
+        ts.append(Token('num', match.group(1)))
+        return i + match.end(), ts
+    raise NumParseError("Expected binary operator '-', '+', '&', '|', or '^'.")
+
+
+def make_seq(p1, p2):
+    def parse(s, i, ts):
+        i,ts2 = p1(s,i,ts)
+        return p2(s,i,ts2)
+    return parse
+
+
+def main():
+
+    p = make_seq(num_parser, make_seq(op_parser,num_parser))
+    s = ''
+    iface = 'h1-eth0'
+
+    while True:
+        s = str(raw_input('> '))
+        if s == "quit":
+            break
+        print s
+        try:
+            i,ts = p(s,0,[])
+            pkt = Ether(dst='00:04:00:00:00:00', type=0x1234) / P4calc(op=ts[1].value,
+                                              operand_a=int(ts[0].value),
+                                              operand_b=int(ts[2].value))
+            pkt = pkt/' '
+
+#            pkt.show()
+            resp = srp1(pkt, iface=iface, timeout=1, verbose=False)
+            if resp:
+                p4calc=resp[P4calc]
+                if p4calc:
+                    print p4calc.result
+                else:
+                    print "cannot find P4calc header in the packet"
+            else:
+                print "Didn't receive response"
+        except Exception as error:
+            print error
+
+
+if __name__ == '__main__':
+    main()

exercises/other/calc/s1-runtime.json

@@ -0,0 +1,6 @@
+{
+  "target": "bmv2",
+  "p4info": "build/calc.p4info",
+  "bmv2_json": "build/calc.json",
+  "table_entries": [ ]
+}

exercises/other/calc/solution/calc.p4

@@ -0,0 +1,256 @@
+/* -*- P4_16 -*- */
+
+/*
+ * P4 Calculator
+ *
+ * This program implements a simple protocol. It can be carried over Ethernet
+ * (Ethertype 0x1234).
+ *
+ * The Protocol header looks like this:
+ *
+ *        0                1                  2              3
+ * +----------------+----------------+----------------+---------------+
+ * |      P         |       4        |     Version    |     Op        |
+ * +----------------+----------------+----------------+---------------+
+ * |                              Operand A                           |
+ * +----------------+----------------+----------------+---------------+
+ * |                              Operand B                           |
+ * +----------------+----------------+----------------+---------------+
+ * |                              Result                              |
+ * +----------------+----------------+----------------+---------------+
+ *
+ * P is an ASCII Letter 'P' (0x50)
+ * 4 is an ASCII Letter '4' (0x34)
+ * Version is currently 0.1 (0x01)
+ * Op is an operation to Perform:
+ *   '+' (0x2b) Result = OperandA + OperandB
+ *   '-' (0x2d) Result = OperandA - OperandB
+ *   '&' (0x26) Result = OperandA & OperandB
+ *   '|' (0x7c) Result = OperandA | OperandB
+ *   '^' (0x5e) Result = OperandA ^ OperandB
+ *
+ * The device receives a packet, performs the requested operation, fills in the 
+ * result and sends the packet back out of the same port it came in on, while 
+ * swapping the source and destination addresses.
+ *
+ * If an unknown operation is specified or the header is not valid, the packet
+ * is dropped 
+ */
+
+#include <core.p4>
+#include <v1model.p4>
+
+/*
+ * Define the headers the program will recognize
+ */
+
+/*
+ * Standard ethernet header 
+ */
+header ethernet_t {
+    bit<48> dstAddr;
+    bit<48> srcAddr;
+    bit<16> etherType;
+}
+
+/*
+ * This is a custom protocol header for the calculator. We'll use 
+ * ethertype 0x1234 for is (see parser)
+ */
+const bit<16> P4CALC_ETYPE = 0x1234;
+const bit<8>  P4CALC_P     = 0x50;   // 'P'
+const bit<8>  P4CALC_4     = 0x34;   // '4'
+const bit<8>  P4CALC_VER   = 0x01;   // v0.1
+const bit<8>  P4CALC_PLUS  = 0x2b;   // '+'
+const bit<8>  P4CALC_MINUS = 0x2d;   // '-'
+const bit<8>  P4CALC_AND   = 0x26;   // '&'
+const bit<8>  P4CALC_OR    = 0x7c;   // '|'
+const bit<8>  P4CALC_CARET = 0x5e;   // '^'
+
+header p4calc_t {
+    bit<8>  p;
+    bit<8>  four;
+    bit<8>  ver;
+    bit<8>  op;
+    bit<32> operand_a;
+    bit<32> operand_b;
+    bit<32> res;
+}
+
+/*
+ * All headers, used in the program needs to be assembed into a single struct.
+ * We only need to declare the type, but there is no need to instantiate it,
+ * because it is done "by the architecture", i.e. outside of P4 functions
+ */
+struct headers {
+    ethernet_t   ethernet;
+    p4calc_t     p4calc;
+}
+
+/*
+ * All metadata, globally used in the program, also  needs to be assembed 
+ * into a single struct. As in the case of the headers, we only need to 
+ * declare the type, but there is no need to instantiate it,
+ * because it is done "by the architecture", i.e. outside of P4 functions
+ */
+ 
+struct metadata {
+    /* In our case it is empty */
+}
+
+/*************************************************************************
+ ***********************  P A R S E R  ***********************************
+ *************************************************************************/
+parser MyParser(packet_in packet,
+                out headers hdr,
+                inout metadata meta,
+                inout standard_metadata_t standard_metadata) {
+
+    state start {
+        packet.extract(hdr.ethernet);
+        transition select(hdr.ethernet.etherType) {
+            P4CALC_ETYPE : check_p4calc;
+            default      : accept;
+        }
+    }
+    
+    state check_p4calc {
+        transition select(packet.lookahead<p4calc_t>().p,
+        packet.lookahead<p4calc_t>().four,
+        packet.lookahead<p4calc_t>().ver) {
+            (P4CALC_P, P4CALC_4, P4CALC_VER) : parse_p4calc;
+            default                          : accept;
+        }
+    }
+    
+    state parse_p4calc {
+        packet.extract(hdr.p4calc);
+        transition accept;
+    }
+}
+
+/*************************************************************************
+ ************   C H E C K S U M    V E R I F I C A T I O N   *************
+ *************************************************************************/
+control MyVerifyChecksum(inout headers hdr,
+                         inout metadata meta) {
+    apply { }
+}
+
+/*************************************************************************
+ **************  I N G R E S S   P R O C E S S I N G   *******************
+ *************************************************************************/
+control MyIngress(inout headers hdr,
+                  inout metadata meta,
+                  inout standard_metadata_t standard_metadata) {
+    
+    action send_back(bit<32> result) {
+        bit<48> tmp;
+
+        /* Put the result back in */
+        hdr.p4calc.res = result;
+        
+        /* Swap the MAC addresses */
+        tmp = hdr.ethernet.dstAddr;
+        hdr.ethernet.dstAddr = hdr.ethernet.srcAddr;
+        hdr.ethernet.srcAddr = tmp;
+        
+        /* Send the packet back to the port it came from */
+        standard_metadata.egress_spec = standard_metadata.ingress_port;
+    }
+    
+    action operation_add() {
+        send_back(hdr.p4calc.operand_a + hdr.p4calc.operand_b);
+    }
+    
+    action operation_sub() {
+        send_back(hdr.p4calc.operand_a - hdr.p4calc.operand_b);
+    }
+    
+    action operation_and() {
+        send_back(hdr.p4calc.operand_a & hdr.p4calc.operand_b);
+    }
+    
+    action operation_or() {
+        send_back(hdr.p4calc.operand_a | hdr.p4calc.operand_b);
+    }
+
+    action operation_xor() {
+        send_back(hdr.p4calc.operand_a ^ hdr.p4calc.operand_b);
+    }
+
+    action operation_drop() {
+        mark_to_drop();
+    }
+    
+    table calculate {
+        key = {
+            hdr.p4calc.op        : exact;
+        }
+        actions = {
+            operation_add;
+            operation_sub;
+            operation_and;
+            operation_or;
+            operation_xor;
+            operation_drop;
+        }
+        const default_action = operation_drop();
+        const entries = {
+            P4CALC_PLUS : operation_add();
+            P4CALC_MINUS: operation_sub();
+            P4CALC_AND  : operation_and();
+            P4CALC_OR   : operation_or();
+            P4CALC_CARET: operation_xor();
+        }
+    }
+
+            
+    apply {
+        if (hdr.p4calc.isValid()) {
+            calculate.apply();
+        } else {
+            operation_drop();
+        }
+    }
+}
+
+/*************************************************************************
+ ****************  E G R E S S   P R O C E S S I N G   *******************
+ *************************************************************************/
+control MyEgress(inout headers hdr,
+                 inout metadata meta,
+                 inout standard_metadata_t standard_metadata) {
+    apply { }
+}
+
+/*************************************************************************
+ *************   C H E C K S U M    C O M P U T A T I O N   **************
+ *************************************************************************/
+
+control MyComputeChecksum(inout headers hdr, inout metadata meta) {
+    apply { }
+}
+
+/*************************************************************************
+ ***********************  D E P A R S E R  *******************************
+ *************************************************************************/
+control MyDeparser(packet_out packet, in headers hdr) {
+    apply {
+        packet.emit(hdr.ethernet);
+        packet.emit(hdr.p4calc);
+    }
+}
+
+/*************************************************************************
+ ***********************  S W I T T C H **********************************
+ *************************************************************************/
+
+V1Switch(
+MyParser(),
+MyVerifyChecksum(),
+MyIngress(),
+MyEgress(),
+MyComputeChecksum(),
+MyDeparser()
+) main;

exercises/other/calc/topology.json

@@ -0,0 +1,12 @@
+{
+    "hosts": [
+        "h1",
+        "h2"
+    ],
+    "switches": {
+        "s1": { "runtime_json" : "s1-runtime.json" }
+    },
+    "links": [
+        ["h1", "s1"], ["h2", "s1"]
+    ]
+}

exercises/other/ecn/Makefile

@@ -0,0 +1,5 @@
+BMV2_SWITCH_EXE = simple_switch_grpc
+NO_P4 = true
+P4C_ARGS = --p4runtime-file $(basename $@).p4info --p4runtime-format text
+
+include ../../utils/Makefile

exercises/other/ecn/README.md

@@ -0,0 +1,192 @@
+# Implementing ECN
+
+## Introduction
+
+The objective of this tutorial is to extend basic L3 forwarding with
+an implementation of Explicit Congestion Notification (ECN).
+
+ECN allows end-to-end notification of network congestion without
+dropping packets.  If an end-host supports ECN, it puts the value of 1
+or 2 in the `ipv4.ecn` field.  For such packets, each switch may
+change the value to 3 if the queue size is larger than a threshold.
+The receiver copies the value to sender, and the sender can lower the
+rate.
+
+As before, we have already defined the control plane rules for
+routing, so you only need to implement the data plane logic of your P4
+program.
+
+> **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,
+`ecn.p4`, which initially implements L3 forwarding. Your job (in the
+next step) will be to extend it to properly append set the ECN bits
+
+Before that, let's compile the incomplete `ecn.p4` and bring up a
+network in Mininet to test its behavior.
+
+1. In your shell, run:
+   ```bash
+   make
+   ```
+   This will:
+   * compile `ecn.p4`, and
+   * start a Mininet instance with three switches (`s1`, `s2`, `s3`) configured
+     in a triangle. There are 5 hosts. `h1` and `h11` are connected to `s1`.
+     `h2` and `h22` are connected to `s2` and `h3` is connected to `s3`.
+   * The hosts are assigned IPs of `10.0.1.1`, `10.0.2.2`, etc
+     (`10.0.<Switchid>.<hostID>`).
+   * The control plane programs the P4 tables in each switch based on
+     `sx-runtime.json`
+
+2. We want to send a low rate traffic from `h1` to `h2` and a high
+rate iperf traffic from `h11` to `h22`.  The link between `s1` and
+`s2` is common between the flows and is a bottleneck because we
+reduced its bandwidth to 512kbps in topology.json.  Therefore, if we
+capture packets at `h2`, we should see the right ECN value.
+
+![Setup](setup.png)
+
+3. You should now see a Mininet command prompt. Open four terminals
+for `h1`, `h11`, `h2`, `h22`, respectively:
+   ```bash
+   mininet> xterm h1 h11 h2 h22
+   ```
+3. In `h2`'s XTerm, start the server that captures packets:
+   ```bash
+   ./receive.py
+   ```
+4. in `h22`'s XTerm, start the iperf UDP server:
+   ```bash
+   iperf -s -u
+   ```
+5. In `h1`'s XTerm, send one packet per second to `h2` using send.py
+say for 30 seconds:
+   ```bash
+   ./send.py 10.0.2.2 "P4 is cool" 30
+   ```
+   The message "P4 is cool" should be received in `h2`'s xterm,
+6. In `h11`'s XTerm, start iperf client sending for 15 seconds
+   ```bash
+   iperf -c 10.0.2.22 -t 15 -u
+   ```
+7. At `h2`, the `ipv4.tos` field (DiffServ+ECN) is always 1
+8. type `exit` to close each XTerm window
+
+Your job is to extend the code in `ecn.p4` to implement the ECN logic
+for setting the ECN flag.
+
+## Step 2: Implement ECN
+
+The `ecn.p4` file contains a skeleton P4 program with key pieces of
+logic replaced by `TODO` comments.  These should guide your
+implementation---replace each `TODO` with logic implementing the
+missing piece.
+
+First we have to change the ipv4_t header by splitting the TOS field
+into DiffServ and ECN fields.  Remember to update the checksum block
+accordingly.  Then, in the egress control block we must compare the
+queue length with ECN_THRESHOLD. If the queue length is larger than
+the threshold, the ECN flag will be set.  Note that this logic should
+happen only if the end-host declared supporting ECN by setting the
+original ECN to 1 or 2.
+
+A complete `ecn.p4` will contain the following components:
+
+1. Header type definitions for Ethernet (`ethernet_t`) and IPv4 (`ipv4_t`).
+2. Parsers for Ethernet, IPv4,
+3. An action to drop a packet, using `mark_to_drop()`.
+4. An action (called `ipv4_forward`), which will:
+	1. Set the egress port for the next hop.
+	2. Update the ethernet destination address with the address of
+           the next hop.
+	3. Update the ethernet source address with the address of the switch. 
+	4. Decrement the TTL.
+5. An egress control block that checks the ECN and
+`standard_metadata.enq_qdepth` and sets the ipv4.ecn.
+6. A deparser that selects the order in which fields inserted into the outgoing
+   packet.
+7. A `package` instantiation supplied with the parser, control,
+  checksum verification and recomputation and deparser.
+
+## Step 3: Run your solution
+
+Follow the instructions from Step 1. This time, when your message from
+`h1` is delivered to `h2`, you should see `tos` values change from 1
+to 3 as the queue builds up.  `tos` may change back to 1 when iperf
+finishes and the queue depletes.
+
+To easily track the `tos` values you may want to redirect the output
+of `h2` to a file by running the following for `h2`
+   ```bash
+   ./receive.py > h2.log
+   ```
+and just print the `tos` values `grep tos h2.log` in a separate window
+```
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x3
+     tos       = 0x3
+     tos       = 0x3
+     tos       = 0x3
+     tos       = 0x3
+     tos       = 0x3
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+     tos       = 0x1
+```
+
+### Food for thought
+
+How can we let the user configure the threshold?
+
+### Troubleshooting
+
+There are several ways that problems might manifest:
+
+1. `ecn.p4` fails to compile.  In this case, `make` will report the
+   error emitted from the compiler and stop.
+2. `ecn.p4` compiles but does not support the control plane rules in
+   the `sX-runtime.json` files that `make` tries to install using
+   a Python controller. In this case, `make` will log the controller output 
+   in the `logs` directory. Use these error messages to fix your `ecn.p4`
+   implementation.
+3. `ecn.p4` compiles, and the control plane rules are installed, but
+   the switch does not process packets in the desired way.  The
+   `/tmp/p4s.<switch-name>.log` files contain trace messages
+   describing how each switch processes each packet.  The output is
+   detailed and can help pinpoint logic errors in your implementation.
+   The `build/<switch-name>-<interface-name>.pcap` also contains the
+   pcap of packets on each interface. Use `tcpdump -r <filename> -xxx`
+   to print the hexdump of the packets.
+4. `ecn.p4` compiles and all rules are installed. Packets go through
+   and the logs show that the queue length was not high enough to set
+   the ECN bit.  Then either lower the threshold in the p4 code or
+   reduce the link bandwidth in `topology.json`
+
+#### Cleaning up Mininet
+
+In the latter two cases above, `make` may leave a Mininet instance
+running in the background.  Use the following command to clean up
+these instances:
+
+```bash
+make stop
+```

exercises/other/ecn/ecn.p4

@@ -0,0 +1,187 @@
+/* -*- P4_16 -*- */
+#include <core.p4>
+#include <v1model.p4>
+
+const bit<8>  TCP_PROTOCOL = 0x06;
+const bit<16> TYPE_IPV4 = 0x800;
+const bit<19> ECN_THRESHOLD = 10;
+
+/*************************************************************************
+*********************** H E A D E R S  ***********************************
+*************************************************************************/
+
+typedef bit<9>  egressSpec_t;
+typedef bit<48> macAddr_t;
+typedef bit<32> ip4Addr_t;
+
+header ethernet_t {
+    macAddr_t dstAddr;
+    macAddr_t srcAddr;
+    bit<16>   etherType;
+}
+
+/*
+ * TODO: split tos to two fields 6 bit diffserv and 2 bit ecn
+ */
+header ipv4_t {
+    bit<4>    version;
+    bit<4>    ihl;
+    bit<8>    tos;
+    bit<16>   totalLen;
+    bit<16>   identification;
+    bit<3>    flags;
+    bit<13>   fragOffset;
+    bit<8>    ttl;
+    bit<8>    protocol;
+    bit<16>   hdrChecksum;
+    ip4Addr_t srcAddr;
+    ip4Addr_t dstAddr;
+}
+
+struct metadata {
+}
+
+struct headers {
+    ethernet_t   ethernet;
+    ipv4_t       ipv4;
+}
+
+/*************************************************************************
+*********************** P A R S E R  ***********************************
+*************************************************************************/
+
+parser MyParser(packet_in packet,
+                  out headers hdr,
+                  inout metadata meta,
+                  inout standard_metadata_t standard_metadata) {
+
+    state start {
+        transition parse_ethernet;
+    }
+
+    state parse_ethernet {
+        packet.extract(hdr.ethernet);
+        transition select(hdr.ethernet.etherType) {
+            TYPE_IPV4: parse_ipv4;
+            default: accept;
+        }
+    }
+
+    state parse_ipv4 {
+        packet.extract(hdr.ipv4);
+        transition accept;
+    }
+}
+
+
+/*************************************************************************
+************   C H E C K S U M    V E R I F I C A T I O N   *************
+*************************************************************************/
+
+control MyVerifyChecksum(inout headers hdr, inout metadata meta) {   
+    apply {  }
+}
+
+
+/*************************************************************************
+**************  I N G R E S S   P R O C E S S I N G   *******************
+*************************************************************************/
+
+control MyIngress(inout headers hdr,
+                  inout metadata meta,
+                  inout standard_metadata_t standard_metadata) {
+    action drop() {
+        mark_to_drop();
+    }
+    
+    action ipv4_forward(macAddr_t dstAddr, egressSpec_t port) {
+        standard_metadata.egress_spec = port;
+        hdr.ethernet.srcAddr = hdr.ethernet.dstAddr;
+        hdr.ethernet.dstAddr = dstAddr;
+        hdr.ipv4.ttl = hdr.ipv4.ttl - 1;
+    }
+
+    table ipv4_lpm {
+        key = {
+            hdr.ipv4.dstAddr: lpm;
+        }
+        actions = {
+            ipv4_forward;
+            drop;
+        }
+        size = 1024;
+        default_action = drop;
+    }
+    
+    apply {
+        if (hdr.ipv4.isValid()) {
+            ipv4_lpm.apply();
+        }
+    }
+}
+
+/*************************************************************************
+****************  E G R E S S   P R O C E S S I N G   *******************
+*************************************************************************/
+
+control MyEgress(inout headers hdr,
+                 inout metadata meta,
+                 inout standard_metadata_t standard_metadata) {
+    apply {
+        /*
+         * TODO:
+         * - if ecn is 1 or 2
+         *   - compare standard_metadata.enq_qdepth with threshold 
+         *     and set hdr.ipv4.ecn to 3 if larger
+         */
+    }
+}
+
+/*************************************************************************
+*************   C H E C K S U M    C O M P U T A T I O N   **************
+*************************************************************************/
+
+control MyComputeChecksum(inout headers hdr, inout metadata meta) {
+    apply {
+        /* TODO: replace tos with diffserve and ecn */
+	update_checksum(
+	    hdr.ipv4.isValid(),
+            { hdr.ipv4.version,
+              hdr.ipv4.ihl,
+              hdr.ipv4.tos,
+              hdr.ipv4.totalLen,
+              hdr.ipv4.identification,
+              hdr.ipv4.flags,
+              hdr.ipv4.fragOffset,
+              hdr.ipv4.ttl,
+              hdr.ipv4.protocol,
+              hdr.ipv4.srcAddr,
+              hdr.ipv4.dstAddr },
+            hdr.ipv4.hdrChecksum,
+            HashAlgorithm.csum16);
+    }
+}
+
+/*************************************************************************
+***********************  D E P A R S E R  *******************************
+*************************************************************************/
+
+control MyDeparser(packet_out packet, in headers hdr) {
+    apply {
+        packet.emit(hdr.ethernet);
+        packet.emit(hdr.ipv4);
+    }
+}
+
+/*************************************************************************
+***********************  S W I T C H  *******************************
+*************************************************************************/
+
+V1Switch(
+MyParser(),
+MyVerifyChecksum(),
+MyIngress(),
+MyEgress(),
+MyComputeChecksum(),
+MyDeparser()
+) main;

exercises/other/ecn/receive.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+import sys
+import struct
+
+from scapy.all import sniff, sendp, hexdump, get_if_list, get_if_hwaddr
+from scapy.all import Packet
+from scapy.all import IP, UDP, Raw
+from scapy.layers.inet import _IPOption_HDR
+
+def get_if():
+    ifs=get_if_list()
+    iface=None
+    for i in get_if_list():
+        if "eth0" in i:
+            iface=i
+            break;
+    if not iface:
+        print "Cannot find eth0 interface"
+        exit(1)
+    return iface
+
+def handle_pkt(pkt):
+    print "got a packet"
+    pkt.show2()
+#    hexdump(pkt)
+    sys.stdout.flush()
+
+
+def main():
+    iface = 'h2-eth0'
+    print "sniffing on %s" % iface
+    sys.stdout.flush()
+    sniff(filter="udp and port 4321", iface = iface,
+          prn = lambda x: handle_pkt(x))
+
+if __name__ == '__main__':
+    main()

exercises/other/ecn/s1-runtime.json

@@ -0,0 +1,52 @@
+{
+  "target": "bmv2",
+  "p4info": "build/ecn.p4info",
+  "bmv2_json": "build/ecn.json",
+  "table_entries": [
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.1.1", 32]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:00:01:01",
+        "port": 2
+      }
+    },
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.1.11", 32]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:00:01:0b",
+        "port": 1
+      }
+    },
+ 
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.2.0", 24]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:02:03:00",
+        "port": 3
+      }
+    },
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.3.0", 24]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:03:02:00",
+        "port": 4
+      }
+    }
+  ]
+}

exercises/other/ecn/s2-runtime.json

@@ -0,0 +1,51 @@
+{
+  "target": "bmv2",
+  "p4info": "build/ecn.p4info",
+  "bmv2_json": "build/ecn.json",
+  "table_entries": [
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.2.2", 32]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:00:02:02",
+        "port": 2
+      }
+    },
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.2.22", 32]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:00:02:16",
+        "port": 1
+      }
+    },
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.1.0", 24]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:01:03:00",
+        "port": 3
+      }
+    },
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.3.0", 24]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:03:03:00",
+        "port": 4
+      }
+    }
+  ]
+}

exercises/other/ecn/s3-runtime.json

@@ -0,0 +1,40 @@
+{
+  "target": "bmv2",
+  "p4info": "build/ecn.p4info",
+  "bmv2_json": "build/ecn.json",
+  "table_entries": [
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.3.3", 32]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:00:03:03",
+        "port": 1
+      }
+    },
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.1.0", 24]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:01:04:00",
+        "port": 2
+      }
+    },
+    {
+      "table": "MyIngress.ipv4_lpm",
+      "match": {
+        "hdr.ipv4.dstAddr": ["10.0.2.0", 24]
+      },
+      "action_name": "MyIngress.ipv4_forward",
+      "action_params": {
+        "dstAddr": "00:00:00:02:04:00",
+        "port": 3
+      }
+    }
+  ]
+}

exercises/other/ecn/send.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+
+import argparse
+import sys
+import socket
+import random
+import struct
+
+from scapy.all import sendp, send, hexdump, get_if_list, get_if_hwaddr
+from scapy.all import Packet, IPOption
+from scapy.all import Ether, IP, UDP
+from scapy.all import IntField, FieldListField, FieldLenField, ShortField
+from scapy.layers.inet import _IPOption_HDR
+
+from time import sleep
+
+def get_if():
+    ifs=get_if_list()
+    iface=None # "h1-eth0"
+    for i in get_if_list():
+        if "eth0" in i:
+            iface=i
+            break;
+    if not iface:
+        print "Cannot find eth0 interface"
+        exit(1)
+    return iface
+
+def main():
+
+    if len(sys.argv)<4:
+        print 'pass 2 arguments: <destination> "<message>" <duration>'
+        exit(1)
+
+    addr = socket.gethostbyname(sys.argv[1])
+    iface = get_if()
+
+    pkt = Ether(src=get_if_hwaddr(iface), dst="ff:ff:ff:ff:ff:ff") / IP(dst=addr, tos=1) / UDP(dport=4321, sport=1234) / sys.argv[2]
+    pkt.show2()
+    #hexdump(pkt)
+    try:
+      for i in range(int(sys.argv[3])):
+        sendp(pkt, iface=iface)
+        sleep(1)
+    except KeyboardInterrupt:
+        raise
+
+
+if __name__ == '__main__':
+    main()

exercises/other/ecn/solution/ecn.p4

@@ -0,0 +1,188 @@
+/* -*- P4_16 -*- */
+#include <core.p4>
+#include <v1model.p4>
+
+const bit<8>  TCP_PROTOCOL = 0x06;
+const bit<16> TYPE_IPV4 = 0x800;
+const bit<19> ECN_THRESHOLD = 10;
+
+/*************************************************************************
+*********************** H E A D E R S  ***********************************
+*************************************************************************/
+
+typedef bit<9>  egressSpec_t;
+typedef bit<48> macAddr_t;
+typedef bit<32> ip4Addr_t;
+
+header ethernet_t {
+    macAddr_t dstAddr;
+    macAddr_t srcAddr;
+    bit<16>   etherType;
+}
+
+header ipv4_t {
+    bit<4>    version;
+    bit<4>    ihl;
+    bit<6>    diffserv;
+    bit<2>    ecn;
+    bit<16>   totalLen;
+    bit<16>   identification;
+    bit<3>    flags;
+    bit<13>   fragOffset;
+    bit<8>    ttl;
+    bit<8>    protocol;
+    bit<16>   hdrChecksum;
+    ip4Addr_t srcAddr;
+    ip4Addr_t dstAddr;
+}
+
+struct metadata {
+}
+
+struct headers {
+    ethernet_t   ethernet;
+    ipv4_t       ipv4;
+}
+
+/*************************************************************************
+*********************** P A R S E R  ***********************************
+*************************************************************************/
+
+parser MyParser(packet_in packet,
+                out headers hdr,
+                inout metadata meta,
+                inout standard_metadata_t standard_metadata) {
+
+    state start {
+        transition parse_ethernet;
+    }
+
+    state parse_ethernet {
+        packet.extract(hdr.ethernet);
+        transition select(hdr.ethernet.etherType) {
+            TYPE_IPV4: parse_ipv4;
+            default: accept;
+        }
+    }
+
+    state parse_ipv4 {
+        packet.extract(hdr.ipv4);
+        transition accept;
+    }
+}
+
+
+/*************************************************************************
+************   C H E C K S U M    V E R I F I C A T I O N   *************
+*************************************************************************/
+
+control MyVerifyChecksum(inout headers hdr, inout metadata meta) {   
+    apply {  }
+}
+
+
+/*************************************************************************
+**************  I N G R E S S   P R O C E S S I N G   *******************
+*************************************************************************/
+
+control MyIngress(inout headers hdr,
+                  inout metadata meta,
+                  inout standard_metadata_t standard_metadata) {
+    action drop() {
+        mark_to_drop();
+    }
+    
+    action ipv4_forward(macAddr_t dstAddr, egressSpec_t port) {
+        standard_metadata.egress_spec = port;
+        hdr.ethernet.srcAddr = hdr.ethernet.dstAddr;
+        hdr.ethernet.dstAddr = dstAddr;
+        hdr.ipv4.ttl = hdr.ipv4.ttl - 1;
+    }
+
+    table ipv4_lpm {
+        key = {
+            hdr.ipv4.dstAddr: lpm;
+        }
+        actions = {
+            ipv4_forward;
+            drop;
+            NoAction;
+        }
+        size = 1024;
+        default_action = NoAction();
+    }
+    
+    apply {
+        if (hdr.ipv4.isValid()) {
+            ipv4_lpm.apply();
+        }
+    }
+}
+
+/*************************************************************************
+****************  E G R E S S   P R O C E S S I N G   *******************
+*************************************************************************/
+
+control MyEgress(inout headers hdr,
+                 inout metadata meta,
+                 inout standard_metadata_t standard_metadata) {
+    action mark_ecn() {
+        hdr.ipv4.ecn = 3;
+    }
+    apply {
+        if (hdr.ipv4.ecn == 1 || hdr.ipv4.ecn == 2){
+            if (standard_metadata.enq_qdepth >= ECN_THRESHOLD){
+                mark_ecn();
+            }
+        }
+    }
+}
+
+/*************************************************************************
+*************   C H E C K S U M    C O M P U T A T I O N   **************
+*************************************************************************/
+
+control MyComputeChecksum(inout headers hdr, inout metadata meta) {
+     apply {
+	update_checksum(
+	    hdr.ipv4.isValid(),
+            { hdr.ipv4.version,
+	      hdr.ipv4.ihl,
+	      hdr.ipv4.diffserv,
+	      hdr.ipv4.ecn,	
+              hdr.ipv4.totalLen,
+              hdr.ipv4.identification,
+              hdr.ipv4.flags,
+              hdr.ipv4.fragOffset,
+              hdr.ipv4.ttl,
+              hdr.ipv4.protocol,
+              hdr.ipv4.srcAddr,
+              hdr.ipv4.dstAddr },
+            hdr.ipv4.hdrChecksum,
+            HashAlgorithm.csum16);
+    }
+}
+
+/*************************************************************************
+***********************  D E P A R S E R  *******************************
+*************************************************************************/
+
+control MyDeparser(packet_out packet, in headers hdr) {
+    apply {
+        packet.emit(hdr.ethernet);
+        packet.emit(hdr.ipv4);
+    }
+}
+
+/*************************************************************************
+***********************  S W I T C H  *******************************
+*************************************************************************/
+
+V1Switch(
+MyParser(),
+MyVerifyChecksum(),
+MyIngress(),
+MyEgress(),
+MyComputeChecksum(),
+MyDeparser()
+) main;

exercises/other/ecn/topology.json

@@ -0,0 +1,18 @@
+{
+    "hosts": [
+        "h1",
+        "h2",
+        "h3",
+        "h11",
+        "h22"
+    ],
+    "switches": {
+        "s1": { "runtime_json" : "s1-runtime.json" },
+        "s2": { "runtime_json" : "s2-runtime.json" },
+        "s3": { "runtime_json" : "s3-runtime.json" }
+    },
+    "links": [
+              ["h1", "s1"], ["h11", "s1"], ["s1", "s2", "0", 0.5], ["s1", "s3"],
+              ["s3", "s2"], ["s2", "h2"], ["s2", "h22"], ["s3", "h3"]
+    ]
+}