updated documentation

git-svn-id: https://zerberus.eonerc.rwth-aachen.de:8443/svn/s2ss/trunk@95 8ec27952-4edc-4aab-86aa-e87bb2611832

include/cfg.h

@@ -2,7 +2,7 @@
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
- * @file cfg.h
+ * @file
  */
 
 #ifndef _CFG_H_
@@ -37,10 +37,12 @@ struct settings {
 
 /** Parse configuration file and store settings in supplied struct settings.
  *
- * @param cfg A libconfig object
- * @param set The global configuration structure (also contains the config filename)
- * @param nodes A pointer to a linked list of nodes which should be parsed
- * @param paths A pointer to a linked list of paths which should be parsed
+ * @param filename The path to the configration file (relative or absolute)
+ * @param cfg A initialized libconfig object
+ * @param set The global configuration structure
+ * @param nodes A linked list of nodes which should be parsed
+ * @param paths A linked list of paths which should be parsed
+ * @param interfaces A linked list of interfaces which should be parsed
  * @return
  *  - 0 on success
  *  - otherwise an error occured

include/config.h

@@ -4,7 +4,7 @@
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
- * @file config.h
+ * @file
  */
 
 #ifndef _CONFIG_H_
@@ -19,9 +19,6 @@
 /** Maximum number of registrable hook functions per path */
 #define MAX_HOOKS	5
 
-/** Size of the stack which gets prefaulted during initialization */
-#define MAX_SAFE_STACK	(16*1024)	/* 16 KiB */
-
 /** Socket priority */
 #define SOCKET_PRIO	7
 

include/if.h

@@ -2,7 +2,7 @@
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
- * @file if.h
+ * @file
  */
 
 #ifndef _IF_H_
@@ -11,8 +11,8 @@
 #include <sys/types.h>
 #include <net/if.h>
 
-#define IF_NAME_MAX	IFNAMSIZ
-#define IF_IRQ_MAX	3
+#define IF_NAME_MAX	IFNAMSIZ /**< Maximum length of an interface name */
+#define IF_IRQ_MAX	3	 /**< Maxmimal number of IRQs of an interface */
 
 /** Interface data structure */
 struct interface {

include/msg.h

@@ -2,7 +2,7 @@
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
- * @file msg.h
+ * @file
  */
 
 #ifndef _MSG_H_

include/node.h

@@ -8,7 +8,7 @@
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
- * @file node.h
+ * @file
  */
 
 #ifndef _NODE_H_

include/path.h

@@ -2,7 +2,7 @@
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
- * @file path.h
+ * @file
  */
 
 #ifndef _PATH_H_
@@ -47,9 +47,13 @@ struct path
 	unsigned int duplicated;
 	/** Last known message number */
 	unsigned int sequence;
+	/** Counter for received messages with invalid device id or data */
+	unsigned int invalid;
 
-	/** The thread ids for this path */
-	pthread_t tid, tid2;
+	/** The thread id for this path */
+	pthread_t tid;
+	/** A second thread id for fixed rate sending thread */
+	phtread_t tid2;
 	/** A pointer to the libconfig object which instantiated this path */
 	config_setting_t *cfg;
 

include/tc.h

@@ -1,8 +1,13 @@
-/**
- * Setup interface queuing desciplines for network emulation
+/** Setup interface queuing desciplines for network emulation
+ *
+ * We use the firewall mark to apply individual netem qdiscs
+ * per node. Every node uses an own BSD socket.
+ * By using so SO_MARK socket option (see socket(7))
+ * we can classify traffic originating from a node seperately.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
+ * @file
  */
 
 #ifndef _TC_H_
@@ -10,25 +15,38 @@
 
 #include <stdint.h>
 
-/* Some helper for TC handles */
+/** A type alias for TC handles.
+ *
+ * TC handles are used to construct a tree
+ * of classes, qdiscs and filters.
+ */
 typedef uint32_t tc_hdl_t;
 
+/** Concatenate 16 bit minor and majar parts to a 32 bit tc handle */
 #define TC_HDL(maj, min)	((maj & 0xFFFF) << 16 | (min & 0xFFFF))
+/** Get the major part of a tc handle */
 #define TC_HDL_MAJ(h)		((h >> 16) & 0xFFFF)
+/** Get the minor part of a tc handle */
 #define TC_HDL_MIN(h)		((h >>  0) & 0xFFFF)
+/** The root handle */
 #define TC_HDL_ROOT		(0xFFFFFFFFU)
 
 /* Bitfield for valid fields in struct netem */
-#define TC_NETEM_LIMIT		(1 << 0)
-#define TC_NETEM_DELAY		(1 << 1)
-#define TC_NETEM_JITTER		(1 << 2)
-#define TC_NETEM_DISTR		(1 << 3)
-#define TC_NETEM_LOSS		(1 << 4)
-#define TC_NETEM_CORRUPT	(1 << 5)
-#define TC_NETEM_DUPL		(1 << 6)
+#define TC_NETEM_LIMIT		(1 << 0) /**< netem::limit is valid @see netem::valid */
+#define TC_NETEM_DELAY		(1 << 1) /**< netem::delay is valid @see netem::valid */
+#define TC_NETEM_JITTER		(1 << 2) /**< netem::jitter is valid @see netem::valid */
+#define TC_NETEM_DISTR		(1 << 3) /**< netem::distribution is valid @see netem::valid */
+#define TC_NETEM_LOSS		(1 << 4) /**< netem::loss is valid @see netem::valid */
+#define TC_NETEM_CORRUPT	(1 << 5) /**< netem::corrupt is valid @see netem::valid */
+#define TC_NETEM_DUPL		(1 << 6) /**< netem::duplicate is valid @see netem::valid */
 
 struct interface;
 
+/** Netem configuration settings
+ *
+ * This struct is used to pass the netem configuration
+ * from config_parse_netem() to tc_netem()
+ */
 struct netem {
 	/** Which fields of this struct contain valid data (TC_NETEM_*). */
 	char valid;
@@ -52,15 +70,17 @@ struct netem {
 /** Remove all queuing disciplines and filters 
  *
  * @param i The interface
+ * @return
+ *  - 0 on success
+ *  - otherwise an error occured
  */
 int tc_reset(struct interface *i);
 
 /** Create a prio queueing discipline
  *
  * @param i The interface
- * @param parent
- * @param handle
- * @param bands
+ * @param handle The handle for the new qdisc
+ * @param bands The number of classes for this new qdisc
  * @return
  *  - 0 on success
  *  - otherwise an error occured
@@ -70,11 +90,23 @@ int tc_prio(struct interface *i, tc_hdl_t handle, int bands);
 /** Add a new network emulator discipline
  *
  * @param i The interface
- * @param parent Make this
+ * @param parent Make this qdisc a child of
+ * @param em The netem settings
+ * @return
+ *  - 0 on success
+ *  - otherwise an error occured
  */
 int tc_netem(struct interface *i, tc_hdl_t parent, struct netem *em);
 
-/** Add a new fwmark filter */
+/** Add a new filter based on the netfilter mark
+ *
+ * @param i The interface
+ * @param flowid The destination class for matched traffic
+ * @param mark The netfilter firewall mark (sometime called 'fwmark')
+ * @return
+ *  - 0 on success
+ *  - otherwise an error occured
+*/
 int tc_mark(struct interface *i, tc_hdl_t flowid, int mark);
 
 #endif /* _TC_H_ */

include/utils.h

@@ -2,7 +2,7 @@
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
- * @file utils.h
+ * @file
  */
 
 #ifndef _UTILS_H_
@@ -16,13 +16,13 @@
 #include <sched.h>
 
 /* Some color escape codes for pretty log messages */
-#define RED(str)	"\x1B[31m" str "\x1B[0m"
-#define GRN(str)	"\x1B[32m" str "\x1B[0m"
-#define YEL(str)	"\x1B[33m" str "\x1B[0m"
-#define BLU(str)	"\x1B[34m" str "\x1B[0m"
-#define MAG(str)	"\x1B[35m" str "\x1B[0m"
-#define CYN(str)	"\x1B[36m" str "\x1B[0m"
-#define WHT(str)	"\x1B[37m" str "\x1B[0m"
+#define RED(str)	"\x1B[31m" str "\x1B[0m" /**< Print str in red */
+#define GRN(str)	"\x1B[32m" str "\x1B[0m" /**< Print str in green */
+#define YEL(str)	"\x1B[33m" str "\x1B[0m" /**< Print str in yellow */
+#define BLU(str)	"\x1B[34m" str "\x1B[0m" /**< Print str in blue */
+#define MAG(str)	"\x1B[35m" str "\x1B[0m" /**< Print str in magenta */
+#define CYN(str)	"\x1B[36m" str "\x1B[0m" /**< Print str in cyan */
+#define WHT(str)	"\x1B[37m" str "\x1B[0m" /**< Print str in white */
 
 /** The log level which is passed as first argument to print() */
 enum log_level { DEBUG, INFO, WARN, ERROR };

src/cfg.c

@@ -1,5 +1,4 @@
-/**
- * Configuration parser
+/** Configuration parser
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/if.c

@@ -1,5 +1,4 @@
-/**
- * Interface related functions
+/** Interface related functions
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/msg.c

@@ -1,5 +1,4 @@
-/**
- * Message related functions
+/** Message related functions
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/node.c

@@ -1,5 +1,4 @@
-/**
- * Nodes
+/** Nodes
  *
  * The S2SS server connects multiple nodes.
  * There are multiple types of nodes:

src/path.c

@@ -1,5 +1,4 @@
-/**
- * Message paths
+/** Message paths
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/random.c

@@ -1,5 +1,4 @@
-/**
- * Generate random packages on stdout
+/** Generate random packages on stdout
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/receive.c

@@ -1,5 +1,4 @@
-/**
- * Receive messages from server snd print them on stdout
+/** Receive messages from server snd print them on stdout
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/send.c

@@ -1,5 +1,4 @@
-/**
- * Send messages from stdin to server
+/** Send messages from stdin to server
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/server.c

@@ -1,5 +1,4 @@
-/**
- * Main routine
+/** Main routine
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/tc.c

@@ -1,5 +1,6 @@
-/**
- * Traffic control: setup interface queuing desciplines
+/** Traffic control: setup interface queuing desciplines
+ *
+ * S2SS uses these functions to setup the network emulation feature.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/test.c

@@ -1,5 +1,4 @@
-/**
- * Some basic tests
+/** Some basic tests
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

src/utils.c

@@ -1,5 +1,4 @@
-/**
- * Some helper functions
+/** Some helper functions
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC