reworked documentation structure

doc/AdvancedIO.md

@@ -0,0 +1,3 @@
+# Advanced IO {#advio}
+
+@todo

doc/Concept.md

@@ -1,12 +1,14 @@
 # Concept
 
-The server is designed around the concept of _nodes_ and _paths_.
+VILLASnode is designed around the concept of _nodes_, _super-nodes_ and _paths_.
 It's the task of the server to forward real-time simulation data between multiple parties.
 In doing so, the server has to perform simple checks and collects statistics.
 From the viewpoint of the communication parters the server is nearly transparent.
 Hence, it's cruical to keep the added overhead as low as possible (in terms of latency).
 
-## Nodes
+## @subpage supernode
+
+## @subpage node
 
 All communication partners are represented by nodes.
 
@@ -19,7 +21,7 @@ Possible types of nodes are:
 
 @see node for implementation details.
 
-## Paths
+## @subpage path
 
 A path is a **uni-directional** connection between incoming and outgoing nodes.
 
@@ -36,6 +38,8 @@ However every path supports optional hook/callback functions which allow user-de
 
 @see path for implementation details.
 
+## @subpage hook
+
 ## Interface
 
 Interfaces are used to represent physical network ports on the server.

doc/Development.md

@@ -1,40 +1,54 @@
 # Development
 
-Developement is currently coordinated by Steffen Vogel <stvogel@eonerc.rwth-aachen.de> using [GitHub](http://github.com/RWTH-ACS/VILLASnode).
+Developement is currently coordinated by Steffen Vogel <stvogel@eonerc.rwth-aachen.de> using [GitLab](http://git.rwth-aachen.de/VILLASframework/VILLASnode).
 Please feel free to submit pull requests or bug reports.
 
+@todo Add link to contribution guidelines
+
+## Programming Paradigm
+
+VILLASnode is currently written in C using the ISO C99 standard.
+Yet, it is heavily structured into modules / plugins and uses a C++-like object oriented style.
+In the future, VILLASnode might switch to lightweight C++.
+
+Main _classes_ in VILLASnode are struct node, struct path, struct hook and struct api_ressource.
+In order to track the life cycle of those objects, each of them has an enum state member.
+The following figure illustrates the state machine which is used:
+
+@diafile states.dia
+
 ## Shared library: libvillas
 
-VILLASnode is split into a shared library called libvillas and a couple of executables (`villas-server`, `villas-pipe`, `villas-test`, `villas-signal`) which are linked agains the library.
+VILLASnode is split into a shared library called libvillas and a couple of executables (`villas-node`, `villas-pipe`, `villas-test`, `villas-signal`, ...) which are linked against this library.
 
-## Extensibilty
+## Extensibilty / Plugins
 
-There are two main places where VILLASnode can easily extended:
+There are many places where VILLASnode can easily extended with plugins:
 
-#### New node-type
+### Example of new node type
 
-    REGISTER_NODE_TYPE(struct node_type *vt)
+See `include/villas/plugin.h`
 
-#### New hook functions
+See `lib/nodes/file.c`:
 
-    /** The type of a hook defines when a hook will be exectuted. This is used as a bitmask. */
-    enum hook_type {
-    	HOOK_PATH_START		= 1 << 0, /**< Called whenever a path is started; before threads are created. */
-	
 	[...]
 	
-    	HOOK_ASYNC		= 1 << 6, /**< Called asynchronously with fixed rate (see path::rate). */
+	static struct plugin p = {
+		.name		= "file",
+		.description	= "support for file log / replay node type",
+		.type		= PLUGIN_TYPE_NODE,
+		.node		= {
+			.vectorize	= 1,
+			.size		= sizeof(struct file),
+			.reverse	= file_reverse,
+			.parse		= file_parse,
+			.print		= file_print,
+			.start		= file_start,
+			.stop		= file_stop,
+			.read		= file_read,
+			.write		= file_write,
+			.instances	= LIST_INIT()
+		}
+	};
 	
-    	HOOK_PERIODIC		= 1 << 7, /**< Called periodically. Period is set by global 'stats' option in the configuration file. */
-	
-    	/** @{ Classes of hooks */
-    	/** Internal hooks are mandatory. */
-    	HOOK_INTERNAL		= 1 << 16,
-    	/** All hooks */
-    	HOOK_ALL		= HOOK_INTERNAL - 1
-    	/** @} */
-    };
-    
-    typedef int (*hook_cb_t)(struct path *p, struct hook *h, int when);
-    
-    REGISTER_HOOK(char *name, int priority, hook_cb_t cb, enum hook_type when)
+	REGISTER_PLUGIN(&p)

doc/GettingStarted.md

@@ -26,8 +26,7 @@ VILLASnode ...
 - is written in object-oriented C11
 - is compiled with Clang / LLVM or GCC
 - is fully based on open source software
-- stands for Simulator-to-Simulator-Server
-- is extensible with new node types
-- heavily multi-threaded
+- is extensible with new node types & hooks
+- is heavily multi-threaded
 - follows the Unix philosophy
-- is separated into a library (libvillas) and a few binaries (server, pipe, test, signal) which link against the lib.
+- is separated into a library (libvillas) and a few binaries (villas-server, villas-pipe, villas-test-*, villas-signal, villas-hook) which link against the lib.

doc/LiveSystem.md

@@ -1,7 +0,0 @@
-# LiveCD & LiveUSB
-
-As described in the [Tuning](Tuning) page, a carefull setup of the underlying system is essential to get optimal performance.
-
-At ACS, we are using a Fedora-based Live system which is optomized for real-time critical workloads.
-
-Take a look at the `contrib/liveusb/` directory for the configuration and scripts we are using.

doc/RemoteAPI.md

@@ -0,0 +1 @@
+#Remote Application Programming Interface (API) {#API}

doc/Usage.md

@@ -1,13 +1,42 @@
 # Usage {#usage}
 
-VILLASnode (`villas node`) expects the path to a configuration file as a single argument.
+The core of VILLASnode is the `villas-node` server.
+The folling usage information is provided when called like `villas-node --help`;
 
-    Usage: ./villas-node CONFIG
-      CONFIG is a required path to a configuration file
-     
-    VILLASnode 0.1-d7de19c (Jun  4 2014 02:50:13)
-      Copyright 2015, Institute for Automation of Complex Power Systems, EONERC
-        Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
+	Usage: villas-node [CONFIG]
+	  CONFIG is the path to an optional configuration file
+	         if omitted, VILLASnode will start without a configuration
+	         and wait for provisioning over the web interface.
+
+	Supported node types:
+	 - file        : support for file log / replay node type
+	 - cbuilder    : RTDS CBuilder model
+	 - socket      : BSD network sockets
+	 - fpga        : VILLASfpga PCIe card (libxil)
+	 - ngsi        : OMA Next Generation Services Interface 10 (libcurl, libjansson)
+	 - websocket   : Send and receive samples of a WebSocket connection (libwebsockets)
+
+	Supported hooks:
+	 - restart     : Call restart hooks for current path
+	 - print       : Print the message to stdout
+	 - decimate    : Downsamping by integer factor
+	 - fix_ts      : Update timestamps of sample if not set
+	 - skip_first  : Skip the first samples
+	 - drop        : Drop messages with reordered sequence numbers
+	 - convert     : Convert message from / to floating-point / integer
+	 - shift       : Shift the origin timestamp of samples
+	 - ts          : Update timestamp of message with current time
+	 - stats       : Collect statistics for the current path
+	 - stats_send  : Send path statistics to another node
+
+	Supported API commands:
+	 - nodes       : retrieve list of all known nodes
+	 - config      : retrieve current VILLASnode configuration
+	 - reload      : restart VILLASnode with new configuration
+
+	VILLASnode v0.7-0.2-646-g59756e7-dirty-debug (built on Mar 12 2017 21:37:40)
+	 copyright 2014-2016, Institute for Automation of Complex Power Systems, EONERC
+	 Steffen Vogel <StVogel@eonerc.rwth-aachen.de>
 
 The server requires root privileges for:
 
@@ -40,7 +69,7 @@ The server requires root privileges for:
 
 4. Edit configuration file
 
-    $ nano etc/opal-test.conf
+    $ nano etc/loopback.conf
 
  - Take a look at the examples and documentation for a detailed description
  - Move with: cursor keys
@@ -48,7 +77,7 @@ The server requires root privileges for:
 
 5. Start server
 
-    $ villas node etc/opal-test.conf
+    $ villas node etc/loopback.conf
 
 6. Terminate server by pressing Ctrl+C
 

doc/concept/Hooks.md

@@ -1,4 +1,4 @@
-# Hooks
+# Hooks {#hook}
 
 Hooks are simple callback functions which are called whenever a message is processed by a path.
 

doc/concept/Node.md

@@ -0,0 +1 @@
+#Nodes {#node}

doc/concept/Path.md

@@ -0,0 +1 @@
+#Paths {#path}

doc/concept/SuperNode.md

@@ -0,0 +1 @@
+# Super Nodes {#supernode}