Merge "[HICN-512] documentation bundle using sphinx"

2 files changed, 0 insertions, 599 deletions

diff --git a/ctrl/facemgr/doc/interface.md b/ctrl/facemgr/doc/interface.md
deleted file mode 100644
index c7168ef23..000000000
--- a/ctrl/facemgr/doc/interface.md
+++ /dev/null
@@ -1,358 +0,0 @@
-# Face manager : Interfaces
-
-## Overview
-
-The architecture of the face manager is built around the concept of interfaces,
-which allows for a modular and extensible deployment.
-
-Interfaces are used to implement in isolation various sources of information
-which help with the construction of faces (such as network interface and service
-discovery), and with handling the heterogeneity of host platforms.
-
-
-### Platform and supported interfaces
-
-Currently, Android, Linux and MacOS are supported through the following
-interfaces:
-
-- hicn-light [Linux, Android, MacOS, iOS]
-    An interface to the hicn-light forwarder, and more specifically to the Face
-    Table and FIB data structures. This component is responsible to effectively
-    create, update and delete faces in the forwarder, based on the information
-    provided by third party interfaces, plus adding default routes for each of
-    the newly created face. The communication with the forwarder is based on the
-    hicn control library (`libhicnctrl`).
-
-- netlink [Linux, Android]
-    The default interface on Linux systems (including Android) to communicate
-    with the kernel and receive information from various sources, including link
-    and address information (both IPv4 and IPv6) about network interfaces.
-
-- android\_utility [Android only]
-    Information available through Netlink is limited with respect to cellular
-    interfaces. This component allows querying the Android layer through SDK
-    functions to get the type of a given network interface (Wired, WiFi or
-    Cellular).
-
-- bonjour [Linux, Android]
-    This component performs remote service discovery based on the bonjour
-    protocol to discover a remote hICN forwarder that might be needed to
-    establish overlay faces.
-
-- network\_framework [MacOS, iOS]
-
-    This component uses the recommended Network framework on Apple devices,
-    which provided all required information to query faces in a unified API:
-    link and address information, interface types, and bonjour service
-    discovery.
-
-
-### Architectural overview
-
-#### Facelets
-
-TODO:
-- Key attributes (netdevice and protocol family)
-- Facelet API
-
-#### Events
-
-TODO
-
-#### Facelet cache & event scheduling
-
-TODO:
- - Facelet cache
- - Joins
- - How synchronization work
-
-### Interface API
-
-TODO
-
-## Developing a new interface
-
-### Dummy template
-
-The face manager source code includes a template that can be used as a skeleton
-to develop new faces. It can be found in `src/interface/dummy/dummy.{h,c}`. Both
-include guard and specific interface functions are prefixed by a (short)
-identifier which acts as a namespace for interface specific code (in our case
-the string 'dummy\_').
-
-Registration and instanciation of the different interfaces is currently done at
-compile time in the file `src/api.c`, and the appropriate hooks to use the dummy
-interface are avaialble in the code between `#if 0/#endif` tags.
-
-#### Interface template header; configuration parameters
-
-All interfaces have a standard interface defined in `src/interface.{h,c}`, and
-as such the header file is only used to specify the configuration parameters of
-the interface, if any.
-
-In the template, these configuration options are empty:
-```
-/*
- * Configuration data
- */
-typedef struct {
-    /* ... */
-} dummy_cfg_t;
-```
-
-#### Overview of the interface template
-
-The file starts with useful includes:
-- the global include `<hicn/facemgr.h>` : this provides public facing elements
-    of the face manager, such the standard definition of faces (`face_t` from
-    `libhicnctrl`), helper classes (such as `ip_address_t` from `libhicn`), etc.
-- common.h
-- facelet.h : facelets are the basic unit of communication between the face
-manager and the different interfaces. They are used to construct the faces
-incrementally.
-- interface.h : the parent class of interfaces, such as the current dummy
-interface.
-
-Each interface can hold a pointer to an internal data structure, which is
-declared as follows:
-```
-/*
- * Internal data
- */
-typedef struct {
-    /* The configuration data will likely be allocated on the stack (or should
-     * be freed) by the caller, we recommend to make a copy of this data.
-     * This copy can further be altered with default values.
-     */
-    dummy_cfg_t cfg;
-
-    /* ... */
-
-    int fd; /* Sample internal data: file descriptor */
-} dummy_data_t;
-```
-
-We find here a copy of the configuration settings (which allows the called to
-instanciate the structure on the stack), as well as a file descriptor
-(assuming most interfaces will react on events on a file descriptor).
-
-The rest of the file consists in the implementation of the interface, in
-particular the different function required by the registration of a new
-interface to the system. They are grouped as part of the `interface_ops_t` data
-structure declared at the end of the file:
-
-```
-interface\_ops\_t dummy\_ops = {
-    .type = "dummy",
-    .initialize = dummy_initialize,
-    .finalize = dummy_finalize,
-    .callback = dummy_callback,
-    .on_event = dummy_on_event,
-};
-```
-
-The structure itself is declared and documented in `src/interface.h`
-```
-/**
- * \brief Interface operations
- */
-typedef struct {
-    /** The type given to the interfaces */
-    char * type;
-    /* Constructor */
-    int (*initialize)(struct interface\_s * interface, void * cfg);
-    /* Destructor */
-    int (*finalize)(struct interface_s * interface);
-    /* Callback upon file descriptor event (iif previously registered) */
-    int (*callback)(struct interface_s * interface);
-    /* Callback upon facelet events coming from the face manager */
-    int (*on_event)(struct interface_s * interface, const struct facelet_s * facelet);
-} interface\_ops\_t;
-```
-
-Such an interface has to be registered first, then one (or multiple) instance(s)
-can be created (see `src/interface.c` for the function prototypes, and
-`src/api.c` for their usage).
-
-- interface registration:
-
-```
-extern interface\_ops\_t dummy\_ops;
-
-/* [...] */
-
-rc = interface\_register(&dummy\_ops);
-if (rc < 0)
-    goto ERR_REGISTER;
-```
-
-- interface instanciation:
-
-```
-#include "interfaces/dummy/dummy.h"
-
-/* [...] */
-
-rc = facemgr_create_interface(facemgr, "dummy0", "dummy", &facemgr->dummy);
-if (rc < 0) {
-    ERROR("Error creating 'Dummy' interface\n");
-    goto ERR_DUMMY_CREATE;
-}
-```
-
-#### Implementation of the interface API
-
-We now quickly go other the different functions, but their usage will be better
-understood through the hands-on example treated in the following section.
-
-In the template, the constructor is the most involved as it need to:
-
-- initialize the internal data structure:
-
-```
-    dummy_data_t * data = malloc(sizeof(dummy_data_t));
-    if (!data)
-        goto ERR_MALLOC;
-    interface->data = data;
-```
-
-- process configuration parameters, eventually setting some default values:
-
-```
-    /* Use default values for unspecified configuration parameters */
-    if (cfg) {
-        data->cfg = *(dummy_cfg_t *)cfg;
-    } else {
-        memset(&data->cfg, 0, sizeof(data->cfg));
-    }
-```
-
-- open an eventually required file descriptor
-
-For the sake of simplicity, the current API only supports a single file
-descriptor per-interface, and it has to be created in the constructor, and
-set as the return value so as to be registered by the system, and added to the
-event loop for read events. A return value of 0 means the interface does not
-require any file descriptor. As usual, a negative return value indicates an
-error.
-
-```
-    data->fd = 0;
-
-    /* ... */
-
-    /*
-     * We should return a negative value in case of error, and a positive value
-     * otherwise:
-     *  - a file descriptor (>0) will be added to the event loop; or
-     *  - 0 if we don't use any file descriptor
-     */
-    return data->fd;
-```
-
-While support for multiple file descriptors might be added in the future, an
-alternative short-term implementation might consider the instanciation of
-multiple interface, as is done for Bonjour in the current codebase, in
-`src/api.c`.
-
-Data reception on the file descriptor will get the callback function called, in
-our case `dummy_callback`. Finally, the destructor `dummy_finalize` should close
-an eventual open file descriptor.
-
-In order to retrieve the internal data structure, that should in particular
-store such a file descriptor, all other function but the constructor can
-dereference it from the interface pointer they receive as parameter:
-
-```
-dummy\_data\_t * data = (dummy\_data\_t*)interface->data;
-```
-
-#### Raising and receiving events
-
-An interface will receive events in the form of a facelet through the `*_on_event`
-function. It can then use the facelet API we have describe above to read
-information about the face.
-
-As this information is declared const, the interface can either create a new
-facelet (identified by the same netdevice and protocol family), or eventually
-clone it.
-
-The facelet event can then be defined and raised to the face maanger for further
-processing through the following code:
-```
-    facelet_set_event(facelet, EVENT_TYPE_CREATE);
-    interface_raise_event(interface, facelet);
-```
-
-Here the event is a facelet creation (`EVENT_TYPE_CREATE`). The full facelet API
-and the list of possible event types is available in `src/facelet.h`
-
-
-#### Integration in the build system
-
-The build system is based on CMake. Each interface should declare its source
-files, private and public header files, as well as link dependencies in the
-local `CMakeLists.txt` file.
-
-TODO: detail the structure of the file
-
-
-### Hands-on example
-
-#### Overview
-
-In order to better illustrate the development of a new interface, we will
-consider the integration of a sample server providing a signal instructing the
-face manager to alternatively use either the WiFi or the LTE interface. The code
-of this server is available in the folder `examples/updownsrv/`, and the
-corresponding client code in `examples/updowncli`.
-
-Communication between client and server is done through unix sockets over an
-abstract namespace (thereby not using the file system, which would cause issues
-on Android). The server listens for client connections, and periodically
-broadcast a binary information to all connected clients, in the form of one byte
-equal to either \0 (which we might interpret as enable LTE, disable WiFi), or \1
-(enable WiFi, disable LTE).
-
-Our objective is to develop a new face manager interface that would listen to
-such event in order to update the administrative status of the current faces.
-This would thus alternatively set the different interfaces admnistratively up
-and down (which takes precedence over the actual status of the interface when
-the forwarder establishes the set of available next hops for a given prefix).
-The actual realization of such queries will be ultimately performed by the
-hicn-light interface.
-
-#### Sample server and client
-
-In the folder containing the source code of hICN, the following commands allow
-to run the sample server:
-
-```
-cd ctrl/facemgr/examples/updownsrv
-make
-./updownsrv
-```
-
-The server should display "Waiting for clients..."
-
-Similar commands allow to run the sample client:
-```
-cd ctrl/facemgr/examples/updowncli
-make
-./updowncli
-```
-
-The client should display "Waiting for server data...", then every couple of
-seconds display either "WiFi" or "LTE".
-
-#### Facemanager interface
-
-An example illustrating how to connect to the dummy service from `updownsrv` is
-provided as the `updown` interface in the facemgr source code.
-
-This interface periodically swaps the status of the LTE interface up and down.
-It is instanciated as part of the facemgr codebase when the code is compiled
-with the ``-DWITH_EXAMPLE_UPDOWN` cmake option.
-
-
-
diff --git a/ctrl/sysrepo-plugins/README.md b/ctrl/sysrepo-plugins/README.md
deleted file mode 100644
index 0940fff67..000000000
--- a/ctrl/sysrepo-plugins/README.md
+++ /dev/null
@@ -1,241 +0,0 @@
-# Sysrepo plugin for hicn-plugin  (2019)
-
-These plugins serve as a data management agent. They provide yang models via
-NETCONF to allow the management of hicn-light, and hicn-plugin which runs in VPP
-instance from out-of-box.
-
-## Software Requirement
-
-- VPP
-
-- sysrepo
-
-- hicn-plugin
-
-- hicn-light
-
-## hICN yang model
-
-You can install the yang model using the following bash script:
-```
-EXIT_CODE=0
-command -v sysrepoctl > /dev/null
-if [ $? != 0 ]; then
-    echo "Could not find command \"sysrepoctl\"."
-     exit ${EXIT_CODE}
-else
-sysrepoctl --install --yang=path_to_hicn_yang_model
-fi
-```
-hicn.yang can be found in the yang-model. It consists of two container nodes:
-hicn-conf and hicn-state. One is used to hold the configuration data (i.e.,
-hicn-conf) and one for providing the state data (i.e., hicn-state). The
-hicn-conf has one node, params, which contains the hICN configuration
-parameters. A controller can configure these parameters through the edit-config RPC
-call. This node can be used to enable and to initialize the hicn-plugin in VPP
-instance. Hicn-state container is used to provide the state data to the
-controller. It consists of state, strategy, strategies, route, and face-ip-params
-nodes with the corresponding leaves. In the hicn model a variety of RPCs are provided
-to allow controller to communicate with the hicn-plugin as well as update the state
-data in hicn-state.
-
-To setup the startup configuration you can use the following script:
-```
-EXIT_CODE=0
-command -v sysrepocfg > /dev/null
-if [ $? != 0 ]; then
-    echo "Could not find command \"sysrepocfg\"."
-     exit ${EXIT_CODE}
-else
-sysrepocfg -d startup -i path_to_startup_xml -f xml hicn
-fi
-```
-
-startup.xml is placed in the yang-model. Here you can find the content:
-```
-<hicn-conf  xmlns="urn:sysrepo:hicn">
-<params>
-    <enable_disable>false</enable_disable>
-    <pit_max_size>-1</pit_max_size>
-    <cs_max_size>-1</cs_max_size>
-    <cs_reserved_app>-1</cs_reserved_app>
-    <pit_dflt_lifetime_sec>-1</pit_dflt_lifetime_sec>
-    <pit_max_lifetime_sec>-1</pit_max_lifetime_sec>
-    <pit_min_lifetime_sec>-1</pit_min_lifetime_sec>
-</params>
-</hicn-conf>
-```
-As can be seen, it contains the leaves of the params in hicn-conf node which is
-used as the startup configuration. This configuration can be changed through the
-controller by subscribing which changes the target to the running state. hicn
-yang model provides a list of RPCs which allows controller to communicate
-directly with the hicn-plugin. This RPCs may also cause the modification in
-state data.
-
-In order to run different RPCs from controller you can use the examples in the
-controler_rpcs_instances.xml in the yang-model. Here you can find the content:
-```
-<node-params-get xmlns="urn:sysrepo:hicn"/>
-
-<node-stat-get xmlns="urn:sysrepo:hicn"/>
-
-<strategy-get xmlns="urn:sysrepo:hicn">
-    <strategy_id>0</strategy_id>
-</strategy-get>
-
-<strategies-get xmlns="urn:sysrepo:hicn"/>
-
-<route-get xmlns="urn:sysrepo:hicn">
-    <prefix0>10</prefix0>
-    <prefix1>20</prefix1>
-    <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">
-    <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-ip-del xmlns="urn:sysrepo:hicn">
-    <faceid>0</faceid>
-</face-ip-del>
-
-<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>
-```
-
-## Run the plugin
-
-Firstly, verify the plugin and binary libraries are located correctly, then run
-the vpp through (service vpp start). Next, run the sysrepo daemon (sysrepod),
-for debug mode: sysrepo -d -l 4 which runs with high verbosity. Then, run the
-sysrepo plugin (sysrepo-plugind), for debug mode: sysrep-plugind -d -l 4 which
-runs with high verbosity. Now, the hicn sysrepo plugin is loaded. Then, run the
-netopeer2-server which serves as NETCONF server.
-
-## Connect from netopeer2-cli
-
-In order to connect through the netopeer client run the netopeer2-cli. Then, follow these steps:
-
-- connect --host XXX --login XXX
-- get (you can get the configuration and operational data)
-- get-config (you can get the configuration data)
-- edit-config --target running --config
-  you can modify the configuration but it needs an xml configuration input
-```
-<hicn-conf  xmlns="urn:sysrepo:hicn">
-<params>
-    <enable_disable>false</enable_disable>
-    <pit_max_size>-1</pit_max_size>
-    <cs_max_size>-1</cs_max_size>
-    <cs_reserved_app>-1</cs_reserved_app>
-    <pit_dflt_lifetime_sec>-1</pit_dflt_lifetime_sec>
-    <pit_max_lifetime_sec>-1</pit_max_lifetime_sec>
-    <pit_min_lifetime_sec>-1</pit_min_lifetime_sec>
-</params>
-</hicn-conf>
-```
-- user-rpc (you can call one of the rpc proposed by hicn model but it needs an xml input)
-
-## Connect from OpenDaylight (ODL) controller
-
-In order to connect through the OpenDaylight follow these procedure:
-
-- run karaf distribution (./opendayligh_installation_folder/bin/karaf)
-- install the required feature list in DOL (feature:install odl-netconf-server
-  odl-netconf-connector odl-restconf-all odl-netconf-topology or
-  odl-netconf-clustered-topology)
-- run a rest client program (e.g., postman or RESTClient)
-- mount the remote netopeer2-server to the OpenDaylight by the following REST API:
-
-PUT http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/hicn-node
-
-with the following body
-```
- <node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
-   <node-id>hicn-node</node-id>
-   <host xmlns="urn:opendaylight:netconf-node-topology">Remote_NETCONF_SERVER_IP</host>
-   <port xmlns="urn:opendaylight:netconf-node-topology">830</port>
-   <username xmlns="urn:opendaylight:netconf-node-topology">username</username>
-   <password xmlns="urn:opendaylight:netconf-node-topology">password</password>
-   <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
-   <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">1</keepalive-delay>
- </node>
-```
-Note that the header files must be set to Content-Type: application/xml, Accept: application/xml.
-
-- send the operation through the following REST API:
-
-POST http://localhost:8181/restconf/operations/network-topology:network-topology/topology/topology-netconf/node/hicn-node/yang-ext:mount/ietf-netconf:edit-config
-
-The body can be used the same as edit-config in netopeer2-cli.
-
-## Connect from Network Services Orchestrator (NSO)
-
-To connect NSO to the netopeer2-server, first, you need to write a NED package
-for your device. The procedure to create NED for hicn is explained in the
-following:
-
-Place hicn.yang model in a folder called hicn-yang-model, and follow these steps:
-
-- ncs-make-package --netconf-ned ./hicn-yang-model ./hicn-nso
-- cd hicn-nso/src; make
-- ncs-setup --ned-package ./hicn-nso --dest ./hicn-nso-project
-- cd hicn-nso-project
-- ncs
-- ncs_cli -C -u admin
-- configure
-- devices authgroups group authhicn default-map remote-name user_name remote-password password
-- devices device hicn address IP_device port 830 authgroup authhicn device-type netconf
-- state admin-state unlocked
-- commit
-- ssh fetch-host-keys
-
-At this point, we are able to connect to the remote device.
-
-## Release note
-
-The current version is compatible with the 19.01 VPP stable and sysrepo 0.7.7.
\ No newline at end of file