mirror of
https://git.rwth-aachen.de/acs/public/villas/node/
synced 2025-03-30 00:00:11 +01:00
added more inline documentation
git-svn-id: https://zerberus.eonerc.rwth-aachen.de:8443/svn/s2ss/trunk@54 8ec27952-4edc-4aab-86aa-e87bb2611832
This commit is contained in:
parent
8842ffbd10
commit
9682a53a2c
7 changed files with 114 additions and 81 deletions
|
|
@ -1,8 +1,8 @@
|
|||
/**
|
||||
* Configuration parser
|
||||
/** Configuration file parser.
|
||||
*
|
||||
* @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
|
||||
* @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_ */
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
/**
|
||||
* Configuration
|
||||
/** Static server configuration
|
||||
*
|
||||
* This file contains some defines which are not part of the configuration file.
|
||||
*
|
||||
* @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
|
||||
* @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
|
||||
* @file config.h
|
||||
*/
|
||||
|
||||
#ifndef _CONFIG_H_
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
/**
|
||||
* Message format
|
||||
/** Message format and message related functions
|
||||
*
|
||||
* @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
|
||||
* @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
|
||||
|
|
|
|||
|
|
@ -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 <stvogel@eonerc.rwth-aachen.de>
|
||||
* @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
|
||||
* @file node.h
|
||||
*/
|
||||
|
||||
#ifndef _NODE_H_
|
||||
|
|
@ -17,6 +17,10 @@
|
|||
#include <sys/socket.h>
|
||||
#include <netinet/in.h>
|
||||
|
||||
/** 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
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
/**
|
||||
* Message paths
|
||||
/** Message paths
|
||||
*
|
||||
* @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
|
||||
* @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
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
/**
|
||||
* Some helper functions
|
||||
/** Various helper functions
|
||||
*
|
||||
* @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
|
||||
* @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_ */
|
||||
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue