uniformity across exercises

EXERCISE-1.md

@@ -1,10 +1,10 @@
-# Exercise 1: P4Runtime basics
+# Exercise 1: P4Runtime Basics
 
 This exercise provides a hands-on introduction to the P4Runtime API. You will be
 asked to:
 
-1. Take a look at the starter P4 code
-2. Compile it for the BMv2 software switch and understand the output (the P4Info
+1. Look at the P4 starter code
+2. Compile it for the BMv2 software switch and understand the output (P4Info
    and BMv2 JSON files)
 3. Start Mininet with a 2x2 topology of `stratum_bmv2` switches
 4. Use the P4Runtime Shell to manually insert table entries in one of the
@@ -87,7 +87,7 @@ you will notice that we are asking the compiler to:
   It's ok to ignore such warnings here, as they are generated because of a bug
   in p4c.
 
-### Take a look at the compiler output
+### Compiler output
 
 #### bmv2.json
 
@@ -183,7 +183,6 @@ When starting the Mininet container, a set of files related to the execution of
 each `stratum_bmv2` instance is generated in the
 `tmp`directory. Examples include:
 
-
 * `tmp/leaf1/stratum_bmv2.log`: contains the stratum_bmv2 log for switch
   `leaf1`;
 * `tmp/leaf1/chassis-config.txt`: the Stratum "chassis config" file used to
@@ -402,8 +401,8 @@ PING 2001:1:1::b(2001:1:1::b) 56 data bytes
 
 ## Congratulations!
 
-You have completed the first exercise! Leave mininet running, as we will need it
-for following exercises.
+You have completed the first exercise! Leave Mininet running, as you will need it
+for the following exercises.
 
 [p4c]: https://github.com/p4lang/p4c
 [p4runtime-sh]: https://github.com/p4lang/p4runtime-shell

EXERCISE-2.md

@@ -1,13 +1,13 @@
-# Exercise 2: Yang, OpenConfig, and gNMI basics
+# Exercise 2: Yang, OpenConfig, and gNMI Basics
 
 This exercise is designed to give you more exposure to YANG, OpenConfig,
-and gNMI. It is divided in three parts:
+and gNMI. It includes:
 
 1. Understanding the YANG language
 2. Understand YANG encoding
 3. Understanding YANG-enabled transport protocols (using gNMI)
 
-## Part 1: Understanding the YANG language
+## 1. Understanding the YANG language
 
 We start with a simple YANG module called `demo-port` in
 [`yang/demo-port.yang`](./yang/demo-port.yang)
@@ -38,7 +38,9 @@ bash-4.4# pyang -f tree demo-port.yang
 You should see a tree representation of the `demo-port` module. Does this match
 your expectations?
 
-*Extra Credit:* If you finish this quickly, you can try to add a new leaf node
+------
+
+*Extra Credit:* Try to add a new leaf node
 to `port-config` or `port-state` grouping, then rerun `pyang` and see where your
 new leaf was added.
 
@@ -71,15 +73,19 @@ In the interface model, we can see the path to enable or disable an interface:
 
 What is the path to read the number of incoming packets (`in-pkts`) on an interface?
 
-*Extra Credit:* If you have some time, take a look at the models in the
+------
+
+*Extra Credit:* Take a look at the models in the
 `/models` directory or browse them on Github:
 <https://github.com/openconfig/public/tree/master/release/models>
 
 Try to find the description of the `enabled` or `in-pkts` leaf nodes.
 
 *Hint:* Take a look at the `openconfig-interfaces.yang` file.
 
-## Part 2: Understand YANG encoding
+------
+
+## 2. Understand YANG encoding
 
 There is no specific YANG data encoding, but data adhering to YANG models can be
 encoded into XML, JSON, or Protobuf (among other formats). Each of these formats
@@ -145,7 +151,6 @@ bash-4.4# less /proto/tutorial/enums/enums.proto
 You should see an enum for the 10GB speed, along with any other speeds that you
 added if you completed the extra credit above.
 
-------
 
 We can also use `proto_generator` to build the protobuf messages for the
 OpenConfig models that Stratum uses:
@@ -180,6 +185,8 @@ bash-4.4# proto_generator \
 
 You will find `openconfig.proto` and `enums.proto` in the `/proto/openconfig` directory.
 
+------
+
 *Extra Credit:* Try to find the Protobuf message fields used to enable a port or
 get the ingress packets counter in the protobuf messages.
 
@@ -190,6 +197,8 @@ get the ingress packets counter in the protobuf messages.
 `ygot` can also be used to generate Go structs that adhere to the YANG model
 and that are capable of validating the structure, type, and values of data.
 
+------
+
 *Extra Credit:* If you have extra time or are interested in using YANG and Go
 together, try generating Go code for the `demo-port` module.
 
@@ -200,9 +209,11 @@ bash-4.4# generator -output_dir=/goSrc -package_name=tutorial demo-port.yang
 
 Take a look at the Go files in `/goSrc`.
 
+------
+
 You can now quit out of the container (using `Ctrl-D` or `exit`).
 
-## Part 3: Understanding YANG-enabled transport protocols
+## 3. Understanding YANG-enabled transport protocols
 
 There are several YANG-model agnostic protocols that can be used to get or set
 data that adheres to a model, like NETCONF, RESTCONF, and gNMI.
@@ -299,6 +310,8 @@ $ util/gnmi-cli --grpc-addr localhost:50001 get / | util/oc-pb-decoder | less
 The contents of the response should now be easier to read. Scroll down to the first
 `interface`. Is the interface enabled? What is the speed of the port?
 
+------
+
 *Extra credit:* Can you find `in-pkts`? If not, why do you think they are
 missing?
 
@@ -475,8 +488,6 @@ other traffic like NDP messages contributing to the increase.)
 
 You can stop the gNMI subscription using `Ctrl-C`.
 
-------
-
 Finally, we will monitor link events using gNMI's on-change subscriptions.
 
 Start a subscription for the operational status of the first switch's first port:

EXERCISE-3.md

@@ -1,4 +1,4 @@
-# Exercise 3: Using ONOS as the control plane
+# Exercise 3: Using ONOS as the Control Plane
 
 This exercise provides a hands-on introduction to ONOS, where you will learn how
 to:
@@ -11,7 +11,7 @@ to:
 4. Access the ONOS CLI and UI to verify that all `stratum_bmv2` switches have
    been discovered and configured correctly.
 
-### 1. Start ONOS
+## 1. Start ONOS
 
 In a terminal window, type:
 
@@ -89,7 +89,7 @@ There are definitely more apps than defined in `$ONOS_APPS`. That's
 because each app in ONOS can define other apps as dependencies. When loading an
 app, ONOS automatically resolves dependencies and loads all other required apps.
 
-**Disable link discovery service**
+#### Disable link discovery service
 
 Link discovery will be the focus of the next exercise. For now, this service
 lacks support in the P4 program. We suggest you deactivate it for the rest of
@@ -103,12 +103,12 @@ onos> app deactivate lldpprovider
 To exit the ONOS CLI, use `Ctrl-D`. This will stop the CLI process
 but will not affect ONOS itself.
 
-**Restart ONOS in case of errors**
+#### Restart ONOS in case of errors
 
 If anything goes wrong and you need to kill ONOS, you can use command `make
 restart` to restart both Mininet and ONOS.
 
-### 2. Build app and register pipeconf
+## 2. Build app and register pipeconf
 
 Inside the [app/](./app) directory you will find a starter implementation of an
 ONOS app that includes a pipeconf. The pipeconf-related files are the following:
@@ -152,7 +152,7 @@ Alternatively, you can show the list of registered pipeconfs using the ONOS CLI
 onos> pipeconfs
 ```
 
-### 3. Push netcfg to ONOS
+## 3. Push netcfg to ONOS
 
 Now that ONOS and Mininet are running, it's time to let ONOS know how to reach
 the four switches and control them. We do this by using a configuration file
@@ -197,7 +197,7 @@ INFO  [DeviceManager] Device device:leaf1 port [leaf1-eth5](5) status changed (e
 INFO  [DeviceManager] Device device:leaf1 port [leaf1-eth6](6) status changed (enabled=true)
 ```
 
-### 4. Use the ONOS CLI to verify the network configuration
+## 4. Use the ONOS CLI to verify the network configuration
 
 Access the ONOS CLI using `make onos-cli`. Enter the following command to
 verify the network config pushed before:
@@ -277,7 +277,7 @@ types of P4Runtime entities. In this case, you should see 1 group of type
 clone packets to the controller via packet-in. We'll talk more about controller
 packet-in/out in the next session.
 
-### 5. Visualize the topology on the ONOS web UI
+## 5. Visualize the topology on the ONOS web UI
 
 Using the ONF Cloud Tutorial Portal, access the ONOS UI.
 If you are running the VM on your laptop, open up a browser (e.g. Firefox) to
@@ -316,9 +316,10 @@ fields, actions, action parameter bit widths, etc.
 ## Congratulations!
 
 You have completed the third exercise! If you're feeling ambitious,
-you can check the bonus steps below.
+you can do the extra credit steps below.
 
-### Bonus: inspect stratum_bmv2 internal state
+
+### Extra Credit: Inspect stratum_bmv2 internal state
 
 You can use the P4Runtime shell to dump all table entries currently
 installed on the switch by ONOS. In a separate terminal window, start a
@@ -372,7 +373,8 @@ action {
 priority: 40001
 ```
 
-### Bonus: show ONOS gRPC log
+
+### Extra Credit: Show ONOS gRPC log
 
 ONOS provides a debugging feature that dumps all gRPC messages
 exchanged with a device to a file. To enable this feature, type the

EXERCISE-4.md

@@ -1,4 +1,4 @@
-# Exercise 4: Enabling ONOS built-in services
+# Exercise 4: Enabling ONOS Built-in Services
 
 In this exercise, you will integrate ONOS built-in services for link and
 host discovery with your P4 program. Such built-in services are based on the
@@ -15,9 +15,12 @@ The exercise has two parts:
 1. Enable packet I/O and verify link discovery
 2. Host discovery & L2 bridging
 
-But first, let's review how controller packet I/O works with P4Runtime.
 
-## Controller packet I/O with P4Runtime
+## Part 1: Enable packet I/O and verify link discovery
+
+We start by reviewing how controller packet I/O works with P4Runtime.
+
+### Background: Controller packet I/O with P4Runtime
 
 The P4 program under [p4src/main.p4](p4src/main.p4) provides support for
 carrying arbitrary metadata in P4Runtime `PacketIn` and `PacketOut` messages.
@@ -52,7 +55,6 @@ Similarly, when Stratum receives a P4Runtime `PacketOut` message, it uses the
 values found in the `PacketOut`'s metadata fields to serialize and prepend a
 `cpu_out_header_t` to the frame before feeding it to the pipeline parser.
 
-## Part 1: enable packet I/O and verify link discovery
 
 ### 1. Modify P4 program
 
@@ -315,7 +317,7 @@ In the following, you will be asked to enable the app's `L2BridgingComponent`,
 and to verify that host discovery works by pinging hosts on Mininet. But before,
 it's useful to review how the starter code implements L2 bridging.
 
-### Overview: our implementation of L2 bridging
+### Background: Our implementation of L2 bridging
 
 To make things easier, the starter code assumes that hosts of a given subnet are
 all connected to the same leaf, and two interfaces of two different leaves

EXERCISE-5.md

@@ -1,10 +1,10 @@
-# Exercise 5: IPv6 routing
+# Exercise 5: IPv6 Routing
 
 In this exercise, you will be modifying the P4 program and ONOS app to add
 support for IPv6-based (L3) routing between all hosts connected to the fabric,
 with support for ECMP to balance traffic flows across multiple spines.
 
-## Overview
+## Background
 
 ### Requirements
 
@@ -79,9 +79,7 @@ mininet> h2 ip -6 n
 2001:1:2::ff dev h2-eth0  FAILED
 ```
 
-## Exercise steps
-
-### 1. Modify P4 program
+## 1. Modify P4 program
 
 The first step will be to add new tables to `main.p4`.
 
@@ -202,7 +200,7 @@ Make sure to address any compiler errors before continuing.
 
 At this point, our P4 pipeline should be ready for testing.
 
-### 2. Run PTF tests
+## 2. Run PTF tests
 
 Tests for the IPv6 routing behavior are located in `ptf/tests/routing.py`. Open
 that file up and modify wherever requested (look for `TODO EXERCISE 5`).
@@ -232,7 +230,7 @@ tests of the previous exercises as well.
 
 If all tests succeed, congratulations! You can move to the next step.
 
-### 3. Modify ONOS app
+## 3. Modify ONOS app
 
 The last part of the exercise is to update the starter code for the routing
 components of our ONOS app, located here:
@@ -301,7 +299,7 @@ pipeline configuration has been set and the `Ipv6RoutingComponent` and
 harmful messages (`make onos-log`). If needed, take a look at section **Appendix
 A: Understanding ONOS error logs** at the end of this exercise.
 
-### 4. Test IPv6 routing on Mininet
+## 4. Test IPv6 routing on Mininet
 
 #### Verify ping
 

EXERCISE-6.md

@@ -4,6 +4,8 @@ In this exercise, you will be implementing a simplified version of segment
 routing, a source routing method that steers traffic through a specified set of
 nodes.
 
+## Background
+
 This exercise is based on an IETF draft specification called SRv6, which uses
 IPv6 packets to frame traffic that follows an SRv6 policy. SRv6 packets use the
 IPv6 routing header, and they can either encapsulate IPv6 (or IPv4) packets
@@ -100,9 +102,8 @@ In our implementation, we simplify these types into two roles:
 For more details, you can read the draft specification here:
 https://tools.ietf.org/id/draft-filsfils-spring-srv6-network-programming-06.html
 
-## Exercise steps
 
-### 1. Adding tables for SRv6
+## 1. Adding tables for SRv6
 
 We have already defined the SRv6 header as well as included the logic for
 parsing the header in `main.p4`.
@@ -121,7 +122,7 @@ entries to forward traffic after the SRv6 policy is applied). You can also apply
 the PSP behavior as part of your `apply` logic because we will always be
 applying it if we are the penultimate SID.
 
-### 2. Testing the pipeline with Packet Test Framework (PTF)
+## 2. Testing the pipeline with Packet Test Framework (PTF)
 
 In this exercise, you will be modifying tests in [srv6.py](ptf/tests/srv6.py) to
 verify the SRv6 behavior of the pipeline.
@@ -171,7 +172,7 @@ $ make p4-test
 
 Now we have shown that we can install basic rules and pass SRv6 traffic using BMv2.
 
-### 3. Building the ONOS App
+## 3. Building the ONOS App
 
 For the ONOS application, you will need to update `Srv6Component.java` in the
 following ways:
@@ -198,7 +199,7 @@ reload the app:
 $ make app-build app-reload
 ```
 
-### 4. Inserting SRv6 policies
+## 4. Inserting SRv6 policies
 
 The next step is to show that traffic can be steered using an SRv6 policy.
 
@@ -270,7 +271,7 @@ the specified spine.
 
 <img src="img/srv6-ping-2.png" alt="SRv6 Ping Test" width="335"/>
 
-### Debugging and Clean Up
+## 5. Debugging and Clean Up
 
 If you need to remove your SRv6 policies, you can use the `srv6-clear` command
 to clear all SRv6 policies from a specific device. For example to remove flows