From 4c80f8cded7302c23804abecc9c153ec27106341 Mon Sep 17 00:00:00 2001 From: Steffen Vogel Date: Mon, 13 Mar 2017 00:03:36 -0300 Subject: [PATCH] reworked documentation structure --- doc/AdvancedIO.md | 3 ++ doc/Concept.md | 10 ++++-- doc/Development.md | 64 ++++++++++++++++++++++--------------- doc/GettingStarted.md | 7 ++-- doc/LiveSystem.md | 7 ---- doc/RemoteAPI.md | 1 + doc/Usage.md | 47 +++++++++++++++++++++------ doc/{ => concept}/Hooks.md | 2 +- doc/concept/Node.md | 1 + doc/concept/Path.md | 1 + doc/concept/SuperNode.md | 1 + doc/figures/states.dia | Bin 0 -> 2256 bytes 12 files changed, 95 insertions(+), 49 deletions(-) create mode 100644 doc/AdvancedIO.md delete mode 100644 doc/LiveSystem.md create mode 100644 doc/RemoteAPI.md rename doc/{ => concept}/Hooks.md (99%) create mode 100644 doc/concept/Node.md create mode 100644 doc/concept/Path.md create mode 100644 doc/concept/SuperNode.md create mode 100644 doc/figures/states.dia diff --git a/doc/AdvancedIO.md b/doc/AdvancedIO.md new file mode 100644 index 000000000..a79ab03af --- /dev/null +++ b/doc/AdvancedIO.md @@ -0,0 +1,3 @@ +# Advanced IO {#advio} + +@todo \ No newline at end of file diff --git a/doc/Concept.md b/doc/Concept.md index 5d03ceb10..a2b0beb48 100644 --- a/doc/Concept.md +++ b/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. diff --git a/doc/Development.md b/doc/Development.md index 00d811569..ee76b4384 100644 --- a/doc/Development.md +++ b/doc/Development.md @@ -1,40 +1,54 @@ # Development -Developement is currently coordinated by Steffen Vogel using [GitHub](http://github.com/RWTH-ACS/VILLASnode). +Developement is currently coordinated by Steffen Vogel 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) \ No newline at end of file diff --git a/doc/GettingStarted.md b/doc/GettingStarted.md index 342e76613..78201b0b9 100644 --- a/doc/GettingStarted.md +++ b/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. \ No newline at end of file +- 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. \ No newline at end of file diff --git a/doc/LiveSystem.md b/doc/LiveSystem.md deleted file mode 100644 index 714e884bb..000000000 --- a/doc/LiveSystem.md +++ /dev/null @@ -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. diff --git a/doc/RemoteAPI.md b/doc/RemoteAPI.md new file mode 100644 index 000000000..c78b8dd70 --- /dev/null +++ b/doc/RemoteAPI.md @@ -0,0 +1 @@ +#Remote Application Programming Interface (API) {#API} \ No newline at end of file diff --git a/doc/Usage.md b/doc/Usage.md index 093dbcd92..45fb7f46b 100644 --- a/doc/Usage.md +++ b/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 + 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 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 diff --git a/doc/Hooks.md b/doc/concept/Hooks.md similarity index 99% rename from doc/Hooks.md rename to doc/concept/Hooks.md index 6ec3b9828..e85d41ab4 100644 --- a/doc/Hooks.md +++ b/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. diff --git a/doc/concept/Node.md b/doc/concept/Node.md new file mode 100644 index 000000000..66c18daae --- /dev/null +++ b/doc/concept/Node.md @@ -0,0 +1 @@ +#Nodes {#node} \ No newline at end of file diff --git a/doc/concept/Path.md b/doc/concept/Path.md new file mode 100644 index 000000000..1a74a2a63 --- /dev/null +++ b/doc/concept/Path.md @@ -0,0 +1 @@ +#Paths {#path} \ No newline at end of file diff --git a/doc/concept/SuperNode.md b/doc/concept/SuperNode.md new file mode 100644 index 000000000..147ba0f56 --- /dev/null +++ b/doc/concept/SuperNode.md @@ -0,0 +1 @@ +# Super Nodes {#supernode} \ No newline at end of file diff --git a/doc/figures/states.dia b/doc/figures/states.dia new file mode 100644 index 0000000000000000000000000000000000000000..91e61a68d4beee8a54d9add9a8fb7a3ba5f7804a GIT binary patch literal 2256 zcmV;>2ru^^iwFP!000021MOYgZsWEVea}}2o`<$TDvJ~;QB9L#&UA_fEzS&P(gK|q zgSHr3XJpBs=y=?Re*2+hWo+Gi)5Wn%0|_E|Yj2U_T8rc+l^=ilGWE45#v?BbZhJsC zdKwExq3Z?X+uk1!zkE-6KiysZ=z8=A`7`Eps>v&YC_cLFO@x^J(C;r63*BEvRD@jj zy}2H-{y)_BXdt%#$Qzg)Cq)8Rt9#6W7x9{BFbXZo_%eU>0)0sV9mdhhgY58myuUK4-_riAL0yO>A4SYLw#96C&Jk|Buv< z_9?*X^jEYUirg{x-0i^4SX6jfc&?ZXzO+A+%_xY!j zu=o1%nyq2wtx_Ib!Z5>!%foo?xh&ez%(6BWo+hbTe^;&N?e?vh)v26VCn0>gWIT2M zt9*2fk9n-qTKa@j%F*aZcu&tq838R$XmK z9$1^%Xb5!6BykiX^#SUp1<19d0|3ZzQAc4A3|QbMg*c>Wr4~mPT{ex;EFZgUJ>fwT z61W4(dAP_sUbjRDYq}ozEEsQ-zoR*Q9b$*T?j0e1(y}qh1|Jo);`tkGA|a9ztO%3d zlD7UBS&>F)XfM%-vBlD7G6walFW*0~pIN8#o4LM?lV&uH3{_P`)fE zgE~-#r-3qQ0?McxD5DIN?XIAVc0<`#P`)fE!#YqlPXlGAHk4(ZCP~yb!EERt0W(R! zEY&#%vxImTU@n%g!sytEd@;z%Yt&y{nvi?hS=bzajY9Z}+1cvr4!I{f z7axrsrXnpxT9+{waz><8 zdks6pF?5mLCTl^Y6G>Rt&Wg97oh)US;}(e9WUi8;l^EIk896(+O9pckcPZ{VHFsGx zlB=X!?rLI*wR4L8meF#5%h}zPa#U|iG1g@ykzZ7At7@JaH3xa}XiN4e=lXNL7v(c*Ur0c{fg-GVQY?2kY3`{Mb&bTXc@BtzpPr#&@F% zWVeQb4)%uD7=v8K9-x2S#vcJZxT$e)l*hy0}u&)%(`#ezoKNVY-2Tut`%T_(Q|m(10#?!`Be98k$`G%wQT z!RH`c1p2>jRObL2LI{ZEK+}MB`>%6I8kOx>rgK@NI-`YAUDbcWNp5M2TI_&lL-Yk2 zpf9Uk`og+F05NY6(oF}T_~i|N9J>|t1oSnL^fhEG(7eDCo_y?oOCDQzVj`LBk~wzHK7&l(pYj>Io><0|HCk~PP3IBP-q~ovMxUR1W`pGD z+wT;Ab-`aqiXc|>b>8%anxHSzGJV;}STd$B%Z$5SBpyq`vl&WykrsptIgr%m5!2)& z(MB|or-Y=i^}LwY*QhTTk7vl_gX7{Wt3~mVVzq8q%~qqy3!pXJ#Qc8C6a4W@U{YFx z#B`GX!ElDO7W3FwYFkc2&UEdK