From 9682a53a2c217430395225973b3b2fe1a3bf5ea7 Mon Sep 17 00:00:00 2001 From: Steffen Vogel Date: Thu, 5 Jun 2014 09:35:32 +0000 Subject: [PATCH] added more inline documentation git-svn-id: https://zerberus.eonerc.rwth-aachen.de:8443/svn/s2ss/trunk@54 8ec27952-4edc-4aab-86aa-e87bb2611832 --- include/cfg.h | 36 ++++++++++++++++++++++++++++++----- include/config.h | 6 ++++-- include/msg.h | 31 ++++++++++++------------------ include/node.h | 49 +++++++++++++++++++++++++++--------------------- include/path.h | 37 ++++++++++++++++++++---------------- include/utils.h | 32 +++++++++++++++---------------- src/cfg.c | 4 ++-- 7 files changed, 114 insertions(+), 81 deletions(-) diff --git a/include/cfg.h b/include/cfg.h index 15b02d6a8..ec4e7055b 100644 --- a/include/cfg.h +++ b/include/cfg.h @@ -1,8 +1,8 @@ -/** - * Configuration parser +/** Configuration file parser. * * @author Steffen Vogel * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @file cfg.h */ #ifndef _CFG_H_ @@ -13,6 +13,7 @@ struct node; struct path; +/// Global configuration struct config { /// Name of this node const char *name; @@ -27,7 +28,9 @@ struct config { /// Protocol version of UDP packages int protocol; /// Number of parsed paths - int path_count, node_count; + int path_count; + /// Number of parsed nodes + int node_count; /// libconfig object config_t obj; @@ -38,18 +41,41 @@ struct config { struct path *paths; }; -/** - * @brief Parse configuration file and store settings in suplied struct +/** Parse configuration file and store settings in supplied struct config. * * @param c A libconfig object * @param g The global configuration structure (also contains the config filename) */ int config_parse(config_t *c, struct config *g); +/** Parse the global section of a configuration file. + * + * @param c A libconfig object pointing to the root of the file + * @param g The global configuration file + * @return + * - 0 on success + * - otherwise an error occured + */ int config_parse_global(config_setting_t *c, struct config *g); +/** Parse a single path and add it to the global configuration. + * + * @param c A libconfig object pointing to the path + * @param g The global configuration file + * @return + * - 0 on success + * - otherwise an error occured + */ int config_parse_path(config_setting_t *c, struct config *g); +/** Parse a single node and add it to the global configuration. + * + * @param c A libconfig object pointing to the node + * @param g The global configuration file + * @return + * - 0 on success + * - otherwise an error occured + */ int config_parse_node(config_setting_t *c, struct config *g); #endif /* _CFG_H_ */ diff --git a/include/config.h b/include/config.h index a65f69246..42552f26f 100644 --- a/include/config.h +++ b/include/config.h @@ -1,8 +1,10 @@ -/** - * Configuration +/** Static server configuration + * + * This file contains some defines which are not part of the configuration file. * * @author Steffen Vogel * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @file config.h */ #ifndef _CONFIG_H_ diff --git a/include/msg.h b/include/msg.h index c4ae7e6c0..8b94d2ff9 100644 --- a/include/msg.h +++ b/include/msg.h @@ -1,8 +1,8 @@ -/** - * Message format +/** Message format and message related functions * * @author Steffen Vogel * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @file msg.h */ #ifndef _MSG_H_ @@ -15,10 +15,9 @@ #include "node.h" #if PROTOCOL == 0 -/** - * The format of a message (OPAL-RT example format) +/** The format of a message (OPAL-RT example format). * - * This struct defines the format of a message (protocol version 0) + * This struct defines the format of a message (protocol version 0). * Its declared as "packed" because it represents the "on wire" data. */ struct msg @@ -33,10 +32,9 @@ struct msg double data[MAX_VALUES]; } __attribute__((packed)); #elif PROTOCOL == 1 -/** - * Next generation message format for RTDS integration +/** Next generation message format for RTDS integration. * - * This struct defines the format of a message (protocol version 1) + * This struct defines the format of a message (protocol version 1). * Its declared as "packed" because it represents the "on wire" data. */ struct msg @@ -72,8 +70,7 @@ struct msg #error "Unknown protocol version!" #endif -/** - * @brief Print a raw UDP packge in human readable form +/** Print a raw UDP message in human readable form. * * @param f The file stream * @param msg A pointer to the message @@ -83,8 +80,7 @@ struct msg */ int msg_fprint(FILE *f, struct msg *m); -/** - * @brief Read a message from a file stream +/** Read a message from a file stream. * * @param f The file stream * @param m A pointer to the message @@ -94,15 +90,13 @@ int msg_fprint(FILE *f, struct msg *m); */ int msg_fscan(FILE *f, struct msg *m); -/** - * @brief Change the values of an existing message in a random fashion +/** Change the values of an existing message in a random fashion. * - * @param msg A pointer to the message whose values will be updated + * @param m A pointer to the message whose values will be updated */ void msg_random(struct msg *m); -/** - * @brief Send a message to a node +/** Send a message to a node. * * @param m A pointer to the message * @param n A pointer to the node @@ -112,8 +106,7 @@ void msg_random(struct msg *m); */ int msg_send(struct msg *m, struct node *n); -/** - * @brief Receive a message from a node +/** Receive a message from a node. * * @param m A pointer to the message * @param n A pointer to the node diff --git a/include/node.h b/include/node.h index d9d06df58..f9520d611 100644 --- a/include/node.h +++ b/include/node.h @@ -1,5 +1,4 @@ -/** - * Nodes +/** Nodes * * The S2SS server connects multiple nodes. * There are multiple types of nodes: @@ -9,6 +8,7 @@ * * @author Steffen Vogel * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @file node.h */ #ifndef _NODE_H_ @@ -17,6 +17,10 @@ #include #include +/** The type of a node. + * + * This type is used to determine the message format of the remote node + */ enum node_type { NODE_INVALID, @@ -27,32 +31,39 @@ enum node_type NODE_SIM_DSP }; +/** The datastructure for a node. + * + * Every entity which exchanges messages is represented by a node. + */ struct node { /// The socket descriptor int sd; - // Local address of the socket - struct sockaddr_in local; - - // Remote address of the socket - struct sockaddr_in remote; - /// The type of this node enum node_type type; + /// Local address of the socket + struct sockaddr_in local; + /// Remote address of the socket + struct sockaddr_in remote; + + /// A short identifier of the node const char *name; }; -/** - * @brief Create a new node +/** Create a new node. * * Memory is allocated dynamically and has to be freed by node_destroy() * - * @param n A pointer to the node structure - * @param name An acroynm, describing the node - * @param type The type of a node (server, simulator, workstation) + * @param n A pointer to the node structure. + * @param name An acroynm which describes the node. + * @param type The type of a node (server, simulator, workstation). + * @param local The local address of this node. + * This is where to server is listening for the arrival of new messages. + * @param remote The local address of this node. + * This is where messages are sent to. * @return * - 0 on success * - otherwise on error occured @@ -60,8 +71,7 @@ struct node int node_create(struct node *n, const char *name, enum node_type type, struct sockaddr_in local, struct sockaddr_in remote); -/** - * @brief Connect and bind the UDP socket of this node +/** Connect and bind the UDP socket of this node * * @param n A pointer to the node structure * @return @@ -70,8 +80,7 @@ int node_create(struct node *n, const char *name, enum node_type type, */ int node_connect(struct node *n); -/** - * @brief Disconnect the UDP socket of this node +/** Disconnect the UDP socket of this node. * * @param n A pointer to the node structure * @return @@ -80,16 +89,14 @@ int node_connect(struct node *n); */ int node_disconnect(struct node *n); -/** - * @brief Lookup node type from string +/** Lookup node type from string. * * @param str The string containing the node type * @return The node type enumeration value */ enum node_type node_lookup_type(const char *str); -/** - * @brief Search list of nodes for a name +/** Search list of nodes for a name. * * @param str The name of the wanted node * @param nodes A pointer to the first list element diff --git a/include/path.h b/include/path.h index b05686b80..0e575db3c 100644 --- a/include/path.h +++ b/include/path.h @@ -1,8 +1,8 @@ -/** - * Message paths +/** Message paths * * @author Steffen Vogel * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @file path.h */ #ifndef _PATH_H_ @@ -14,15 +14,22 @@ #include "node.h" #include "msg.h" -/** - * @brief The datastructure for a path +/** The datastructure for a path + * + * @todo Add support for multiple outgoing nodes */ struct path { - /// Pointers to the incoming and outgoing node - struct node *in, *out; + /// Pointer to the incoming node + struct node *in; + /// Pointer to the outgoing node + struct node *out; - /// If non NULL this function is called for every received message + /** If non NULL this function is called for every received message. + * + * This hook can be used to filter messages on a user-defined criteria. + * If the function has a non-zero return value the message will be dropped. + */ int (*hook)(struct msg *m); /// Counter for received messages @@ -37,25 +44,24 @@ struct path /// Last known message number unsigned int sequence; - /// The path thread + /// The thread for this path pthread_t tid; }; -/** - * @brief Setup a new path +/** Setup a new path. * * @param p A pointer to the path structure * @param in The node we are receiving messages from - * @param out The nodes we are sending to - * @param len count of outgoing nodes + * @param out The destination node * @return * - 0 on success * - otherwise an error occured */ int path_create(struct path *p, struct node *in, struct node *out); -/** - * @brief Start a path +/** Start a path. + * + * Start a new pthread for receiving/sending messages over this path. * * @param p A pointer to the path struct * @return @@ -64,8 +70,7 @@ int path_create(struct path *p, struct node *in, struct node *out); */ int path_start(struct path *p); -/** - * @brief Stop a path +/** Stop a path. * * @param p A pointer to the path struct * @return diff --git a/include/utils.h b/include/utils.h index 7c2fd5a67..9b46d89bf 100644 --- a/include/utils.h +++ b/include/utils.h @@ -1,8 +1,8 @@ -/** - * Some helper functions +/** Various helper functions * * @author Steffen Vogel * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC + * @file utils.h */ #ifndef _UTILS_H_ @@ -16,6 +16,7 @@ struct config; struct sockaddr_in; +/// The log level which is passed as first argument to print() enum log_level { DEBUG, @@ -24,27 +25,27 @@ enum log_level ERROR }; -/** - * @brief Logs variadic messages to stdout +/** Logs variadic messages to stdout. + * * @param lvl The log level * @param fmt The format string (printf alike) */ void print(enum log_level lvl, const char *fmt, ...); -/** - * @brief Resolve host/service name by local databases and/or nameservers +/** Resolve host/service name by local databases and/or nameservers. * * @param addr A string containing the hostname/ip and port seperated by a colon * @param sa A pointer to the resolved address * @param flags Flags for gai * @return * - 0 on success + * - otherwise an error occured */ int resolve(const char *addr, struct sockaddr_in *sa, int flags); -/** - * @brief Setup various realtime realated things +/** Setup various realtime related things. * + * We use the following techniques for performance tuning * - Prefault the stack * - Lock memory * - Use FIFO scheduler with realtime priority @@ -54,7 +55,7 @@ int resolve(const char *addr, struct sockaddr_in *sa, int flags); */ void realtime_init(struct config *g); -/// Check assertion and exit if failed +/// Check assertion and exit if failed. #define assert(exp) do { \ if (!(exp)) { \ print(ERROR, "Assertion failed: '%s' in %s, %s:%d", \ @@ -62,36 +63,36 @@ void realtime_init(struct config *g); exit(EXIT_FAILURE); \ } } while (0) -/// Printf alike debug message with level +/// Printf alike debug message with level. #define debug(lvl, msg, ...) do { \ if (lvl <= V) \ print(DEBUG, msg, ##__VA_ARGS__); \ } while (0) -/// Printf alike info message +/// Printf alike info message. #define info(msg, ...) do { \ print(INFO, msg, ##__VA_ARGS__); \ } while (0) -/// Printf alike warning message +/// Printf alike warning message. #define warn(msg, ...) do { \ print(WARN, msg, ##__VA_ARGS__); \ } while (0) -/// Print error and exit +/// Print error and exit. #define error(msg, ...) do { \ print(ERROR, msg, ##__VA_ARGS__); \ exit(EXIT_FAILURE); \ } while (0) -/// Print error and strerror(errno) +/// Print error and strerror(errno). #define perror(msg, ...) do { \ print(ERROR, msg ": %s", ##__VA_ARGS__, \ strerror(errno)); \ exit(EXIT_FAILURE); \ } while (0) -/// Print configuration error and exit +/// Print configuration error and exit. #define cerror(c, msg, ...) do { \ print(ERROR, msg " in %s:%u", ##__VA_ARGS__, \ config_setting_source_file(c), \ @@ -100,4 +101,3 @@ void realtime_init(struct config *g); } while (0) #endif /* _UTILS_H_ */ - diff --git a/src/cfg.c b/src/cfg.c index fde624c0a..d0cfb5c0e 100644 --- a/src/cfg.c +++ b/src/cfg.c @@ -15,7 +15,7 @@ #include "path.h" #include "utils.h" -int config_parse(config_t *cfg, struct config *g) +int config_parse(config_t *c, struct config *g) { config_setting_t *cfg_nodes, *cfg_paths, *cfg_root; @@ -27,7 +27,7 @@ int config_parse(config_t *cfg, struct config *g) ); } - cfg_root = config_root_setting(cfg); + cfg_root = config_root_setting(c); /* Read global settings */ config_parse_global(cfg_root, g);