From 006440567aa3210b6183b3a1d32f8df1b6f5fd22 Mon Sep 17 00:00:00 2001 From: Steffen Vogel Date: Sat, 19 Sep 2015 18:48:00 +0200 Subject: [PATCH] improving documentation --- Doxyfile | 2 +- documentation/Clients.md | 11 ++++++----- documentation/Tuning.md | 12 +++++++----- server/include/file.h | 4 +++- server/include/gtfpga.h | 4 +++- server/include/hooks.h | 22 +++++++++++++--------- server/include/node.h | 5 ++++- server/include/opal.h | 6 ++++-- server/include/path.h | 9 +++++++-- server/include/socket.h | 4 +++- server/src/hooks.c | 1 - 11 files changed, 51 insertions(+), 29 deletions(-) diff --git a/Doxyfile b/Doxyfile index f5725561e..2123c9250 100644 --- a/Doxyfile +++ b/Doxyfile @@ -771,7 +771,7 @@ INPUT = server/ \ clients/ml507_ppc440_udp/pcores/ \ clients/ml507_ppc440_udp/s2ss/ \ clients/ml507_gtfpga_pcie/code/ \ - clients/opal_udp/models/AsyncIP_sl/s2ss/ + clients/opal_udp/models/send_receive/src/ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/documentation/Clients.md b/documentation/Clients.md index bb96a3434..a5a6226fc 100644 --- a/documentation/Clients.md +++ b/documentation/Clients.md @@ -9,8 +9,9 @@ Every server needs clients which act as sinks / sources for simulation data. In Take a look at the `clients/` directory for them: - - RTDS UDP Network Card ? - - RTDS via GTFPGA - - OPAL - - Labview - - Simulink + - RTDS via GTFPGA and UDP + - RTDS via GTFPGA and PCIexpress + - OPAL via Asynchronous Process and UDP + - OPAL via Asynchronous Process and Shared memory + - Labview (*planned*) + - Simulink (*planned*) diff --git a/documentation/Tuning.md b/documentation/Tuning.md index 3330da5cd..1e9769b92 100644 --- a/documentation/Tuning.md +++ b/documentation/Tuning.md @@ -3,14 +3,18 @@ ## Operating System and Kernel For minimum latency several kernel and driver settings can be optimized. -A [RT-preemp patched Linux](https://rt.wiki.kernel.org/index.php/Main_Page) kernel is recommended. +A [RT-preempt patched Linux](https://rt.wiki.kernel.org/index.php/Main_Page) kernel is recommended. Precompiled kernels for Fedora can be found here: http://ccrma.stanford.edu/planetccrma/software/ - Map NIC IRQs => see setting `affinity` + - Map Tasks => see setting `affinity` - Kernel command line: isolcpus=[cpu_number] -- Nice Task => see setting `priority` + +- Increase priority of server task (nice(2)) => see setting `priority` + - Increase socket priority + - Configure NIC interrupt coalescence with `ethtool`: $ ethtool -C|--coalesce devname [adaptive-rx on|off] [adaptive-tx on|off] ... @@ -27,8 +31,6 @@ This are some proposals for the selection of appropriate server hardware: - Server-grade CPU: Intel Xeon - A multi-core systems allows parallization of send/receive paths. + - Server-grade network cards: Intel PRO/1000 - These allow offloading of UDP checksumming to the hardware - -\example server/etc/loopback.conf -\example server/etc/example.conf diff --git a/server/include/file.h b/server/include/file.h index 4d0220199..8c54684b8 100644 --- a/server/include/file.h +++ b/server/include/file.h @@ -7,8 +7,10 @@ * @copyright 2014-2015, Institute for Automation of Complex Power Systems, EONERC * This file is part of S2SS. All Rights Reserved. Proprietary and confidential. * Unauthorized copying of this file, via any medium is strictly prohibited. - * + */ +/** * @addtogroup file File-IO node type + * @ingroup node * @{ *********************************************************************************/ diff --git a/server/include/gtfpga.h b/server/include/gtfpga.h index 2a3e20162..5f863a49b 100644 --- a/server/include/gtfpga.h +++ b/server/include/gtfpga.h @@ -10,8 +10,10 @@ * @copyright 2014-2015, Institute for Automation of Complex Power Systems, EONERC * This file is part of S2SS. All Rights Reserved. Proprietary and confidential. * Unauthorized copying of this file, via any medium is strictly prohibited. - * + */ +/** * @addtogroup gtfpga RTDS - PCIexpress Fiber interface node type + * @ingroup node * @{ *********************************************************************************/ diff --git a/server/include/hooks.h b/server/include/hooks.h index 5af8b486a..a8994d726 100644 --- a/server/include/hooks.h +++ b/server/include/hooks.h @@ -11,8 +11,10 @@ * @copyright 2014-2015, Institute for Automation of Complex Power Systems, EONERC * This file is part of S2SS. All Rights Reserved. Proprietary and confidential. * Unauthorized copying of this file, via any medium is strictly prohibited. - * + */ +/** * @addtogroup hooks User-defined hook functions + * @ingroup path * @{ *********************************************************************************/ @@ -32,6 +34,7 @@ __attribute__((constructor)) void __register_ ## fnc () { \ /* Forward declarations */ struct path; +/** This is a list of hooks which can be used in the configuration file. */ extern struct list hooks; /** Callback type of hook function @@ -42,6 +45,7 @@ extern struct list hooks; */ typedef int (*hook_cb_t)(struct path *p); +/** The type of a hook defines when a hook will be exectuted. */ enum hook_type { HOOK_PATH_START, /**< Called whenever a path is started; before threads are created. */ HOOK_PATH_STOP, /**< Called whenever a path is stopped; after threads are destoyed. */ @@ -56,7 +60,7 @@ enum hook_type { HOOK_MAX }; -/** Descriptor for user defined hooks. See hook_list[]. */ +/** Descriptor for user defined hooks. See hooks[]. */ struct hook { /** The unique name of this hook. This must be the first member! */ const char *name; @@ -65,13 +69,13 @@ struct hook { enum hook_type type; }; -struct hook * hook_lookup(const char *name); - -/* The following prototypes are example hooks */ - -/** Example hook: Print the message. - * @example +/** The following prototypes are example hooks + * + * @addtogroup hooks_examples Examples for hook functions + * @{ */ + +/** Example hook: Print the message. */ int hook_print(struct path *p); /** Example hook: Drop messages. */ @@ -100,4 +104,4 @@ int hook_restart(struct path *p); /** Core hook: check if sequence number is correct. Otherwise message will be dropped */ int hook_drop(struct path *p); -#endif /** _HOOKS_H_ @} */ +#endif /** _HOOKS_H_ @} @} */ diff --git a/server/include/node.h b/server/include/node.h index 1b4307a87..733bd1395 100644 --- a/server/include/node.h +++ b/server/include/node.h @@ -11,6 +11,9 @@ * @copyright 2014-2015, Institute for Automation of Complex Power Systems, EONERC * This file is part of S2SS. All Rights Reserved. Proprietary and confidential. * Unauthorized copying of this file, via any medium is strictly prohibited. + * + * @addtogroup node Node + * @{ *********************************************************************************/ #ifndef _NODE_H_ @@ -224,4 +227,4 @@ struct node * node_create(); */ void node_destroy(struct node *n); -#endif /* _NODE_H_ */ +#endif /** _NODE_H_ @} */ diff --git a/server/include/opal.h b/server/include/opal.h index d589a79c8..842618fb1 100644 --- a/server/include/opal.h +++ b/server/include/opal.h @@ -7,8 +7,10 @@ * @copyright 2014-2015, Institute for Automation of Complex Power Systems, EONERC * This file is part of S2SS. All Rights Reserved. Proprietary and confidential. * Unauthorized copying of this file, via any medium is strictly prohibited. - * - * @addtogroup opal OPAL-RT Asyc Process node type + */ +/** + * @ingroup node + * @addtogroup opal OPAL-RT Async Process node type * @{ **********************************************************************************/ diff --git a/server/include/path.h b/server/include/path.h index fdf269883..5d1a80601 100644 --- a/server/include/path.h +++ b/server/include/path.h @@ -4,7 +4,12 @@ * @author Steffen Vogel * @copyright 2014-2015, Institute for Automation of Complex Power Systems, EONERC * This file is part of S2SS. All Rights Reserved. Proprietary and confidential. - * Unauthorized copying of this file, via any medium is strictly prohibited. + * Unauthorized copying of this file, via any medium is strictly prohibited. + */ +/** A path connects one input node to multiple output nodes (1-to-n). + * + * @addtogroup path Path + * @{ *********************************************************************************/ #ifndef _PATH_H_ @@ -147,4 +152,4 @@ int path_print(struct path *p, char *buf, int len); */ int path_run_hook(struct path *p, enum hook_type t); -#endif /* _PATH_H_ */ +#endif /** _PATH_H_ @} */ diff --git a/server/include/socket.h b/server/include/socket.h index 28946efcf..370f483ac 100644 --- a/server/include/socket.h +++ b/server/include/socket.h @@ -7,8 +7,10 @@ * @copyright 2014-2015, Institute for Automation of Complex Power Systems, EONERC * This file is part of S2SS. All Rights Reserved. Proprietary and confidential. * Unauthorized copying of this file, via any medium is strictly prohibited. - * + */ +/** * @addtogroup socket BSD Socket Node Type + * @ingroup node * @{ *********************************************************************************/ diff --git a/server/src/hooks.c b/server/src/hooks.c index d8b6e7199..986e09028 100644 --- a/server/src/hooks.c +++ b/server/src/hooks.c @@ -23,7 +23,6 @@ /* Some hooks can be configured by constants in te file "config.h" */ -/** This is a static list of available hooks. */ struct list hooks; REGISTER_HOOK("print", 99, hook_print, HOOK_MSG)