doc: Initial high-level architecture

This adds the initial high-level architecture (HLA) document. It
outlines the design decisions taken for the Ouroboros prototype.

2 files changed, 329 insertions, 0 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 00000000..e4e5f6c8
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1 @@
+*~
\ No newline at end of file
diff --git a/doc/highlevelarchitecture.txt b/doc/highlevelarchitecture.txt
new file mode 100644
index 00000000..795ccdf4
--- /dev/null
+++ b/doc/highlevelarchitecture.txt
@@ -0,0 +1,328 @@
+1.  Introduction

+

+This document describes the high-level software architecture of the

+Ouroboros prototype, an implementation of the Recursive InterNetwork

+Architecture (RINA). The high-level architecture described is for an

+implementation in user-space of an Operating System. It identifies the

+different software components and delineates their interactions and

+interfaces. The main focus of Ouroboros is portability, to allow the

+prototype to be deployed on different platforms and in widely varying

+environments.

+

+This document will assume the reader is familiar with RINA

+terminology. Please see the reference model for a more in-depth

+description of RINA.

+

+2.  The Ouroboros Framework

+

+The framework consists of a library, that implements the Recursive

+InterNetwork Architecture.  Applications can make use of the library

+for networking. This is shown in Figure 1. The library offers an API

+to applications so they can make use of the functionality. Apart from

+the library, 2 types of daemon are provided:

+

+- The IPC Resource Manager Daemon, responsible for instantiating new

+IPC Processes, destroying them etc. It is the local management system

+in the processing system that handles IPC requests.

+

+- IPC Process Daemon(s), a daemon that is the instantiation of an IPC

+Process on the processing system.

+

+The library can run the daemons as threads instead of processes if

+needed, for instance when it is deployed on Android, iOS, as a web

+app, ... Multithreading will be supported, so that the daemons can

+spawn as many threads as needed for them to function correctly. The

+high-level architecture is devised in such a way that it tries to

+minimize the multitasking switches.

+

+  +-------------------------+        +-------------------------------+

+  |      Applications       |        | Shell scripts, config files,  |

+  |                         |        | Python scripts, ...           |

+  +-------------------------+        +-------------------------------+

+           | Function calls                   | Function calls

+           v                                  v

+  +-------------------------------------------------------------------+

+  |                       Ouroboros Library                           |

+  +-------------------------------------------------------------------+

+  Function calls ^  | Sockets     |  |     Function calls ^  | Sockets                

+                 |  v             |  |                    |  v

+  +-------------------------+     |  |    +-------------------------+

+  |    IPC Process Daemon   |     |  |    |  IPC Resource Manager   |

+  |                         |     |  |    |         Daemon          |

+  +-------------------------+     |  |    +-------------------------+

+                   Function calls |  | Sockets   

+                                  |  v

+                       +-------------------------+

+                       |      DIF Allocator      |

+                       |         Daemon          |

+                       +-------------------------+

+

+                       Figure 1: Ouroboros library

+

+3. Software components convention

+

+A component in the rest of this document adheres to the conventions

+described in the next paragraph. The aim of this section is to remove

+unnecessary detail from other sections and also to provide a unified

+convention for all the different components. Exceptions to these rules

+are allowed, if explicitly indicated.

+

+typedef uint32_t module_id_t

+

+The module_id_t represents a generic identifier mapped to an integer.

+As a return value, module_id_t should be interpreted as follows:

+

+- value >= 0 Represents a positive answer. The value is opaque for the

+  callee while it has an internal meaning for the caller. The caller

+  uses the id for requesting services (operations) to the caller, the

+  callee may use the id for lookups into its internal data structures.

+  

+- value < 0: Represents an error condition

+

+To further clarify , each component has the following lifecycle:

+

+a. Creation: The caller asks for a creation of a new instance of the

+ component. The callee returns a generic identifier

+ 

+b. Operation(s): The caller asks for an operation. The identifier

+ given during creation is always passed along as input parameter. If

+ the operation was successful, zero is returned. In case of an error,

+ the component returns a negative value. The negative value can be

+ passed to ouroboros_strerror to get a human readable version of the

+ error. The error codes are library global, in the case that the

+ library gets migrated in other libraries, they should coincide with

+ errno.

+ 

+c. Destruction: The caller explicitly asks the callee to release all

+ resources related to the component created in step a). The identifier

+ is passed along as input parameter to identify the correct instance.

+

+4.  Ouroboros Libraries

+

+The Ouroboros library is internally split into different smaller

+libraries. They are the following:

+

+- libouroboros-dev: allows applications to allocate flows to other

+  applications, read/write to these flows, deallocate them and to

+  register and unregister themselves in DIFs.

+

+- libouroboros-cdap: this library implements the Common Distributed

+  Application Protocol, RINA’s application protocol.

+

+- libouroboros-irm: this library exposes the IRM API to allow network

+  administrators to build their own network.

+

+- libouroboros-ipcp: this library allows the IRM to create, destroy,

+  configure IPC Processes.

+

+- libouroboros-da: Allows the IRM to resolve a DAF name to a DAP

+  member and how to reach it through an N-1 DIF..

+

+- libouroboros-common: contains the files that are shared by all other

+  libraries. An example is the file with error codes described in the

+  previous section

+

+- libouroboros-utils: contains all the other files not contained in

+  the other libraries. Examples are the implementations of the data

+  structures described in the previous section

+

+When any of the operations is called, the caller is blocked until it

+the operation has been executed. Since some operations may involve

+sending messages to other processes, proper timeouts will be enforced

+on the operations to avoid blocking processes endlessly.

+

+* libouroboros-common *

+

+This library provides the definitions shared between all other

+libraries. Other framework components such as the IRM and IPCP daemons

+may also use this library and common functionalities between these

+daemons may also be contained within this library.

+

+* libouroboros-dev *

+

+This library provides the RINA IPC API to applications. This is the

+native RINA IPC API that allows application processes to

+register/unregister themselves with DIFs, allocate flows with a

+certain Quality of Service and read/write to them and deallocate them

+when they are no longer necessary.

+

+In the case of a server, one can first request all the available DIFs

+in the processing system. Next, one would register the Application

+Process in selected DIFs. Wildcarding is allowed, for instance * would

+mean any DIF, home.* all home DIFs etc. Upon registration a file

+descriptor is returned. This file descriptor is used for incoming

+flows, upon calling flow_accept with this file descriptor the name of

+the requesting application is provided together with a new file

+descriptor in case of a new flow. The server can then choose to accept

+or deny this new flow by calling flow_alloc_resp. If the flow is

+accepted, the file descriptor can then be read from and written to

+with flow_read and flow_write. To deallocate the flow, flow_dealloc

+can be called.

+

+In the case of a client, one can first request all the available QoS

+cubes that are available for communicating with a server. Optionally,

+one can pass a minimum QoS that is required for the flow. With this

+QoS, flow_alloc can be called to allocate flow. One can also just

+provide a minimum QoS in the flow_alloc call and just accept what the

+network gives you. A file descriptor is provided with which one should

+call flow_alloc_res. If this operation returns a positive value, the

+flow is accepted and one can call flow_read and flow_write. To

+deallocate the flow, flow_dealloc can be called.

+

+* libouroboros-cdap *

+

+This library provides the Common Distributed Application Protocol

+(CDAP) and Common Application Connection Establishment Phase

+(CACEP). CDAP is RINA’s stateless application protocol that allows two

+applications to communicate by using atomic operations: create,

+delete, start, stop, write, read. CACEP is RINA’s authentication

+protocol used when setting up communication between two Application

+Entities (AEs). CACEP/CDAP will have to agree on an abstract syntax

+(protocol version) and a specific encoding to use (concrete

+syntax). The library allows for new CDAP instances to be created by

+passing the flow it can use and a structure with callback

+operations. From then on, the flow can only be written and read from

+by the CDAP instance. To send CDAP messages, once can call any of the

+operations by passing the newly created instance together with the

+appropriate parameters. Upon receipt of a reply to the message sent,

+the corresponding callback operation is called.

+

+* libouroboros-irm *

+

+The IPC Resource Manager allows a network administrator to setup a

+RINA network. The IRM exposes an API so that commands can be given

+from a config file reader, scripts or even a full blown DMS. It allows

+the creation and destruction of IPCPs, it allows to bootstrap or

+enroll IPCPs, and to register and unregister IPCPs in certain DIFs and

+to query their RIB. It is also possible to request all the IPCPs

+currently in the processing system as well as all the possible IPCP

+types.

+

+* libouroboros-ipcp *

+

+The IRM can instantiate, destroy, configure IPC Processes. A new IPC

+Process is created by specifying a name and a type (normal IPCP, shim

+IPCP). If it is the first IPCP in the DIF, it can be bootstrapped by

+providing the required DIF info. If it is not the first IPCP in the

+DIF, it has to enroll with an existing member by calling

+ipcp_enroll. After the new IPCP is configured in one of the two

+described ways, it can be registered and unregistered with the

+required N-1 DIFs. Its RIB can also be queried.

+

+* libouroboros-da *

+

+The DIF allocator allows to resolve a DAF to an distributed

+application process and find a DIF through which it is reachable, or

+if a DIF is not yet available to instantiate a new DIF. In the first

+phase of the implementation only the first case will be supported. In

+the case of a DIF, for enrollment this means that an existing member

+can be resolved by providing a DIF name and that N-1 DIFs can be given

+through which the existing member is reachable.

+

+* libouroboros-utils *

+

+This library contains all the other functionalities not contained in

+the other libraries. This includes implementations of data structures

+such as lists, hashmaps, sets, .... It also includes a logging

+system. As well as wrappers around memory allocation/deallocation

+functions.

+

+5.  IPC Resource Manager

+

+The IRM implements the API provided in libouroboros-irm by opening a

+POSIX local IPC socket that listens to messages sent by the

+libouroboros-irm library. It is a daemon that has 2 functions:

+

+- It acts as a broker between the IPC Processes and applications and

+  checks the validity of requests..

+

+- It allows network administrators to construct their RINA network. It

+  holds a directed acyclic graph with all the IPCPs in the system. It

+  is responsible for correctly cleaning up the IPCPs upon shutdown of

+  the network stack.

+

+6.  IPC Process Daemon

+

+A new IPCP will open a POSIX local IPC socket to listen to messages

+from libouroboros-ipcp and the IRM when its functions are

+called. Every type of IPC Process, whether it is a shim IPCP or a

+normal IPCP, has to provide a factory to instantiate a new IPCP of its

+type. Internally, a normal IPC Process consists of different

+components in order to provide IPC to its user. This section provides

+a short description of every component together with their API.

+

+* Flow Manager *

+

+The flow manager is the component that manages a flow’s

+lifecycle. This is the allocation, deallocation and monitoring of

+every flow. The flow monitor will:

+

+- Find the IPCP in the DIF through which the requested application is

+  available.

+

+- Map the requested QoS to policies

+

+- Negotiate the flow’s characteristics with the destination IPCP,

+  perform access control, ...

+

+- Instantiate an FRCT instance associated with the flow

+

+- Maintain the negotiated QoS of the flow

+

+- Deallocate the flow when requested

+

+* Enrollment *

+

+Enrollment allows an IPCP to join a DIF. If the IPCP is the first IPCP

+in the DIF it is just locally bootstrapped. If it is not, it will

+allocate a flow to an IPCP of the DIF and exchange static and dynamic

+information. An address is also assigned during enrollment. The

+prototype will allow assigning addresses from a flat and a topological

+addressing scheme. After enrollment, the IPCP will be informed about

+its neighbors and will also allocate a flow to them.

+

+* Resource Information Base *

+

+The Resource Information Base is the local view the IPCP has of the

+DIF. It is a partially replicated distributed database. It has a

+certain model that is the same for every IPCP in Ouroboros.  RIB

+Provider The RIB can only be accessed through the RIB provider. Apart

+from providing this access, the RIB provider has a

+publisher/subscriber mechanism. Subscribers can subscribe to certain

+events happening in the DIF and publishers can publish these events.

+

+* Flow and Retransmission Control Task *

+

+The flow and retransmission control task, originally known as the

+Error and Flow Control Protocol, provides the flow with flow control

+and (if needed) retransmission control. It consists of two parts: Data

+Transfer (DT) and Data Transfer Control (DTC). DT is for instance

+concerned with concatenation, multiplexing, reassembly, ... DTC provides

+flow control and retransmission control. DT and DTC communicate with

+each other through a shared state vector.

+

+* Relaying and Multiplexing Task *

+

+The relaying and multiplexing task has a scheduler to allow scheduling

+SDUs for different QoS-cubes. It also checks whether or not an

+incoming PDU was intended for this IPCP. If it is not, it forwards it

+through an N-1 port-id by consulting the PDU Forwarding Function.

+

+* PDU Forwarding Function *

+

+This task implements the policy to be used by the RMT to forward

+PDUs. In the first phase, a link state routing policy will be

+provided, implemented by a PDU Forwarding Table (PFT) and a PDU

+Forwarding Table Generator (PFTG). In later iterations, a routing

+policy based on geometric routing will be added.

+

+7.  DIF Allocator

+

+The DIF allocator implements the API provided in libouroboros-da by

+opening a POSIX local IPC socket that listens to messages sent by the

+IRM. It is a daemon that has 2 functions:

+

+- Resolving a DAF name to a DAP

+

+- Providing an N-1 DIF over which a DAP is reachable

+