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 <sander.vrijders@ugent.be>
Signed-off-by: Dimitri Staessens <dimitri.staessens@ugent.be>

2 files changed, 127 insertions, 455 deletions

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.