From 506bb2446c371e487208bd3b0a831d51f51c1c65 Mon Sep 17 00:00:00 2001 From: Steffen Vogel Date: Wed, 6 May 2015 11:36:51 +0200 Subject: [PATCH] updated documentation (copyright year and other stuff) --- server/include/cfg.h | 2 +- server/include/config.h | 2 +- server/include/file.h | 11 +++++- server/include/gtfpga.h | 22 +++++++----- server/include/hist.h | 3 +- server/include/hooks.h | 12 +++---- server/include/if.h | 2 +- server/include/log.h | 1 - server/include/msg.h | 2 +- server/include/msg_format.h | 2 +- server/include/node.h | 38 +++++++++++++++++--- server/include/opal.h | 28 +++++++-------- server/include/path.h | 2 +- server/include/socket.h | 69 +++++++++++-------------------------- server/include/tc.h | 2 +- server/include/utils.h | 2 +- server/src/cfg.c | 2 +- server/src/gtfpga.c | 2 +- server/src/hist.c | 2 +- server/src/hooks.c | 2 +- server/src/if.c | 2 +- server/src/list.c | 1 - server/src/msg.c | 2 +- server/src/random.c | 7 +++- server/src/receive.c | 7 +++- server/src/send.c | 5 ++- 26 files changed, 127 insertions(+), 105 deletions(-) diff --git a/server/include/cfg.h b/server/include/cfg.h index 9c1274923..04979c71d 100644 --- a/server/include/cfg.h +++ b/server/include/cfg.h @@ -5,7 +5,7 @@ * libconfig http://www.hyperrealm.com/libconfig/ * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file */ diff --git a/server/include/config.h b/server/include/config.h index c82ce3e76..bf548b0ab 100644 --- a/server/include/config.h +++ b/server/include/config.h @@ -4,7 +4,7 @@ * This settings are not part of the configuration file. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file */ diff --git a/server/include/file.h b/server/include/file.h index 518b45988..130401b01 100644 --- a/server/include/file.h +++ b/server/include/file.h @@ -4,6 +4,9 @@ * * @author Steffen Vogel * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC + * @file + * @addtogroup file File-IO node type + * @{ */ #ifndef _FILE_H_ @@ -26,16 +29,22 @@ struct file { int tfd; /**< Timer file descriptor. Blocks until 1/rate seconds are elapsed. */ }; +/** @see node_vtable::init */ int file_print(struct node *n, char *buf, int len); +/** @see node_vtable::parse */ int file_parse(config_setting_t *cfg, struct node *n); +/** @see node_vtable::open */ int file_open(struct node *n); +/** @see node_vtable::close */ int file_close(struct node *n); int file_read(struct node *n, struct msg *m); +/** @see node_vtable::read */ int file_write(struct node *n, struct msg *m); +/** @see node_vtable::write */ -#endif /* _FILE_H_ */ \ No newline at end of file +#endif /** _FILE_H_ @} */ \ No newline at end of file diff --git a/server/include/gtfpga.h b/server/include/gtfpga.h index 444c46a50..432e4f6f5 100644 --- a/server/include/gtfpga.h +++ b/server/include/gtfpga.h @@ -3,7 +3,10 @@ * This file implements the gtfpga subtype for nodes. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC + * @file + * @addtogroup gtfpga RTDS - PCIexpress Fiber interface node type + * @{ */ #ifndef _GTFPGA_H_ @@ -30,26 +33,27 @@ struct gtfpga { }; int gtfpga_init(int argc, char * argv[]); +/** @see node_vtable::init */ +/** @see node_vtable::deinit */ int gtfpga_deinit(); -/** Parse node connection details for GTFPGA type - * - * @param cfg A libconfig object pointing to the node. - * @param n A pointer to the node structure which should be parsed. - * @retval 0 Success. Everything went well. - * @retval <0 Error. Something went wrong. - */ +/** @see node_vtable::parse */ int gtfpga_parse(config_setting_t *cfg, struct node *n); +/** @see node_vtable::print */ int gtfpga_print(struct node *n, char *buf, int len); +/** @see node_vtable::open */ int gtfpga_open(struct node *n); +/** @see node_vtable::close */ int gtfpga_close(struct node *n); +/** @see node_vtable::read */ int gtfpga_read(struct node *n, struct msg *m); +/** @see node_vtable::write */ int gtfpga_write(struct node *n, struct msg *m); -#endif /* _GTFPGA_H_ */ +#endif /** _GTFPGA_H_ @} */ diff --git a/server/include/hist.h b/server/include/hist.h index 569f7dbdd..b28d9dc3c 100644 --- a/server/include/hist.h +++ b/server/include/hist.h @@ -1,7 +1,8 @@ /** Histogram functions. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC + * @file */ #ifndef _HIST_H_ diff --git a/server/include/hooks.h b/server/include/hooks.h index 25286ad6d..a4a29e197 100644 --- a/server/include/hooks.h +++ b/server/include/hooks.h @@ -7,13 +7,17 @@ * This file includes some examples. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file + * @addtogroup hooks User-defined hook functions + * @{ */ #ifndef _HOOKS_H_ #define _HOOKS_H_ +/* The configuration of hook parameters is done in "config.h" */ + struct msg; struct path; @@ -50,16 +54,12 @@ int hook_print(struct msg *m, struct path *p); /** Example hook: Drop messages. */ int hook_decimate(struct msg *m, struct path *p); -#define HOOK_DECIMATE_RATIO 10 - /** Example hook: Convert the message values to fixed precision. */ int hook_tofixed(struct msg *m, struct path *p); /** Example hook: add timestamp to message. */ int hook_ts(struct msg *m, struct path *p); -#define HOOK_TS_INDEX -1 /* last message */ - /** Example hook: Finite-Impulse-Response (FIR) filter. */ int hook_fir(struct msg *m, struct path *p); @@ -81,4 +81,4 @@ int hook_demultiplex(struct msg *m, struct path *p); /** Example hook: Discrete Fourier Transform */ int hook_dft(struct msg *m, struct path *p); -#endif /* _HOOKS_H_ */ +#endif /** _HOOKS_H_ @} */ diff --git a/server/include/if.h b/server/include/if.h index 931f20234..cedecaf85 100644 --- a/server/include/if.h +++ b/server/include/if.h @@ -4,7 +4,7 @@ * Most of them make use of Linux-specific APIs. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file */ diff --git a/server/include/log.h b/server/include/log.h index 5d2856efb..407cd5f4c 100644 --- a/server/include/log.h +++ b/server/include/log.h @@ -64,7 +64,6 @@ void log_vprint(const char *lvl, const char *fmt, va_list va); void debug(int lvl, const char *fmt, ...) __attribute__ ((format(printf, 2, 3))); - /** Print a horizontal line. */ void line(); diff --git a/server/include/msg.h b/server/include/msg.h index 38960fb4b..c9d917a9a 100644 --- a/server/include/msg.h +++ b/server/include/msg.h @@ -1,7 +1,7 @@ /** Message related functions * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file */ diff --git a/server/include/msg_format.h b/server/include/msg_format.h index c3c188721..13338768d 100644 --- a/server/include/msg_format.h +++ b/server/include/msg_format.h @@ -1,7 +1,7 @@ /** Message format * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file */ diff --git a/server/include/node.h b/server/include/node.h index c1f088094..1cde79656 100644 --- a/server/include/node.h +++ b/server/include/node.h @@ -7,7 +7,7 @@ * - workstations * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file */ @@ -53,10 +53,38 @@ struct node_vtable { const enum node_type type; const char *name; + /** Parse node connection details for SOCKET type + * + * @param cfg A libconfig object pointing to the node. + * @param n A pointer to the node structure which should be parsed. + * @retval 0 Success. Everything went well. + * @retval <0 Error. Something went wrong. + */ int (*parse)(config_setting_t *cfg, struct node *n); + + /** Print details of socket connection + * + * @param n A pointer to the node structure + * @param buf The character buffer to be filled. + * @param len The length of the supplied buffer. + * @return The length of the address. + */ int (*print)(struct node *n, char *buf, int len); - int (*open)(struct node *n); + /** Create new socket and connect(), bind(), accept(). + * + * @param n A pointer to the node. + * @retval 0 Success. Everything went well. + * @retval <0 Error. Something went wrong. + */ + int (*open) (struct node *n); + + /** Close the socket. + * + * @param n A pointer to the node. + * @retval 0 Success. Everything went well. + * @retval <0 Error. Something went wrong. + */ int (*close)(struct node *n); int (*read)(struct node *n, struct msg *m); int (*write)(struct node *n, struct msg *m); @@ -95,14 +123,14 @@ struct node /** Initialize node type subsystems. * - * These routines are only called once per type (not node). + * These routines are only called once per type (not per node instance). * See node_vtable::init */ -int node_init(int argc, char *argv[]); +int node_init(int argc, char *argv[], struct settings *set); /** De-initialize node type subsystems. * - * These routines are only called once per type (not node). + * These routines are only called once per type (not per node instance). * See node_vtable::deinit */ int node_deinit(); diff --git a/server/include/opal.h b/server/include/opal.h index 1cfa6376c..3e58f6c05 100644 --- a/server/include/opal.h +++ b/server/include/opal.h @@ -3,7 +3,10 @@ * This file implements the opal subtype for nodes. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC + * @file + * @addtogroup opal OPAL-RT Asyc Process node type + * @{ */ #ifndef _OPAL_H_ @@ -57,39 +60,34 @@ struct opal { /** Initialize global OPAL settings and maps shared memory regions. * - * @param argc The number of CLI arguments, provided to main(). - * @param argv The CLI argument list, provided to main(). - * @retval 0 On success. - * @retval <0 On failure. + * @see node_vtable::init */ int opal_init(int argc, char *argv[]); /** Free global OPAL settings and unmaps shared memory regions. * - * @retval 0 On success. - * @retval <0 On failure. + * @see node_vtable::deinit */ int opal_deinit(); -/** Parse node connection details for OPAL type - * - * @param cfg A libconfig object pointing to the node. - * @param nodes Add new nodes to this linked list. - * @retval 0 Success. Everything went well. - * @retval <0 Error. Something went wrong. - */ +/** @see node_vtable::parse */ int opal_parse(config_setting_t *cfg, struct node *n); +/** @see node_vtable::print */ int opal_print(struct node *n, char *buf, int len); int opal_print_global(struct opal_global *g); +/** @see node_vtable::open */ int opal_open(struct node *n); +/** @see node_vtable::close */ int opal_close(struct node *n); +/** @see node_vtable::read */ int opal_read(struct node *n, struct msg *m); +/** @see node_vtable::write */ int opal_write(struct node *n, struct msg *m); -#endif /* _OPAL_H_ */ +#endif /** _OPAL_H_ @} */ diff --git a/server/include/path.h b/server/include/path.h index a01bf357f..c11d794d2 100644 --- a/server/include/path.h +++ b/server/include/path.h @@ -1,7 +1,7 @@ /** Message paths * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file */ diff --git a/server/include/socket.h b/server/include/socket.h index e9a3c4ce6..c9afbad82 100644 --- a/server/include/socket.h +++ b/server/include/socket.h @@ -3,7 +3,10 @@ * This file implements the socket subtype for nodes. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC + * @file + * @addtogroup socket BSD Socket Node Type + * @{ */ #ifndef _SOCKET_H_ @@ -41,48 +44,16 @@ struct socket { */ int socket_open(struct node *n); -/** Close the socket. - * - * @param n A pointer to the node. - * @retval 0 Success. Everything went well. - * @retval <0 Error. Something went wrong. - */ -int socket_close(struct node *n); +/** @see node_vtable::close */ -/** Send a message over a socket connection. - * - * @param m A pointer to the message - * @param n A pointer to the node - * @retval 0 Success. Everything went well. - * @retval <0 Error. Something went wrong. - */ -int socket_write(struct node *n, struct msg *m); +/** @see node_vtable::write */ -/** Receive a message over a socket connection. - * - * @param m A pointer to the message - * @param n A pointer to the node - * @retval 0 Success. Everything went well. - * @retval <0 Error. Something went wrong. - */ -int socket_read(struct node *n, struct msg *m); +/** @see node_vtable::read */ -/** Parse node connection details for SOCKET type - * - * @param cfg A libconfig object pointing to the node. - * @param n A pointer to the node structure which should be parsed. - * @retval 0 Success. Everything went well. - * @retval <0 Error. Something went wrong. - */ +/** @see node_vtable::parse */ int socket_parse(config_setting_t *cfg, struct node *n); -/** Print details of socket connection - * - * @param n A pointer to the node structure - * @param buf A buffer to be filled. - * @param len The length of the supplied buffer. - * @return The length of the address. - */ +/** @see node_vtable::print */ int socket_print(struct node *n, char *buf, int len); /** Generate printable socket address depending on the address family @@ -90,10 +61,10 @@ int socket_print(struct node *n, char *buf, int len); * A IPv4 address is formatted as dotted decimals followed by the port/protocol number * A link layer address is formatted in hexadecimals digits seperated by colons and the inferface name * - * @param buf A buffer to be filled. - * @param len The length of the supplied buffer. - * @param sa A pointer to the socket address. - * @return The length of the address. + * @param buf A buffer to be filled. + * @param len The length of the supplied buffer. + * @param sa A pointer to the socket address. + * @retur The length of the address in bytes. */ int socket_print_addr(char *buf, int len, struct sockaddr *sa); @@ -104,13 +75,13 @@ int socket_print_addr(char *buf, int len, struct sockaddr *sa); * * @todo Add support for autodetection of address type * - * @param str A string specifiying the socket address. See description for allowed formats. - * @param sa A pointer to the resolved address - * @param type Specifies the address type in which the addr is given - * @param flags Flags for getaddrinfo(2) - * @retval 0 Success. Everything went well. - * @retval <0 Error. Something went wrong. + * @param str A string specifiying the socket address. See description for allowed formats. + * @param sa A pointer to the resolved address + * @param type Specifies the address type in which the addr is given + * @param flags Flags for getaddrinfo(2) + * @retval 0 Success. Everything went well. + * @retval <0 Error. Something went wrong. */ int socket_parse_addr(const char *str, struct sockaddr *sa, enum node_type type, int flags); -#endif /* _SOCKET_H_ */ +#endif /** _SOCKET_H_ @} */ diff --git a/server/include/tc.h b/server/include/tc.h index 38df85061..a8e270382 100644 --- a/server/include/tc.h +++ b/server/include/tc.h @@ -6,7 +6,7 @@ * we can classify traffic originating from a node seperately. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file */ diff --git a/server/include/utils.h b/server/include/utils.h index 425be1ac6..bd0bfa2b5 100644 --- a/server/include/utils.h +++ b/server/include/utils.h @@ -1,7 +1,7 @@ /** Various helper functions. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC * @file */ diff --git a/server/src/cfg.c b/server/src/cfg.c index cd4958728..819897602 100644 --- a/server/src/cfg.c +++ b/server/src/cfg.c @@ -1,7 +1,7 @@ /** Configuration parser. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC */ #include diff --git a/server/src/gtfpga.c b/server/src/gtfpga.c index 107f05d44..d6746fe61 100644 --- a/server/src/gtfpga.c +++ b/server/src/gtfpga.c @@ -3,7 +3,7 @@ * This file implements the gtfpga subtype for nodes. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC */ #include "gtfpga.h" diff --git a/server/src/hist.c b/server/src/hist.c index dd89a1a56..6a25f2d98 100644 --- a/server/src/hist.c +++ b/server/src/hist.c @@ -1,7 +1,7 @@ /** Histogram functions. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC */ #include diff --git a/server/src/hooks.c b/server/src/hooks.c index d92a698bf..45fb32f9e 100644 --- a/server/src/hooks.c +++ b/server/src/hooks.c @@ -7,7 +7,7 @@ * This file includes some examples. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC */ #include diff --git a/server/src/if.c b/server/src/if.c index 01eb104df..acf3bc737 100644 --- a/server/src/if.c +++ b/server/src/if.c @@ -1,7 +1,7 @@ /** Interface related functions. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC */ #include diff --git a/server/src/list.c b/server/src/list.c index bfc5882cc..8a99365fa 100644 --- a/server/src/list.c +++ b/server/src/list.c @@ -4,7 +4,6 @@ * * @author Steffen Vogel * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC - * @file */ #include "utils.h" diff --git a/server/src/msg.c b/server/src/msg.c index 01dcc7666..cb46b22da 100644 --- a/server/src/msg.c +++ b/server/src/msg.c @@ -1,7 +1,7 @@ /** Message related functions. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC */ #include diff --git a/server/src/random.c b/server/src/random.c index 4d08c0844..f2e530019 100644 --- a/server/src/random.c +++ b/server/src/random.c @@ -1,7 +1,10 @@ /** Generate random packages on stdout. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC + * @file + * @addtogroup tools Test and debug tools + * @{ */ #include @@ -87,3 +90,5 @@ int main(int argc, char *argv[]) return 0; } + +/** @} */ \ No newline at end of file diff --git a/server/src/receive.c b/server/src/receive.c index 4338fae19..85141895d 100644 --- a/server/src/receive.c +++ b/server/src/receive.c @@ -1,7 +1,10 @@ /** Receive messages from server snd print them on stdout. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC + * @file + * @addtogroup tools Test and debug tools + * @{ */ #include @@ -115,3 +118,5 @@ int main(int argc, char *argv[]) return 0; } + +/** @} */ \ No newline at end of file diff --git a/server/src/send.c b/server/src/send.c index 4a3aca59c..258c52136 100644 --- a/server/src/send.c +++ b/server/src/send.c @@ -1,7 +1,10 @@ /** Send messages from stdin to server. * * @author Steffen Vogel - * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @copyright 2015, Institute for Automation of Complex Power Systems, EONERC + * @file + * @addtogroup tools Test and debug tools + * @{ */ #include