From d501c9f496b3c8c5cfa870830108ce104174bf25 Mon Sep 17 00:00:00 2001 From: Sander Vrijders Date: Wed, 10 Jan 2018 16:49:21 +0100 Subject: doc: Update workflow and remove HLA The high level architecture and workflow document were severely outdated. This removes the HLA document, as a paper will soon be written and updates the workflow document to reflect the current situation. Signed-off-by: Sander Vrijders Signed-off-by: Dimitri Staessens --- doc/highlevelarchitecture.txt | 326 ------------------------------------------ doc/workflow.txt | 256 ++++++++++++++++----------------- 2 files changed, 127 insertions(+), 455 deletions(-) delete mode 100644 doc/highlevelarchitecture.txt diff --git a/doc/highlevelarchitecture.txt b/doc/highlevelarchitecture.txt deleted file mode 100644 index 50540d12..00000000 --- a/doc/highlevelarchitecture.txt +++ /dev/null @@ -1,326 +0,0 @@ -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 (FRCT), originally known as -the Error and Flow Control Protocol (EFCP), provides the flow with -flow control and (if needed) retransmission control. It manages the -shared state between two protocol machines: the Data Transfer Protocol -(DTP) AE and the Data Transfer Control Protocol (DTCP) AE. DTP is for -instance concerned with concatenation, multiplexing, reassembly,... -DTCP provides flow control and retransmission control. - -* 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 diff --git a/doc/workflow.txt b/doc/workflow.txt index a829192b..81bc8667 100644 --- a/doc/workflow.txt +++ b/doc/workflow.txt @@ -1,129 +1,127 @@ -1. Communication - -There are 2 ways that will be used to communicate: The mailing list -(ouroboros@freelists.org) will be used for almost everything except -for day-to-day chat. For that we will use the channel #ouroboros-rina -on Freenode (IRC chat). Use whatever name you desire. - -2. Coding guidelines - -The Ouroboros stack is written in C and has the GPL license. It uses -autotools as the build system. The coding guidelines of the Ouroboros -stack are the same as those of the Linux kernel -(https://www.kernel.org/doc/Documentation/CodingStyle) with the -following exceptions: - -- Soft tabs are to be used instead of hard tabs - -- A space is to be inserted between a pointer and its object name. Example: - -int * a; -instead of -int *a; - -- Don't explicitly cast malloc, but do - -ptr = malloc (sizeof(*ptr) * len); -or -ptr = malloc (sizeof *ptr * len); - -- When checking for invalid pointers use - -if (ptr == NULL) -instead of -if (!ptr) - -3. Development workflow - -Git is used as a version tooling for the code. Releases are identified -through a git tag by a number MAJOR.MICRO. Incrementing MAJOR is used -to indicate a big step ahead in terms of features; it is discussed -when new features are planned. Incrementing MICRO is done when -APIs/ABIs are not necessarily compatible. - -3.1. Repository structure - -The main git repository can be found at: -https://bitbucket.org/ouroboros-rina/stack - -It contains the following branches: - -- master: Contains the most stable versions of the stack. - -- testing: Contains tested version but may still contain bugs. - -- be: Contains untested but compiling code. - -All new contributions are integrated into ‘be’ from forks of the main -git repository. Once a version of ‘be’ is tested enough, it is merged -into ‘testing’. When a ‘testing’ version is considered stable enough, -it is merged into ‘master’. Users should ALWAYS use master. - -3.2. Contributions - -There are 3 ways to provide contributions: - -- bitbucket pull-requests: via bitbucket UI - -- git email pull-requests: via mailing list (ouroboros@freelists.org) - -- git email patch: via mailing list (ouroboros@freelists.org) - -New development is ALWAYS done against the ‘be’ branch of the main git -repository. Contributions are always made using your real name and -real e-mail address. - -3.3 Commit messages - -A commit message should follow these 9 simple rules (adjusted from -http://chris.beams.io/posts/git-commit/): - -- Separate subject from body with a blank line - -- Limit the subject line to 50 characters - -- Capitalize the subject line - -- Do not end the subject line with a period - -- Use the imperative mood in the subject line - -- Precede the subject line by indicating the component where changes -were made - -- Wrap the body at 72 characters - -- Use the body to explain what and why vs. how - -- If the commit addresses a bug, reference it in the body - -3.4 Bugs - -Bugs are reported through the bitbucket issue tracker -(https://bitbucket.org/ouroboros-rina/stack/issues?status=new&status=open). The -process of reporting a bug is the following: - -a. Report the bug on the issue tracker - -b. Sync with the HEAD of the most stable branch where the bug is -present - -c. Provide a bug fix - -d. Request a pull request to that branch - -e. The bugfix will be merged upwards into the less stable branches - -Note that step a is always required. Steps b-e may be performed by -someone else. - -4. New features - -New features can be always be requested through the mailing list. They -will be taken into account when a next version of the prototype is -discussed. A next version is discussed through a conference call, -after which the agreed upon features are added to the issue -tracker. Version 1.0 of Ouroboros will contain minimal functionality -to have a RINA implementation. Pull requests containing non discussed -features will be automatically rejected and will revoke you the rights -to perform new pull requests. +1. Communication + +There are 2 ways that will be used to communicate: The mailing list +(ouroboros@freelists.org) will be used for almost everything except +for day-to-day chat. For that we will use the channel #ouroboros on +Freenode (IRC chat). Use whatever name you desire. + +2. Coding guidelines + +The coding guidelines of the Ouroboros stack are the same as those of +the Linux kernel +(https://www.kernel.org/doc/Documentation/CodingStyle) with the +following exceptions: + +- Soft tabs are to be used instead of hard tabs + +- A space is to be inserted between a pointer and its object name upon + declaration or in function signatures. Example: + +int * a; +instead of +int *a; + +- Don't explicitly cast malloc, but do + +ptr = malloc(sizeof(*ptr) * len); + +- When checking for invalid pointers use + +if (ptr == NULL) +instead of +if (!ptr) + +3. Development workflow + +Git is used as a version tooling for the code. Releases are identified +through a git tag by a number MAJOR.MICRO.PATCHLEVEL. Incrementing +MAJOR is done to indicate a big step ahead in terms of features; it is +discussed when new features are planned. Incrementing MICRO is done +when APIs/ABIs are not necessarily compatible. The PATCHLEVEL is +incremented when an urgent bugfix is incorporated. + +3.1. Repository structure + +The main git repository can be found at: +https://ouroboros.ilabt.imec.be/git/ouroboros + +It contains the following branches: + +- master: Contains the most stable versions of Ouroboros. + +- testing: Contains tested code but may still contain bugs. + +- be: Contains untested but compiling code. + +All new contributions are integrated into 'be' through patches sent to +the mailing list. Once a version of 'be' is tested enough, it is +merged into 'testing'. When a 'testing' version is considered stable +enough, it is merged into 'master'. Users should ALWAYS use master +unless told otherwise. + +3.2. Contributions + +There is 1 ways to provide contributions: + +- git email patch: via mailing list (ouroboros@freelists.org) + +New development is ALWAYS done against the 'be' branch of the main git +repository. Contributions are always made using your real name and +real e-mail address. + +3.3 Commit messages + +A commit message should follow these 9 simple rules (adjusted from +http://chris.beams.io/posts/git-commit/): + +- Separate subject from body with a blank line + +- Limit the subject line to 50 characters + +- Capitalize the subject line + +- Do not end the subject line with a period + +- Use the imperative mood in the subject line + +- Precede the subject line by indicating the component where changes +were made + +- Wrap the body at 72 characters + +- Use the body to explain what and why vs. how + +- If the commit addresses a bug, reference it in the body + +- Sign off your commits using the signoff feature in git + +3.4 Bugs + +Bugs are reported through the Bugzilla issue tracker +(https://ouroboros.ilabt.imec.be/bugzilla/). The process of reporting +a bug is the following: + +a. Provide a description of the bug + +b. Provide system logs + +c. Provide a minimal code example to reproduce the bug + +d. Sync with the HEAD of the most stable branch where the bug is +present + +e. Provide a bug fix if you can + +f. Send a patch to the mailing list + +g. The bugfix will be merged upwards into the less stable branches + +Note that step a and b are always required. Steps c-g may be performed +by someone else. + +4. New features + +New features can be always be requested through the mailing list. They +will be taken into account when a next version of the prototype is +discussed. Patches containing non discussed features will be +automatically rejected. -- cgit v1.2.3