summaryrefslogtreecommitdiffstats
path: root/ctrl/facemgr
diff options
context:
space:
mode:
authorMauro Sardara <msardara@cisco.com>2020-02-12 17:03:47 +0000
committerGerrit Code Review <gerrit@fd.io>2020-02-12 17:03:47 +0000
commitf9243a2bf823086404be1c41c7bcc1b27cfab7de (patch)
tree83d34905027616eea2d7cf01d42c0f7769a96589 /ctrl/facemgr
parent38cc8fb5b1c4d315648a5cc53bb0e874d54f436a (diff)
parent56e29ea01914681f394e3a0af4169936079858a7 (diff)
Merge "[HICN-512] documentation bundle using sphinx"
Diffstat (limited to 'ctrl/facemgr')
-rw-r--r--ctrl/facemgr/doc/interface.md358
1 files changed, 0 insertions, 358 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.
-
-
-