[HICN-533] Update and format documentation

This patch fixes misspells, improves readability and tries to make the different
source files consistent between each other.

It also updates hiperf usage and hicn + VPP installation (in utils.md) and fixes
some mistakes related to collectd plugins (in telemetry.md).

Change-Id: I100a1c7e40dbe9c485ae4548ffc653765f4421b9
Signed-off-by: Olivier Roques <oroques+fdio@cisco.com>

1 files changed, 111 insertions, 90 deletions

diff --git a/docs/source/vpp-plugin.md b/docs/source/vpp-plugin.md
index 772f9a730..0200e38b7 100644
--- a/docs/source/vpp-plugin.md
+++ b/docs/source/vpp-plugin.md
@@ -1,6 +1,4 @@
-# VPP plugin
-
-The hICN-plugin forwarder
+# VPP Plugin
 
 ## Introduction
 
@@ -13,40 +11,46 @@ The plugin provides the following functionalities:
 - Content caching
 - Forwarding strategies
 
-## Quick Start
+## Quick start
+
+All of these commands should be run from the code tree root.
 
+VPP installed with DEB pkg:
 ```bash
-From the code tree root
-
-(VPP installed with DEB pkg)
-$ cd hicn-plugin
-$ mkdir -p build
-$ cd build
-$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr
-$ make
-$ sudo make install
-
-(VPP source code -- build type RELEASE)
-$ cd hicn-plugin
-$ mkdir -p build
-$ cd build
-$ cmake .. -DVPP_HOME=<vpp dir>/build-root/install-vpp-native/vpp -DCMAKE_INSTALL_PREFIX=<vpp src>/build-root/install-vpp-native/vpp
-$ make
-$ sudo make install
-
-(VPP source code -- build type DEBUG)
-$ cd hicn-plugin
-$ mkdir -p build
-$ cd build
-$ cmake .. -DCMAKE_BUILD_TYPE=DEBUG -DVPP_HOME=<vpp dir>/build-root/install-vpp_debug-native/vpp -DCMAKE_INSTALL_PREFIX=<vpp src>/build-root/install-vpp_debug-native/vpp
-$ make
-$ sudo make install
+cd hicn-plugin
+mkdir -p build
+cd build
+cmake .. -DCMAKE_INSTALL_PREFIX=/usr
+make
+sudo make install
+```
 
-CMAKE variables:
-- CMAKE_INSTALL_PREFIX -- set the install directory for the hicn-plugin. This is the common path to the lib folder containing vpp_plugins and vpp_api_test_plugins folders. Default is /usr/local.
-- VPP_HOME -- set the directory containing the include and lib directories of vpp.
+VPP source code - build type `RELEASE`:
+```bash
+cd hicn-plugin
+mkdir -p build
+cd build
+cmake .. -DVPP_HOME=<vpp dir>/build-root/install-vpp-native/vpp -DCMAKE_INSTALL_PREFIX=<vpp src>/build-root/install-vpp-native/vpp
+make
+sudo make install
 ```
 
+VPP source code - build type `DEBUG`:
+```bash
+cd hicn-plugin
+mkdir -p build
+cd build
+cmake .. -DCMAKE_BUILD_TYPE=DEBUG -DVPP_HOME=<vpp dir>/build-root/install-vpp_debug-native/vpp -DCMAKE_INSTALL_PREFIX=<vpp src>/build-root/install-vpp_debug-native/vpp
+make
+sudo make install
+```
+
+CMAKE variables:
+- `CMAKE_INSTALL_PREFIX`: set the install directory for the hicn-plugin. This
+  is the common path to the lib folder containing vpp_plugins and
+  vpp_api_test_plugins folders. Default is /usr/local.
+- `VPP_HOME`: set the directory containing the include and lib directories of vpp.
+
 ## Using hICN plugin
 
 ### Dependencies
@@ -55,17 +59,17 @@ Build dependencies:
 
 - VPP 20.01
   - DEB packages (can be found <https://packagecloud.io/fdio/release/install):>
-  - vpp
-  - libvppinfra-dev
-  - vpp-dev
+    - vpp
+    - libvppinfra-dev
+    - vpp-dev
 
 Runtime dependencies:
 
 - VPP 20.01
   - DEB packages (can be found <https://packagecloud.io/fdio/release/install):>
-  - vpp
-  - vpp-plugin-core
-  - vpp-plugin-dpdk (only to use DPDK compatible nics)
+    - vpp
+    - vpp-plugin-core
+    - vpp-plugin-dpdk (only to use DPDK compatible nics)
 
 Hardware support (not mandatory):
 
@@ -73,7 +77,7 @@ Hardware support (not mandatory):
 
 ## Getting started
 
-In order to start, the hICN plugin requires a running instance of VPP
+In order to start, the hICN plugin requires a running instance of VPP.
 The steps required to successfully start hICN are:
 
 - Setup the host to run VPP
@@ -82,25 +86,27 @@ The steps required to successfully start hICN are:
 - Configure VPP interfaces
 - Configure and start hICN
 
-Detailed information for configuring VPP can be found at [https://wiki.fd.io/view/VPP](https://wiki.fd.io/view/VPP).
+Detailed information for configuring VPP can be found at
+[https://wiki.fd.io/view/VPP](https://wiki.fd.io/view/VPP).
 
 ### Setup the host for VPP
 
-Hugepages must be enabled in the system
+Hugepages must be enabled in the system.
 
-```shell
+```bash
 sudo sysctl -w vm.nr_hugepages=1024
 ```
 
-In order to use a DPDK interface, the `uio` and `uio_pci_generic` or `vfio_pci` modules need to be loaded in the kernel
+In order to use a DPDK interface, the `uio` and `uio_pci_generic` or `vfio_pci`
+modules need to be loaded in the kernel.
 
-```shell
+```bash
 sudo modprobe uio
 sudo modprobe uio_pci_generic
 sudo modprobe vfio_pci
 ```
 
-If the DPDK interface we want to assign to VPP is up, we must bring it down
+If the DPDK interface we want to assign to VPP is up, we must bring it down:
 
 ```bash
 sudo ifconfig <interface_name> down
@@ -114,10 +120,10 @@ sudo ip link set <interface_name> down
 
 ### Configure VPP
 
-The file /etc/VPP/startup.conf contains a set of parameters to setup VPP at startup.
-The following example sets up VPP to use a DPDK interfaces:
+The file `/etc/VPP/startup.conf` contains a set of parameters to setup VPP
+at startup. The following example sets up VPP to use a DPDK interface:
 
-``` shell
+```bash
 unix {
   nodaemon
   log /tmp/vpp.log
@@ -150,37 +156,42 @@ plugins {
 }
 ```
 
-Where `0000:08:00.0` must be replaced with the actual PCI address of the DPDK interface
+`0000:08:00.0` must be replaced with the actual PCI address of the DPDK
+interface.
 
 ### Start VPP
 
 VPP can be started as a process or a service:
 
-``` shell
-Start VPP as a service in Ubuntu 16.04
-$ sudo systemctl start vpp
-
-Start VPP as a process in both 16.04
-$ sudo vpp -c /etc/vpp/startup.conf
+Start VPP as a service in Ubuntu 16.04+:
+```bash
+sudo systemctl start vpp
+```
 
+Start VPP as a process:
+```bash
+sudo vpp -c /etc/vpp/startup.conf
 ```
 
 ### Configure hICN plugin
 
-The hICN plugin can be configured either using the VPP command-line interface (CLI), through a configuration file or through the VPP binary api
+The hICN plugin can be configured either using the VPP command-line interface
+(CLI), through a configuration file or through the VPP binary API.
 
 #### hICN plugin CLI
 
-The CLI commands for the hICN plugin start all with the hicn keyword. To see the full list of command available type:
+The CLI commands for the hICN plugin start all with the `hicn` keyword.
+To see the full list of command available type:
 
-``` shell
-$ sudo vppctl
+```bash
+sudo vppctl
 vpp# hicn ?
 ```
 
-`hicn control param`: configures the internal parameter of the hICN plugin. This command must be run before hicn control start.
+`hicn control param`: configures the internal parameter of the hICN plugin.
+This command must be run before hicn control start.
 
-```shell
+```bash
 hicn control param { pit { size <entries> | { dfltlife | minlife | maxlife } <seconds> } | cs {size <entries> | app <portion to reserved to app>} }
   <entries>                     :set the maximum number of entry in the PIT or CS. Default for PIT is 131072, for CS is 4096. CS size cannot be grater than PIT size. Moreover CS size must be smaller than (# of vlib buffer - 8196).
   <seconds>                     :set the default, maximum or minimum lifetime of pit entries. Default value 2s (default), 0.2s (minumum), 20s (maximum)
@@ -193,18 +204,17 @@ hicn control param { pit { size <entries> | { dfltlife | minlife | maxlife } <se
 
 `hicn face app` : manipulates producer and consumer application faces in the forwarder.
 
-```shell
+```bash
 hicn face app {add intfc <sw_if> {prod prefix <hicn_prefix> cs_size <size_in_packets>} {cons}} | {del <face_id>}
   <sw_if>                     :software interface existing in vpp on top of which to create an application face
   <hicn_prefix>               :prefix to bound to the producer application face. Only content matching the prefix will be allowed through such face.
   <size_in_packets>           :content store size associated to the producer face.
   <face_id>                   :id of the face to remove
-
 ```
 
 `hicn face ip`: manipulates ip application faces in the forwarder.
 
-```shell
+```bash
 hicn face ip {add [local <src_address>] remote <dst_address> intfc <sw_if>} | {del id <face_id>}
   <src_address>               :the IPv4 or IPv6 local IP address to bind to (not mandatory, if not specified the local address is one of the address assigned to sw_if)
   <dst_address>               :the IPv4 or IPv6 address of the remote system
@@ -214,7 +224,7 @@ hicn face ip {add [local <src_address>] remote <dst_address> intfc <sw_if>} | {d
 
 `hicn face show`: list the available faces in the forwarder.
 
-```shell
+```bash
 hicn face show [<face_id>| type <ip/udp>]
   <face_id>                   :face id of which we want to display the informations
   <ip/udp>                    :shows all the ip or udp faces available
@@ -222,7 +232,7 @@ hicn face show [<face_id>| type <ip/udp>]
 
 `hicn face udp`: manipulates udp application faces in the forwarder.
 
-```shell
+```bash
 hicn face udp {add src_addr <src_address> port <src_port > dst_addr <dst_address> port <dst_port>} intfc <sw_if> | {del id <face_id>}
   <src_address>             :the IPv4 or IPv6 local IP address to bind to
   <src_port>                :the local UDP port
@@ -235,16 +245,16 @@ hicn face udp {add src_addr <src_address> port <src_port > dst_addr <dst_address
 
 `hicn fib`: manipulates hicn fib entries.
 
-```shell
+```bash
 hicn fib {{add | delete } prefix <prefix> face <face_id> } | set strategy <strategy_id> prefix <prefix>
   <prefix>                  :prefix to add to the FIB
   <face_id>                 :face id to add as nexto hop in the FIB entry
   <strategy_id>             :set a strategy for the corresponding prefix
 ```
 
-`hicn pgen client`: set an vpp forwarder as an hicn packet generator client
+`hicn pgen client`: set an vpp forwarder as an hicn packet generator client.
 
-```shell
+```bash
 hicn pgen client fwd <ip|hicn> src <addr> n_ifaces <n_ifaces> name <prefix> lifetime <interest-lifetime> intfc <data in-interface> max_seq <max sequence number> n_flows <number of flows>
   <ip|hicn>                 :set if the underlying forwarder is configured as ip or hicn
   <src_addr>                :source address to use in the interests, i.e., the locator for routing the data packet back
@@ -256,9 +266,9 @@ hicn pgen client fwd <ip|hicn> src <addr> n_ifaces <n_ifaces> name <prefix> life
   <number of flows>         :emulate multiple flows downloaded in parallel
 ```
 
-`hicn pgen server`: set an vpp forwarder as an hicn packet generator client
+`hicn pgen server`: set an vpp forwarder as an hicn packet generator client.
 
-```shell
+```bash
 hicn pgen server fwd <ip|hicn> name <prefix> intfc <interest in-interface> size <payload_size>
   <ip|hicn>                     :set if the underlying forwarder is configured as ip or hicn
   <prefix>                      :prefix to use to reply to interest
@@ -266,9 +276,9 @@ hicn pgen server fwd <ip|hicn> name <prefix> intfc <interest in-interface> size
   <payload_size>                :size of the data payload
 ```
 
-`hicn punting`: manipulates punting rules
+`hicn punting`: manipulates punting rules.
 
-```shell
+```bash
 hicn punting {add|delete} prefix <prefix> intfc <sw_if> {type ip | type <udp4|udp6> src_port <src_port> dst_port <dst_port>}
   <prefix>                      :prefix to punt to the hICN plugin
   <sw_if>                       :software interface where to apply the punting
@@ -279,7 +289,7 @@ hicn punting {add|delete} prefix <prefix> intfc <sw_if> {type ip | type <udp4|ud
 
 `hicn show`: show forwarder information.
 
-```shell
+```bash
 hicn show [detail] [strategies]
   <detail>                      :shows additional details as pit,cs entries allocation/deallocation
   <strategies>                  :shows only the available strategies int he forwarder
@@ -287,7 +297,7 @@ hicn show [detail] [strategies]
 
 `hicn strategy mw set`: set the weight for a face.
 
-```shell
+```bash
 hicn strategy mw set prefix <prefix> face <face_id> weight <weight>
   <prefix>                      :prefix to which the strategy applies
   <face_id>                     :id of the face to set the weight
@@ -296,9 +306,12 @@ hicn strategy mw set prefix <prefix> face <face_id> weight <weight>
 
 #### hICN plugin configuration file
 
-A configuration can be use to setup the hicn plugin when vpp starts. The configuration file is made of a list of CLI commands. In order to set vpp to read the configuration file, the file /etc/vpp/startup.conf needs to be modified as follows:
+A configuration can be use to setup the hicn plugin when vpp starts.
+The configuration file is made of a list of CLI commands. In order to set vpp
+to read the configuration file, the file `/etc/vpp/startup.conf` needs to be
+modified as follows:
 
-```shell
+```bash
 unix {
   nodaemon
   log /tmp/vpp.log
@@ -309,16 +322,23 @@ unix {
 
 #### hICN plugin binary API
 
-The binary api, or the vapi, can be used as well to configure the hicn plugin. For each cli command there is a corresponding message in the binary api. The list of messages is available in the file hicn.api (located in hicn/hicn-plugin/src/)
+The binary api, or the vapi, can be used as well to configure the hicn plugin.
+For each CLI command there is a corresponding message in the binary api.
+The list of messages is available in the file hicn.api (located in
+`hicn/hicn-plugin/src/`).
 
-### Example: consumer and producer Ping
+### Example: consumer and producer ping
 
-In this example, we connect two vpp forwarders, A and B, each of them running the hicn plugin. On top of forwarder A we run the ping_client application, on top of forwarder B we run the ping_server application. Each application connects to the underlying forwarder through a memif-interface. The two forwarders are connected through a dpdk link.
+In this example, we connect two vpp forwarders, A and B, each of them running
+the hicn plugin. On top of forwarder A we run the `ping_client` application,
+on top of forwarder B we run the `ping_server` application. Each application
+connects to the underlying forwarder through a memif-interface. The two
+forwarders are connected through a dpdk link.
 
-#### Forwarder A
+#### Forwarder A (client)
 
-```shell
-$ sudo vppctl
+```bash
+sudo vppctl
 vpp# set interface ip address TenGigabitEtherneta/0/0 2001::2/64
 vpp# set interface state TenGigabitEtherneta/0/0 up
 vpp# hicn control start
@@ -327,24 +347,25 @@ vpp# hicn fib add prefix b002::1/64 face 0
 vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/0 type ip
 ```
 
-#### Forwarder B
+#### Forwarder B (server)
 
-```shell
-$ sudo vppctl
+```bash
+sudo vppctl
 vpp# set interface ip address TenGigabitEtherneta/0/1 2001::3/64
 vpp# set interface state TenGigabitEtherneta/0/1 up
 vpp# hicn control start
 vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/1 type ip
 ```
 
-Once the two forwarder are started, run the ping_server application on the host where the forwarder B is running
+Once the two forwarder are started, run the `ping_server` application on the
+host where the forwarder B is running:
 
-```shell
+```bash
 sudo ping_server -n b002::1
 ```
 
-and the client on the host where forwarder B is running
+Then `ping_client` on the host where forwarder B is running:
 
-```shell
+```bash
 sudo ping_client -n b002::1
 ```