[HICN-708] Rebase with master

Signed-off-by: Enrico Loparco (eloparco) <eloparco@cisco.com>
Change-Id: I2122e1d61dd3b2e039972624ffbdbcb3c5610159

5 files changed, 204 insertions, 117 deletions

diff --git a/docs/doxygen/CMakeLists.txt b/docs/doxygen/CMakeLists.txt
new file mode 100644
index 000000000..8da74995b
--- /dev/null
+++ b/docs/doxygen/CMakeLists.txt
@@ -0,0 +1,35 @@
+# add a target to generate API documentation with Doxygen
+find_package(Doxygen)
+option(BUILD_DOCUMENTATION "Create and install the HTML based API documentation (requires Doxygen)" ${DOXYGEN_FOUND})
+
+if(BUILD_DOCUMENTATION)
+    if(NOT DOXYGEN_FOUND)
+        message(FATAL_ERROR "Doxygen is needed to build the documentation.")
+    endif()
+
+    set(doxy_main_page ${CMAKE_CURRENT_SOURCE_DIR}/../../README.md)
+    set(doxyfile_in ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+    set(doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+    # extract version from git
+    execute_process(
+      COMMAND git describe --long --match v*
+      WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+      OUTPUT_VARIABLE VERSION
+      OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+
+    if (NOT VERSION)
+      set(VERSION "v1.0-1-gcafe")
+    endif()
+
+    configure_file(${doxyfile_in} ${doxyfile} @ONLY)
+
+    add_custom_target(doc
+        COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Generating API documentation with Doxygen"
+        VERBATIM)
+
+    install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION share/doc OPTIONAL)
+endif()
diff --git a/docs/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in
new file mode 100644
index 000000000..6f152323d
--- /dev/null
+++ b/docs/doxygen/Doxyfile.in
@@ -0,0 +1,12 @@
+PROJECT_NAME           = "Hybrid ICN (hICN) plugin"
+PROJECT_NUMBER         = @VERSION@
+STRIP_FROM_PATH        = @PROJECT_SOURCE_DIR@ \
+                         @PROJECT_BINARY_DIR@
+INPUT                  = @doxy_main_page@ \
+                         @PROJECT_SOURCE_DIR@ \
+                         @PROJECT_BINARY_DIR@
+FILE_PATTERNS          = *.md \
+                         *.h \
+                         *.hpp
+RECURSIVE              = YES
+USE_MDFILE_AS_MAINPAGE = @doxy_main_page@
diff --git a/docs/source/control.md b/docs/source/control.md
index 07010a8d1..9564a23af 100644
--- a/docs/source/control.md
+++ b/docs/source/control.md
@@ -149,60 +149,17 @@ controler_rpcs_instances.xml in the yang-model. Here you can find the content:
     <len>30</len>
 </route-get>
 
-<route-del xmlns="urn:sysrepo:hicn">
-    <prefix0>10</prefix0>
-    <prefix1>20</prefix1>
-    <len>30</len>
-</route-del>
-
-<route-nhops-add xmlns="urn:sysrepo:hicn">
-    <prefix0>10</prefix0>
-    <prefix1>20</prefix1>
-    <len>30</len>
-    <face_ids0>40</face_ids0>
-    <face_ids1>50</face_ids1>
-    <face_ids2>60</face_ids2>
-    <face_ids3>70</face_ids3>
-    <face_ids4>80</face_ids4>
-    <face_ids5>90</face_ids5>
-    <face_ids6>100</face_ids6>
-    <n_faces>110</n_faces>
-</route-nhops-add>
-
-<route-nhops-del xmlns="urn:sysrepo:hicn">
-    <prefix0>10</prefix0>
-    <prefix1>20</prefix1>
-    <len>30</len>
-    <faceid>40</faceid>
-</route-nhops-del>
-
-<face-ip-params-get xmlns="urn:sysrepo:hicn">
+<face-params-get xmlns="urn:sysrepo:hicn">
     <faceid>10</faceid>
-</face-ip-params-get>
-
-<face-ip-add xmlns="urn:sysrepo:hicn">
-    <nh_addr0>10</nh_addr0>
-    <nh_addr1>20</nh_addr1>
-    <swif>30</swif>
-</face-ip-add>
+</face-params-get>
 
-<face-ip-del xmlns="urn:sysrepo:hicn">
-    <faceid>0</faceid>
-</face-ip-del>
+<hicn-enable xmlns="urn:sysrepo:hicn">
+    <prefix>b001::/64</prefix>
+</hicn-enable>
 
-<punting-add xmlns="urn:sysrepo:hicn">
-    <prefix0>10</prefix0>
-    <prefix1>20</prefix1>
-    <len>30</len>
-    <swif>40</swif>
-</punting-add>
-
-<punting-del xmlns="urn:sysrepo:hicn">
-    <prefix0>10</prefix0>
-    <prefix1>20</prefix1>
-    <len>30</len>
-    <swif>40</swif>
-</punting-del>
+<hicn-disable xmlns="urn:sysrepo:hicn">
+    <prefix>b001::/64</prefix>
+</hicn-disable>
 ```
 
 #### Run the plugin
diff --git a/docs/source/packethicn.md b/docs/source/packethicn.md
new file mode 100644
index 000000000..cf4976837
--- /dev/null
+++ b/docs/source/packethicn.md
@@ -0,0 +1,127 @@
+HICN Plugin for Wireshark
+===================
+
+The `packethicn` plugin adds support to Wireshark to parse and dissect HICN traffic.
+
+`packethicn` can be compiled and installed in two ways:
+
+1. Alongside HICN, from the HICN root dir (see [Build with HICN](#Build-with-HICN))
+
+2. As a standalone component (see [Standalone build](#Standalone-build))
+
+The second one is preferred if HICN is already installed in the system.
+
+# Supported platforms
+`packethicn` has been tested in
+
+- Ubuntu 18.04
+- Ubuntu 20.04
+- macOS 11.2
+
+Other platforms and architectures may work.
+
+# Installation 
+## Build with HICN
+
+### Dependencies
+
+```bash
+$ sudo add-apt-repository ppa:wireshark-dev/stable
+
+$ sudo apt install -y build-essential cmake wireshark wireshark-dev libgcrypt-dev libgnutls28-dev
+
+```
+
+### Build and install
+
+From the root HICN dir add the `-DBUILD_WSPLUGIN` flag to cmake.
+
+```bash
+$ cd hicn
+
+$ mkdir build; cd build
+
+$ cmake -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl\@1.1 -DBUILD_APPS=ON -DBUILD_WSPLUGIN=ON ..
+
+$ make -j`nproc`
+
+$ sudo make install
+
+```
+
+## Standalone build
+### Linux (Ubuntu)
+
+#### Install dependencies
+```bash
+$ sudo add-apt-repository ppa:wireshark-dev/stable
+
+$ curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash
+
+$ sudo apt install -y build-essential cmake libhicn-dev wireshark wireshark-dev libgcrypt-dev libgnutls28-dev
+
+```
+#### Compile and install HICN plugin
+```bash
+$ cd packethicn
+
+$ mkdir build; cd build
+
+$ cmake ..
+
+$ make
+
+$ sudo make install
+```
+
+
+### macOS
+If installing wireshark via brew use the `./install_macos.sh` script as shown below:
+
+```bash
+$ brew tap icn-team/hicn-tap
+
+$ brew install hicn
+
+$ brew install wireshark
+
+$ brew install cask wireshark
+
+$ cd packethicn
+
+$ ./install_macos.sh
+```
+
+Otherwise (if wireshark was compiled from sources) you can follow the setup for Linux:
+
+```bash
+$ cd packethicn
+
+$ mkdir build; cd build
+
+$ cmake ..
+
+$ make
+
+$ sudo make install
+```
+
+# Usage
+
+## Filters
+
+| Filter | Description | Example |
+| --- | --- | --- |
+| `hicn`  | HICN traffic only  | *hicn* |
+| `hicn.l3.src`  | Source address / Name Prefix (of data)  | *hicn.l3.src == b001::a8f:ae2a:bd5b:0:0* |
+| `hicn.l3.dst`  | Destination address / Name Prefix (of interest)  | *hicn.l3.dst == b001::a8f:ae2a:bd5b:1111:0* |
+| `hicn.l4.namesuffix `  | Name Suffix  | *hicn.l4.namesuffix == 0x21* |
+| `hicn.l4.pathlabel `  | Path Label  | *hicn.l4.pathlabel == 0xbb* |
+| `hicn.l4.timescale `  | Timescale  | *hicn.l4.timescale == 4* |
+| `hicn.l4.flags `  | Flags  | *hicn.l4.flags == 0x42* |
+| `hicn.l4.flags.id `  |  ID Flag | *hicn.l4.flags.<span></span>id == 1* |
+| `hicn.l4.flags.man `  |  MAN Flag | *hicn.l4.flags.man == 0* |
+| `hicn.l4.flags.sig `  | SIG Flag | *hicn.l4.flags.sig == 0* |
+| `hicn.l4.ldr `  | Loss Detection and Recovery | *hicn.l4.ldr > 0* |
+| `hicn.l4.csum `  | Checksum | *hicn.l4.csum > 0* |
+| `hicn.l4.lifetime `  | Lifetime | *hicn.l4.lifetime == 1000* |
diff --git a/docs/source/vpp-plugin.md b/docs/source/vpp-plugin.md
index f93479da8..7f49cd8b9 100644
--- a/docs/source/vpp-plugin.md
+++ b/docs/source/vpp-plugin.md
@@ -188,40 +188,6 @@ sudo vppctl
 vpp# hicn ?
 ```
 
-`hicn control param`: configures the internal parameter of the hICN plugin.
-This command must be run before hicn control start.
-
-```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)
-  <portion to reserved to app>  :set the portion of CS to reserve to application running locally on the forwarder. Default is 30% of the cs size.
-```
-
-`hicn control start`: starts the hICN plugin in VPP.
-
-`hicn control stop` : stops the hICN plugin in VPP. Currently not supported.
-
-`hicn face app` : manipulates producer and consumer application faces in the forwarder.
-
-```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.
-
-```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
-  <sw_if>                     :software interface on thop of which we create the face
-  <face_id>                   :id of the face to remove
-```
-
 `hicn face show`: list the available faces in the forwarder.
 
 ```bash
@@ -230,28 +196,6 @@ hicn face show [<face_id>| type <ip/udp>]
   <ip/udp>                    :shows all the ip or udp faces available
 ```
 
-`hicn face udp`: manipulates udp application faces in the forwarder.
-
-```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
-  <dst_address>             :the IPv4 or IPv6 address of the remote system
-  <dst_port>                :the remote UDP port
-  <sw_if>                   :software interface on thop of which we create the face
-  <face_id>                 :id of the face to remove
-
-```
-
-`hicn fib`: manipulates hicn fib entries.
-
-```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.
 
 ```bash
@@ -291,6 +235,21 @@ hicn strategy mw set prefix <prefix> face <face_id> weight <weight>
   <weight>                       :weight
 ```
 
+`hicn enable`: enable hICN forwarding pipeline for an ip prefix.
+
+```bash
+hicn enable <prefix>
+  <prefix>                      :prefix for which the hICN forwarding pipeline is enabled
+```
+
+`hicn disable`: disable hICN forwarding pipeline for an ip prefix.
+
+```bash
+hicn enable <prefix>
+  <prefix>                      :prefix for which the hICN forwarding pipeline is disable
+```
+
+
 #### hICN plugin configuration file
 
 A configuration can be use to setup the hicn plugin when vpp starts.
@@ -328,10 +287,8 @@ forwarders are connected through a dpdk link.
 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
-vpp# hicn face ip add local 2001::2 remote 2001::3 intfc TenGigabitEtherneta/0/0
-vpp# hicn fib add prefix b002::1/64 face 0
-vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/0 type ip
+vpp# ip route add b002::1/64 via remote 2001::3 TenGigabitEtherneta/0/0
+vpp# hicn enable b002::1/64
 ```
 
 #### Forwarder B (server)
@@ -340,8 +297,6 @@ vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/0 type ip
 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
@@ -380,6 +335,7 @@ sudo vppctl
 vpp# set interface ip address TenGigabitEtherneta/0/0 2001::2/64
 vpp# set interface state TenGigabitEtherneta/0/0 up
 vpp# ip route add b001::/64 via 2001::3 TenGigabitEtherneta/0/0
+vpp# ip route add 2001::3 via TenGigabitEtherneta/0/0
 vpp# hicn pgen client src 2001::2 name b001::1/64 intfc TenGigabitEtherneta/0/0
 vpp# exec /<path_to>pg.conf
 vpp# packet-generator enable-stream hicn-pg
@@ -419,8 +375,8 @@ vpp# hicn pgen server name b001::1/64 intfc TenGigabitEtherneta/0/1
 sudo vppctl
 vpp# set interface ip address TenGigabitEtherneta/0/0 2001::2/64
 vpp# set interface state TenGigabitEtherneta/0/0 up
-vpp# hicn face ip add remote 2001::3 intfc TenGigabitEtherneta/0/0
-vpp# hicn fib add prefix b001::/64 face 0
+vpp# ip route add b001::/64 via 2001::3 TenGigabitEtherneta/0/0
+vpp# hicn enable b001::/64
 vpp# create loopback interface
 vpp# set interface state loop0 up
 vpp# set interface ip address loop0 5002::1/64
@@ -442,7 +398,7 @@ vpp# create loopback interface
 vpp# set interface state loop0 up
 vpp# set interface ip address loop0 2002::1/64
 vpp# ip neighbor loop1 2002::2 de:ad:00:00:00:00
-vpp# hicn face ip add remote 2002::2 intfc loop0
-vpp# hicn fib add prefix b001::/64 face 0
+vpp# ip route add b001::/64 via 2002::2 loop0
+vpp# hicn enable b001::/64
 vpp# hicn pgen server name b001::1/64 intfc loop0
 ```