From 62d71caa084c40f10bcf9206fad63c82b7eac56c Mon Sep 17 00:00:00 2001 From: Sander Vrijders Date: Thu, 11 Feb 2016 10:41:16 +0100 Subject: doc: Initial high-level architecture This adds the initial high-level architecture (HLA) document. It outlines the design decisions taken for the Ouroboros prototype. --- doc/.gitignore | 1 + doc/highlevelarchitecture.txt | 328 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 329 insertions(+) create mode 100644 doc/.gitignore create mode 100644 doc/highlevelarchitecture.txt (limited to 'doc') 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 + -- cgit v1.2.3