NDT-DEV email list created

Revision: 632
Author:   

Date:     Fri Sep 16 08:39:32 2011
Log:      Inline documentation for SFW test, util and odbc related files,  
few more changes to standardize comments in network.c
http://code.google.com/p/ndt/source/detail?r=632

Modified:
 /branches/kkumar_code_organize/src/ndt_odbc.c
 /branches/kkumar_code_organize/src/network.c
 /branches/kkumar_code_organize/src/test_sfw_srv.c
 /branches/kkumar_code_organize/src/testoptions.c
 /branches/kkumar_code_organize/src/web100-util.c

=======================================
--- /branches/kkumar_code_organize/src/ndt_odbc.c       Wed Oct 10 14:09:36 
2007
+++ /branches/kkumar_code_organize/src/ndt_odbc.c       Fri Sep 16 08:39:32 
2011
@@ -93,6 +93,14 @@
                           ");";
 char createTableStmt[2048];

+/**
+ * Retrieves all the diagnostics
+ *  associated with that a given SQL handle
+ * @param fn pointer to function name string
+ * @param handle SQLHandle
+ * @param type SQLHandle type
+ * */
+
 static void
 extract_error(char *fn, SQLHANDLE handle, SQLSMALLINT type)
 {
@@ -106,6 +114,8 @@
     log_println(2, "\nThe driver reported the following diagnostics whilst  
running %s:\n", fn);
     do
     {
+    	// get current values of multiple fields(error, warning, and status)  
of diagnostic record
+       // and see if return value indicated success
         ret = SQLGetDiagRec(type, handle, ++i, state, &native, text,
                             sizeof(text), &len );
         if (SQL_SUCCEEDED(ret))
@@ -115,6 +125,14 @@
 }
 #endif

+/**
+ * Initialize Database
+ * @param options integer indicating whether DB should be used
+ * @param dsn data source name string pointer
+ * @param uid User name string pointer the db uses for authentication
+ * @param pwd pointer to password string pointer the db uses for  
authentication
+ * @return integer 0 if success, 1 if failure
+ * */
 int
 initialize_db(int options, char* dsn, char* uid, char* pwd)
 {
@@ -129,13 +147,14 @@
         log_println(1, "Initializing DB with DSN='%s', UID='%s', PWD=%s",  
dsn, uid, pwd ? "yes" : "no");
         sprintf(createTableStmt, "%s%s%s%s", ctStmt_1, ctStmt_2, ctStmt_3,  
ctStmt_4);

-        /* Allocate an environment handle */
+        // Allocate an environment handle
         SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &env);
-        /* We want ODBC 3 support */
+        // We want ODBC 3 support
         SQLSetEnvAttr(env, SQL_ATTR_ODBC_VERSION, (void *) SQL_OV_ODBC3,  
0);
-        /* Allocate a connection handle */
+        // Allocate a connection handle
         SQLAllocHandle(SQL_HANDLE_DBC, env, &dbc);
-        /* Connect to the DSN */
+        // Connect to the DSN after creating summarizing login data
+        // into "loginstring"
         memset(loginstring, 0, 1024);
         snprintf(loginstring, 256, "DSN=%s;", dsn);
         if (uid) {
@@ -161,45 +180,46 @@
             extract_error("SQLDriverConnect", dbc, SQL_HANDLE_DBC);
             return 1;
         }
-        /* Allocate a statement handle */
+        // Allocate a statement handle
         ret = SQLAllocHandle(SQL_HANDLE_STMT, dbc, &stmt);
         if (!SQL_SUCCEEDED(ret)) {
             log_println(0, "  Failed to alloc statement handle\n  
Continuing without DB logging");
             extract_error("SQLAllocHandle", dbc, SQL_HANDLE_DBC);
             return 1;
         }
-        /* Retrieve a list of tables */
+        // Retrieve a list of tables
         ret = SQLTables(stmt, NULL, 0, NULL, 0, NULL, 0, (unsigned  
char*) "TABLE", SQL_NTS);
         if (!SQL_SUCCEEDED(ret)) {
             log_println(0, "  Failed to fetch table info\n Continuing  
without DB logging");
             extract_error("SQLTables", dbc, SQL_HANDLE_DBC);
             return 1;
         }
-        /* How many columns are there */
+        // How many columns are there?
         SQLNumResultCols(stmt, &columns);

-        /* Loop through the rows in the result-set */
+        // Loop through the rows in the result-set
         while (SQL_SUCCEEDED(ret = SQLFetch(stmt))) {
             SQLUSMALLINT i;
-            /* Loop through the columns */
+            // Loop through the columns
             for (i = 2; i <= columns; i++) {
                 SQLINTEGER indicator;
                 char buf[512];
-                /* retrieve column data as a string */
+                // retrieve column data as a string
                 ret = SQLGetData(stmt, i, SQL_C_CHAR,
                         buf, sizeof(buf), &indicator);
                 if (SQL_SUCCEEDED(ret)) {
-                    /* Handle null columns */
+                    // Handle null columns
                     if (indicator == SQL_NULL_DATA) strcpy(buf, "NULL");
                     if (strcmp(buf, "ndt_test_results") == 0) {
-                        /* the table exists - do nothing */
+                        // the table exists - do nothing
                         SQLFreeStmt(stmt, SQL_CLOSE);
                         return 0;
                     }
                 }
             }
         }
-        /* the table doesn't exist - create the one */
+
+        // the table doesn't exist - create it
         SQLFreeStmt(stmt, SQL_CLOSE);
         log_print(1, "The table 'ndt_test_results' doesn't exist,  
creating...");
         ret = SQLExecDirect(stmt, (unsigned char*) createTableStmt,  
strlen(createTableStmt));
@@ -217,6 +237,11 @@
 #endif
 }

+/**
+ * Insert row of test results into Database
+ * @params All parameters related to test results collected
+ * @return integer 0 if success, 1 if failure
+ * */
 int
 db_insert(char spds[4][256], float runave[], char* cputimelog, char*  
snaplog, char* c2s_snaplog,
         char* hostName, int testPort,
=======================================
--- /branches/kkumar_code_organize/src/network.c        Tue Sep 13 07:04:10 
2011
+++ /branches/kkumar_code_organize/src/network.c        Fri Sep 16 08:39:32 
2011
@@ -136,15 +136,14 @@
 }

 /**
- * Function name: CreateListenSocket
- * Description: Creates the I2Addr structure with the listen socket.
- * Arguments: addr - the I2Addr structure, where listen socket should
+ * Creates the I2Addr structure with the listen socket.
+ * @param addr  the I2Addr structure, where listen socket should
  *                   be added, or NULL, if the new structure should be
  *                   created
- *            serv - the port number
- *            options - the binding socket options
- *            buf_sixe - manually set the TCP send/receive socket buffer
- * Returns: The I2Addr structure with the listen socket.
+ * @param serv  the port number
+ * @param options the binding socket options
+ * @param buf_size manually set the TCP send/receive socket buffer
+ * @returns I2Addr structure with the listen socket.
  */

 I2Addr
@@ -437,6 +436,10 @@
  *            len - the target place for the length of the message
  * Returns: 0 - success
  *          !0 - error code.
+ *          Error codes:
+ *          -1 : Error reading from socket
+ *          -2 : No of bytes received were lesser than expected byte count
+ *          -3 : No of bytes received did not match expected byte count
  */

 int
@@ -449,12 +452,17 @@
   assert(msg);
   assert(len);

+  // if 3 bytes are not explicitly read, signal error
   if (readn(ctlSocket, buff, 3) != 3) {
     return -1;
   }
+
+  // get msg type, and calculate length as sum of the next 2 bytes
   *type = buff[0];
   length = buff[1];
   length = (length << 8) + buff[2];
+
+  // if received buffer size < length as conveyed by buffer contents, then  
error
   assert(length <= (*len));
   if (length > (*len)) {
     log_println(3, "recv_msg: length [%d] > *len [%d]", length, *len);
@@ -535,7 +543,7 @@
    */
   while (received < amount) {

-       // check if fd_1 sockets are ready to be read
+       // check if fd+1 socket is ready to be read
     rc = select(fd+1, &rfd, NULL, NULL, &sel_tv);
     if (rc == 0) {  /* A timeout occurred, nothing to read from socket  
after 3 seconds */
       log_println(6, "readn() routine timeout occurred, return error  
signal and kill off child");
=======================================
--- /branches/kkumar_code_organize/src/test_sfw_srv.c	Fri Apr  9 09:23:03  
2010
+++ /branches/kkumar_code_organize/src/test_sfw_srv.c	Fri Sep 16 08:39:32  
2011
@@ -23,10 +23,9 @@
 static int toWait = 1;
 static pthread_t threadId = -1;

-/*
- * Function name: catch_alrm
- * Description: Prints the appropriate message when the SIGALRM is catched.
- * Arguments: signo - the signal number (shuld be SIGALRM)
+/**
+ * Prints the appropriate message when the SIGALRM is caught.
+ * @param signo Signal number (should be SIGALRM)
  */

 void
@@ -43,10 +42,13 @@
   log_println(0, "Unknown (%d) signal was caught", signo);
 }

-/*
- * Function name: test_osfw_srv
- * Description: Performs the server part of the opposite Simple
- *              firewall test in the separate thread.
+/**
+ * Performs the server part of the opposite Simple
+ *              firewall test in a separate thread.
+ * In other words, sends the S->C TEST_MSG with message body
+ * "Simple firewall test"
+ * @param vptr void pointer
+ * @todo protocol validation log at line 67
  */

 void*
@@ -55,17 +57,21 @@
   int sfwsock;
   struct sigaction new, old;

-  /* ignore the alrm signal */
+  // ignore the alarm signal
   memset(&new, 0, sizeof(new));
   new.sa_handler = catch_alrm;
   sigaction(SIGALRM, &new, &old);
   alarm(testTime);
+
+  // connect to client and send TEST_MSG message containing a pre-defined  
string
   if (CreateConnectSocket(&sfwsock, NULL, sfwcli_addr, 0, 0) == 0) {
     send_msg(sfwsock, TEST_MSG, "Simple firewall test", 20);
   }
+
   alarm(0);
   sigaction(SIGALRM, &old, NULL);

+  // signal sleeping threads to wake up
   pthread_mutex_lock( &mainmutex);
   toWait = 0;
   pthread_cond_broadcast(&maincond);
@@ -74,35 +80,42 @@
   return NULL;
 }

-/*
- * Function name: finalize_sfw
- * Description: Waits for the every thread to accomplish and finalizes
+/**
+ * Wait for the every thread to conclude and finalize
  *              the SFW test.
- * Arguments: ctlsockfd - the client control socket descriptor
+ * @param ctlsockfd Client control socket descriptor
+ * @todo protocol validation log at line 97
  */

 void
 finalize_sfw(int ctlsockfd)
 {
+  // wait for mutex to be released before attempting to finalize
   while (toWait) {
     pthread_mutex_lock( &mainmutex);
     pthread_cond_wait(&maincond, &mainmutex);
     pthread_mutex_unlock( &mainmutex);
   }
+
+  // close the SFW test by sending a nil (0 length) message and set test  
status
   send_msg(ctlsockfd, TEST_FINALIZE, "", 0);
   log_println(1, " <-------------------------->");
   setCurrentTest(TEST_NONE);
 }

-/*
- * Function name: test_sfw_srv
- * Description: Performs the server part of the Simple firewall test.
- * Arguments: ctlsockfd - the client control socket descriptor
- *            options - the test options
- *            conn_options - the connection options
- * Returns: 0 - success (no firewalls on the path),
- *          1 - failure (protocol mismatch),
- *          2 - unknown (probably firwall on the path).
+/**
+ * Performs the server part of the Simple firewall test.
+ * @param ctlsockfd Client control socket descriptor
+ * @param agent web100_agent
+ * @param options The test options
+ * @param conn_options The connection options
+ * @returns Integer with values:
+ *                     0 - success (no firewalls on the path),
+ *          1 - Message reception errors/inconsistencies
+ *			2 - Unexpected message type received/no message received due to  
timeout
+ *                     3 - erroneous message  reception
+ *                     4 - Client port number not received
+ *                     5 - Unable to resolve client address
  */

 int
@@ -130,6 +143,7 @@
     setCurrentTest(TEST_SFW);
     log_println(1, " <-- %d - Simple firewall test -->", options->child0);

+    // bind to a new port and obtain address structure with details of  
port etc
     sfwsrv_addr = CreateListenSocket(NULL, "0", conn_options, 0);
     if (sfwsrv_addr == NULL) {
       log_println(0, "Server (Simple firewall test): CreateListenSocket  
failed: %s", strerror(errno));
@@ -137,16 +151,25 @@
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       return -1;
     }
+
+    // get socket FD and the ephemeral port number to be used
     sfwsockfd = I2AddrFD(sfwsrv_addr);
     sfwsockport = I2AddrPort(sfwsrv_addr);
     log_println(1, "  -- port: %d", sfwsockport);

+
     cn = web100_connection_from_socket(agent, ctlsockfd);
     if (cn) {
+
+      // Get remote end's address
       web100_agent_find_var_and_group(agent, "RemAddress", &group, &var);
       web100_raw_read(var, cn, buff);
       memset(hostname, 0, 256);
       strncpy(hostname, web100_value_to_text(web100_get_var_type(var),  
buff), 255);
+
+      // Determine test time in seconds.
+      // test-time = max(round trip time, timeout) > 3 ? 3 : 1
+
       web100_agent_find_var_and_group(agent, "MaxRTT", &group, &var);
       web100_raw_read(var, cn, buff);
       maxRTT = atoi(web100_value_to_text(web100_get_var_type(var), buff));
@@ -170,14 +193,19 @@
     }
     log_println(1, "  -- SFW time: %d", testTime);

+    // try sending TEST_PREPARE msg with ephemeral port number to client.
+    // If unable to, return
     sprintf(buff, "%d %d", sfwsockport, testTime);
     if ((rc = send_msg(ctlsockfd, TEST_PREPARE, buff, strlen(buff))) < 0)
-       return (rc);
-
+       return (rc);
+
+    // Listen for TEST_MSG from client's port number sent as data.
+    // Any other type of message is unexpected at this juncture.
     msgLen = sizeof(buff);
-    if (recv_msg(ctlsockfd, &msgType, buff, &msgLen)) {
+    if (recv_msg(ctlsockfd, &msgType, buff, &msgLen)) { // message  
reception error
       log_println(0, "Protocol error!");
       sprintf(buff, "Server (Simple firewall test): Invalid port number  
received");
+         //TODO above seems incorrect w.r.t the erroe message too
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       I2AddrFree(sfwsrv_addr);
       return 1;
@@ -189,15 +217,18 @@
       I2AddrFree(sfwsrv_addr);
       return 2;
     }
-    if (msgLen <= 0) {
+    if (msgLen <= 0) { // message reception has error
       log_println(0, "Improper message");
+      // TODO: why are log messages and msg to client different? why is  
the only
+      // status used all over here == Invalid port number?
       sprintf(buff, "Server (Simple firewall test): Invalid port number  
received");
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       I2AddrFree(sfwsrv_addr);
       return 3;
     }
+
     buff[msgLen] = 0;
-    if (check_int(buff, &sfwport)) {
+    if (check_int(buff, &sfwport)) { // message data is not number, thus  
no port info received
       log_println(0, "Invalid port number");
       sprintf(buff, "Server (Simple firewall test): Invalid port number  
received");
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
@@ -205,8 +236,10 @@
       return 4;
     }

+    // Get node, port(if present) and other details of client end.
+    // If not able to resolve it, the test cannot proceed to  
the "throughput" stage
     if ((sfwcli_addr = I2AddrByNode(get_errhandle(), hostname)) == NULL) {
-      log_println(0, "Unable to resolve server address");
+      log_println(0, "Unable to resolve server address"); //todo is'nt  
this client address we cannot resolve?
       send_msg(ctlsockfd, TEST_FINALIZE, "", 0);
       log_println(1, " <-------------------------->");
       I2AddrFree(sfwsrv_addr);
@@ -215,15 +248,23 @@
     I2AddrSetPort(sfwcli_addr, sfwport);
     log_println(1, "  -- oport: %d", sfwport);

+    // send S->C side TEST_MSG
     send_msg(ctlsockfd, TEST_START, "", 0);
+
+    // send the S->C default test message in a separate thread to client
     pthread_create(&threadId, NULL, &test_osfw_srv, NULL);

     FD_ZERO(&fds);
     FD_SET(sfwsockfd, &fds);
     sel_tv.tv_sec = testTime;
     sel_tv.tv_usec = 0;
+
+    // determine status of listening socket - looking for TEST_MSG from  
client.
+    // The following switch statement checks for cases where this socket  
status
+    // indicates error , and finalizes the test at this point.
+
     switch (select(sfwsockfd+1, &fds, NULL, NULL, &sel_tv)) {
-      case -1:
+      case -1:  // If SOCKET_ERROR - status of firewall unknown
         log_println(0, "Simple firewall test: select exited with error");
         sprintf(buff, "%d", SFW_UNKNOWN);
         send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
@@ -231,7 +272,7 @@
         I2AddrFree(sfwsrv_addr);
         I2AddrFree(sfwcli_addr);
         return 1;
-      case 0:
+      case 0: // Time expiration. SFW possible in C->S side
         log_println(0, "Simple firewall test: no connection for %d  
seconds", testTime);
         sprintf(buff, "%d", SFW_POSSIBLE);
         send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
@@ -240,11 +281,16 @@
         I2AddrFree(sfwcli_addr);
         return 2;
     }
+
+    // Now read actual data from the sockets listening for client message.
+    // Based on data, conclude SFW status and send TEST_MSG with result.
+    // In all cases, finalize the test
+
     clilen = sizeof(cli_addr);
     sockfd = accept(sfwsockfd, (struct sockaddr *) &cli_addr, &clilen);

     msgLen = sizeof(buff);
-    if (recv_msg(sockfd, &msgType, buff, &msgLen)) {
+    if (recv_msg(sockfd, &msgType, buff, &msgLen)) { // message received  
in error
       log_println(0, "Simple firewall test: unrecognized message");
       sprintf(buff, "%d", SFW_UNKNOWN);
       send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
@@ -255,6 +301,7 @@
       return 1;
     }
     if (check_msg_type("Simple firewall test", TEST_MSG, msgType, buff,  
msgLen)) {
+       // unexpected message type received
       sprintf(buff, "%d", SFW_UNKNOWN);
       send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
       close(sockfd);
@@ -263,7 +310,8 @@
       I2AddrFree(sfwcli_addr);
       return 1;
     }
-    if (msgLen != 20) {
+    if (msgLen != 20) { // Expecting default 20 byte long "Simple firewall  
test" message
+       // todo define constants for 20 and default message string
       log_println(0, "Simple firewall test: Improper message");
       sprintf(buff, "%d", SFW_UNKNOWN);
       send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
@@ -275,6 +323,7 @@
     }
     buff[msgLen] = 0;
     if (strcmp(buff, "Simple firewall test") != 0) {
+       // Message was of correct length, but was not expected content-wise
       log_println(0, "Simple firewall test: Improper message");
       sprintf(buff, "%d", SFW_UNKNOWN);
       send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
@@ -285,6 +334,7 @@
       return 1;
     }

+    // All messages were received correctly, hence no firewall
     sprintf(buff, "%d", SFW_NOFIREWALL);
     send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
     close(sockfd);
=======================================
--- /branches/kkumar_code_organize/src/testoptions.c	Sun May  8 04:04:21  
2011
+++ /branches/kkumar_code_organize/src/testoptions.c	Fri Sep 16 08:39:32  
2011
@@ -1264,7 +1264,7 @@
         for (;;) {
           ret = select(mon_pipe2[0]+1, &rfd, NULL, NULL, &sel_tv);
           if ((ret == -1) && (errno == EINTR)) {
-	    log_println(6, "Inerrupt received while waiting for s2c select90 to  
finish, continuing");
+	    log_println(6, "Interrupt received while waiting for s2c select90 to  
finish, continuing");
             continue;
          }
          if (((ret == -1) && (errno != EINTR)) || (ret == 0)) {
@@ -1304,6 +1304,7 @@

     /* alarm(30); */  /* reset alarm() again, this 10 sec test should  
finish before this signal
                  * is generated.  */
+    // Get web100 variables from snapshot taken earlier and send to client
     log_println(6, "S2C-Send web100 data vars to client pid=%d", mon_pid2);
     ret = web100_get_data(tsnap, ctlsockfd, agent, count_vars);
     web100_snapshot_free(tsnap);
=======================================
--- /branches/kkumar_code_organize/src/web100-util.c	Mon Mar 22 20:56:00  
2010
+++ /branches/kkumar_code_organize/src/web100-util.c	Fri Sep 16 08:39:32  
2011
@@ -16,9 +16,16 @@
 #include "utils.h"
 #include "protocol.h"

-/*
+/**
  * set up the necessary structures for monitoring connections at the
  * beginning
+ * @param *VarFileName pointer to file name of Web100 variables
+ * @return integer indicating number of web100 variables read
+ *     , or indicating failure of initialization
+ *  Error codes:
+ *     5 : Unable to open web100 variable file
+ *     -1: TODO :When is -1 returned? Calling code seems to rely on -1?
+ *
  */
 int
 web100_init(char *VarFileName)
@@ -30,14 +37,15 @@

   assert(VarFileName);

-  if((fp = fopen(VarFileName, "r")) == NULL) {
+  if((fp = fopen(VarFileName, "r")) == NULL) { // unable to open web100  
variable file
     err_sys("Required Web100 variables file missing, use -f option to  
specify file location\n");
     exit(5);
   }

-  while (fgets(line, 255, fp) != NULL) {
-    if ((line[0] == '#') || (line[0] == '\n'))
+  while (fgets(line, 255, fp) != NULL) { // read file linewise
+    if ((line[0] == '#') || (line[0] == '\n')) // if newline or comment,  
ignore
       continue;
+    // copy web100 variable into our array and increment count of read  
variables
     strncpy(web_vars[count_vars].name, line, (strlen(line)-1));
     count_vars++;
   }
@@ -47,6 +55,25 @@
   return(count_vars);
 }

+/**
+ * Performs part of the middlebox test.
+ * The server sets the maximum value of the
+ * congestion window, and starts a 5 second long
+ *  throughput test using the newly created connection.
+ *
+ *  The NDT server then sends packets contiguously.
+ *    These are written using a buffer of the size of the current MSS or
+ *    8192 bytes.
+ *
+ * @TODO Why is this method in web100-util.c?
+ * @param sock integer socket file descriptor
+ * @param agent pointer to a web100_agent
+ * @param cn pointer to the web100_connection
+ * @param results pointer to string containing Server address , client  
address
+ *                      currentMSS, WinScaleSent and WinScaleRecv values
+ *
+ *
+ */
 void
 web100_middlebox(int sock, web100_agent* agent, web100_connection* cn,  
char *results)
 {
@@ -56,7 +83,7 @@
   web100_snapshot* snap;
   char buff[8192], line[256];
   char* sndbuff;
-  int i, j, k, octets=0;
+  int i, j, k, currentMSSval =0;
   int SndMax=0, SndUna=0;
   fd_set wfd;
   struct timeval sel_tv;
@@ -67,6 +94,7 @@
   web100_var *LimCwnd;
   u_int32_t limcwnd_val;

+  // middlebox test results
   static char vars[][255] = {
     "CurMSS",
     "WinScaleSent",
@@ -77,17 +105,29 @@

   log_println(4, "Looking for Web100 data on socketid %d", sock);

+  // get Server address and add to "results"
+
+  // get socket name
   addr = I2AddrByLocalSockFD(get_errhandle(), sock, False);
   memset(tmpstr, 0, 200);
+  // copy address into tmpstr String
   I2AddrNodeName(addr, tmpstr, &tmpstrlen);
+  // now copy tmpstr containing address into "line"
   sprintf(line, "%s;", tmpstr);
   memset(tmpstr, 0, 200);
+  // service name into tmpstr
   I2AddrServName(addr, tmpstr, &tmpstrlen);
   log_print(3, "Server: %s%s ",  line, tmpstr);
+  // copy servers address into the meta test struct
   memcpy(meta.server_ip, line, strlen(line));
+  // terminate the IP address string
   meta.server_ip[(strlen(line)-1)] = 0;
+  // Add this address to results
   strncat(results, line, strlen(line));
-  I2AddrFree(addr);
+  I2AddrFree(addr); // free memory
+
+  // Now perform the above set of functions for client address/service name
+  // and copy into results
   tmpstrlen = sizeof(tmpstr);
   addr = I2AddrBySockFD(get_errhandle(), sock, False);
   memset(tmpstr, 0, 200);
@@ -98,19 +138,25 @@
   strncat(results, line, strlen(line));
   I2AddrFree(addr);

+  // get web100 values for the middlebox test result group
   for (i=0; i<3; i++) {
+       // read web100_group and web100_var of vars[i] into group and var
     web100_agent_find_var_and_group(agent, vars[i], &group, &var);
-    web100_raw_read(var, cn, buff);
+    web100_raw_read(var, cn, buff); // read variable value from web100  
connection
+
+    // get current MSS in textual format and append to results
+
+    //get current MSS value and append to "results"
     if (strcmp(vars[i], "CurMSS") == 0)
-      octets = atoi(web100_value_to_text(web100_get_var_type(var), buff));
+    	currentMSSval = atoi(web100_value_to_text(web100_get_var_type(var),  
buff));
     sprintf(line, "%s;", web100_value_to_text(web100_get_var_type(var),  
buff));
-    if (strcmp(line, "4294967295;") == 0)
+    if (strcmp(line, "4294967295;") == 0) // TODO what is this number?
       sprintf(line, "%d;", -1);
     strcat(results, line);
     log_print(3, "%s",  line);
   }
   log_println(3, "");
-  log_println(0, "Sending %d Byte packets over the network", octets);
+  log_println(0, "Sending %d Byte packets over the network",  
currentMSSval);

   /* The initial check has been completed, now stream data to the remote  
client
    * for 5 seconds with very limited buffer space.  The idea is to see if  
there
@@ -119,53 +165,70 @@
    * RAC 2/28/06
    */

+  // get web100_var and web100_group
   web100_agent_find_var_and_group(agent, "LimCwnd", &group, &LimCwnd);
-  limcwnd_val = 2 * octets;
+
+  // set TCP CWND web100 variable to twice the current MSS Value
+  limcwnd_val = 2 * currentMSSval;
   web100_raw_write(LimCwnd, cn, &limcwnd_val);
   log_println(5, "Setting Cwnd Limit to %d octets", limcwnd_val);

-  sndbuff = malloc(octets);
-  if (sndbuff == NULL) {
+  // try to allocate memory of the size of current MSS Value
+  sndbuff = malloc(currentMSSval);
+  if (sndbuff == NULL) { // not possible, use 8192 bytes
     log_println(0, "Failed to allocate memory --> switching to 8192 Byte  
packets");
     sndbuff = buff;
-    octets = 8192;
+    currentMSSval = 8192; //todo define constant
   }
   if (getuid() == 0) {
     system("echo 1 > /proc/sys/net/ipv4/route/flush");
   }
+
+  // fill send buffer with random printable data
+
   k=0;
-  for (j=0; j<octets; j++) {
-    while (!isprint(k & 0x7f))
+  for (j=0; j<currentMSSval; j++) {
+    while (!isprint(k & 0x7f)) // Is character printable?
       k++;
     sndbuff[j] = (k++ & 0x7f);
   }

+  // search web100 group with name "read"?
   group = web100_group_find(agent, "read");
   snap = web100_snapshot_alloc(group, cn);

   FD_ZERO(&wfd);
   FD_SET(sock, &wfd);
-  sel_tv.tv_sec = 5;
-  sel_tv.tv_usec = 0;
+  // TODO: define constants for 5 seconds, 0 ms
+  sel_tv.tv_sec = 5; // 5 seconds maximum for select call below to complete
+  sel_tv.tv_usec = 0; // 5s + 0ms
   while ((ret = select(sock+1, NULL, &wfd, NULL, &sel_tv)) > 0) {
     if ((ret == -1) && (errno == EINTR))  /* a signal arrived, ignore it */
        continue;

     web100_snap(snap);
+
+    // get next sequence # to be sent
     web100_agent_find_var_and_group(agent, "SndNxt", &group, &var);
     web100_snap_read(var, snap, line);
     SndMax = atoi(web100_value_to_text(web100_get_var_type(var), line));
+    // get oldest un-acked sequence number
     web100_agent_find_var_and_group(agent, "SndUna", &group, &var);
     web100_snap_read(var, snap, line);
     SndUna = atoi(web100_value_to_text(web100_get_var_type(var), line));
-    if ((octets<<4) < (SndMax - SndUna - 1)) {
+
+    // stop sending data if (buf size * 16) <
+    //  [ (Next Sequence # To Be Sent) - (Oldest Unacknowledged Sequence  
#) - 1 ]
+    if ((currentMSSval<<4) < (SndMax - SndUna - 1)) {
       continue;
     }

-    k = write(sock, sndbuff, octets);
-    if ((k == -1) && (errno == EINTR))
+    // write currentMSSval number of bytes from send-buffer data into  
socket
+    k = write(sock, sndbuff, currentMSSval);
+    if ((k == -1) && (errno == EINTR)) // error writing into socket due
+                                                               // to 
interruption, try again
       continue;
-    if (k < 0 )
+    if (k < 0 ) // general error writing to socket. quit
       break;
   }
   log_println(5, "Finished with web100_middlebox() routine snap-0x%x,  
sndbuff=%x0x", snap, sndbuff);
@@ -173,27 +236,43 @@
   /* free(sndbuff); */
 }

+/**
+ * Get receiver side Web100 stats and write them to the log file
+ *
+ * @param sock integer socket file descriptor
+ * @param agent pointer to a web100_agent
+ * @param cn pointer to a web100_connection
+ * @param count_vars integer number of web100_variables to get value of
+ *
+ */
 void
 web100_get_data_recv(int sock, web100_agent* agent, web100_connection* cn,  
int count_vars)
 {
   int i, ok;
   web100_var* var;
-  char buf[32], line[256], *ctime();
+  char buf[32], line[256], *ctime(); // todo: define constants for 32, 256
   web100_group* group;
   FILE *fp;
   time_t tt;

+  // get current time
   tt=time(0);
+  // open logfile in append mode and write time into it
   fp=fopen(get_logfile(),"a");
   if (fp)
     fprintf(fp,"%15.15s;", ctime(&tt)+4);
+  // get values for group, var of IP Address of the Remote host's side of  
connection
   web100_agent_find_var_and_group(agent, "RemAddress", &group, &var);
   web100_raw_read(var, cn, buf);
   sprintf(line, "%s;", web100_value_to_text(web100_get_var_type(var),  
buf));
+  // write remote address to log file
   if (fp)
     fprintf(fp,"%s",  line);

   ok = 1;
+
+  // get values for other web100 variables and write to the log file
+
   for(i=0; i<count_vars; i++) {
     if ((web100_agent_find_var_and_group(agent, web_vars[i].name, &group,  
&var)) != WEB100_ERR_SUCCESS) {
       log_println(1, "Variable %d (%s) not found in KIS", i,  
web_vars[i].name);
@@ -219,6 +298,8 @@
     }
     ok = 1;
   }
+
+  //close file pointers after web100 variables have been fetched
   if (fp) {
     fprintf(fp, "\n");
     fclose(fp);
@@ -226,6 +307,16 @@

 }

+
+/**
+ * Collect Web100 stats from a snapshot and transmit to a receiver
+ *
+ * @param snap pointer to a web100_snapshot taken earlier
+ * @param ctlsock integer socket file descriptor indicating data recipient
+ * @param agent pointer to a web100_agent
+ * @param count_vars integer number of web100_variables to get value of
+ *
+ */
 int
 web100_get_data(web100_snapshot* snap, int ctlsock, web100_agent* agent,  
int count_vars)
 {
@@ -238,18 +329,21 @@
   assert(snap);
   assert(agent);

+  // Read values for number of variables intended
   for(i=0; i<count_vars; i++) {
     if ((web100_agent_find_var_and_group(agent, web_vars[i].name, &group,  
&var)) != WEB100_ERR_SUCCESS) {
       log_println(9, "Variable %d (%s) not found in KIS", i,  
web_vars[i].name);
       continue;
     }

+    // if no snapshot provided, no way to get values
     if (snap == NULL) {
       fprintf(stderr, "Web100_get_data() failed, return to testing  
routine\n");
       log_println(6, "Web100_get_data() failed, return to testing  
routine\n");
       return(-1);
     }

+    // handle an unsuccessful data retrieval
     if ((web100_snap_read(var, snap, buf)) != WEB100_ERR_SUCCESS) {
       if (get_debuglvl() > 9) {
         log_print(9, "Variable %d (%s): ", i, web_vars[i].name);
@@ -257,6 +351,8 @@
       }
       continue;
     }
+
+    // assign values and transmit message with all web100 variables to  
socket receiver end
     sprintf(web_vars[i].value, "%s",  
web100_value_to_text(web100_get_var_type(var), buf));
     sprintf(line, "%s: %d\n", web_vars[i].name, atoi(web_vars[i].value));
     send_msg(ctlsock, TEST_MSG, line, strlen(line));
@@ -267,6 +363,24 @@

 }

+/**
+ * Calculate Web100 based Round-Trip Time (RTT) value.
+ *
+ * "SumRTT" = sum of all sampled round trip times.
+ * "CountRTT" = count of samples in SumRTT.
+ * Thus, sumRTT/CountRTT = RTT
+ * @param ctlsock integer socket file descriptor indicating data recipient
+ * @param agent pointer to a web100_agent
+ * @param cn pointer to web100_connection
+ * @return positive integral round trip time in milliseconds on success,
+ *                negative integer error code if failure.
+ *             Error codes :
+ *                              -10 if web100-connection is null.
+ *                              -24 Cannot find CountRTT or SumRTT 
web100_variable's var/group.
+ * 				 -25 cannot read the value of the countRTT or SumRTT  
web100_variable.
+ *
+ *
+ */
 int
 web100_rtt(int sock, web100_agent* agent, web100_connection* cn)
 {
@@ -293,6 +407,24 @@
   sum = atoi(web100_value_to_text(web100_get_var_type(var), buf));
   return(sum/count);
 }
+
+
+/**
+ * Check if the "Auto Tune Send Buffer" and "Auto Tune Receive Buffer"  
options
+ * are enabled and return status on each
+ *
+ * @param sock integer socket file descriptor indicating data recipient
+ * @param agent pointer to a web100_agent
+ * @param cn pointer to web100_connection
+ * @return On successful fetch of required web100_varibles, integers:
+ *                             0x01 if "Autotune send buffer" is not enabled
+ *                             0x02 if "Autotune receive buffer" is not 
enabled
+ *  				0x03 if both " Autotune send buffer" and "Autotune receive buffer"  
are not enabled.
+ *             If failure, error codes :
+ *                             10 if web100-connection is null.
+ * 					22 Cannot find X_SBufMode or X_RBufMode web100_variable's  
var/group.
+ * 					23 cannot read the value of the X_SBufMode or X_RBufMode  
web100_variable.
+ */

 int
 web100_autotune(int sock, web100_agent* agent, web100_connection* cn)
@@ -335,11 +467,34 @@
   return(j);
 }

+/**
+ * Check if the "Auto Tune Send Buffer" and "Auto Tune Receive Buffer"  
options
+ * are enabled. If not, scale the Send window or receive window sizes  
based on the
+ * scaling factors negotiated. Scaling factor sndWinScale is used to set  
used to set "LimCwnd"
+ * (maximum size, in bytes, of the congestion window that may be used)
+ * and RcvWindowScale is used to set "LimRwin"( maximum receive window  
size, in bytes, that may be advertised).
+ *
+ * This function seems unused currently.
+ *
+ * @param sock integer socket file descriptor indicating data recipient
+ * @param agent pointer to a web100_agent
+ * @param cn pointer to web100_connection
+ * @return Integer, 0 on success
+ *       If failure, error codes :
+ *                             10 - web100-connection is null.
+ *                             22 - Cannot find LimCwnd web100 variable's 
var/group data.
+ *                             23 - Cannot find LimRwin web100 variable's 
var/group data
+ *                                     24 - cannot find SndWinScale web100 
variable's var/group data.
+ *                                     25 - cannot read the value of the 
SndWinScale web100 variable.
+ *                                     34 - cannot find RcvWinScale web100 
variable's var/group data.
+ *                                     35 - cannot read value of RcvWinScale 
web100 variable.
+ *
+ */
 int
 web100_setbuff(int sock, web100_agent* agent, web100_connection* cn, int  
autotune)
 {
   web100_var* var;
-  char buf[32];
+  char buf[32]; // todo defined constants for 32
   web100_group* group;
   int buff;
   int sScale, rScale;
@@ -347,15 +502,17 @@
   if (cn == NULL)
     return(10);

+  // get Window scale used by the sender to decode snd.wnd
   if ((web100_agent_find_var_and_group(agent, "SndWinScale", &group,  
&var)) != WEB100_ERR_SUCCESS)
     return(24);
   if ((web100_raw_read(var, cn, buf)) != WEB100_ERR_SUCCESS) {
     return(25);
   }
   sScale = atoi(web100_value_to_text(web100_get_var_type(var), buf));
-  if (sScale > 15)
+  if (sScale > 15) // define constant for 15
     sScale = 0;

+  // get Window scale used by the sender to decode seg.wnd
   if ((web100_agent_find_var_and_group(agent, "RcvWinScale", &group,  
&var)) != WEB100_ERR_SUCCESS)
     return(34);
   if ((web100_raw_read(var, cn, buf)) != WEB100_ERR_SUCCESS) {
@@ -366,21 +523,24 @@
     rScale = 0;

   if ((sScale > 0) && (rScale > 0)) {
-    buff = (64 * 1024) << sScale;
-    if (autotune & 0x01) {
+    buff = (64 * 1024) << sScale; // todo define constants for 64k( max  
TCP rcv window)
+    if (autotune & 0x01) { // autotune send buffer is not enabled
       if ((web100_agent_find_var_and_group(agent, "LimCwnd", &group,  
&var)) != WEB100_ERR_SUCCESS)
         return(22);
+      // attempt writing variable value, log failure
       if ((web100_raw_write(var, cn, &buff)) != WEB100_ERR_SUCCESS) {
         log_println(4, "Web100_raw_write(LimCwnd) failed with errorno=%d",  
errno);
         return(23);
       }
     }
     buff = (64 * 1024) << rScale;
-    if (autotune & 0x02) {
+
+
+    if (autotune & 0x02) { // autotune receive buffer is not enabled
       if ((web100_agent_find_var_and_group(agent, "LimRwin", &group,  
&var)) != WEB100_ERR_SUCCESS)
         return(22);
       if ((web100_raw_write(var, cn, &buff)) != WEB100_ERR_SUCCESS) {
-        log_println(4, "Web100_raw_write(LimCwnd) failed with errorno=%d",  
errno);
+        log_println(4, "Web100_raw_write(LimRwin) failed with errorno=%d",  
errno);
         return(23);
       }
     }
@@ -389,6 +549,14 @@
   return(0);
 }

+
+/**
+* @param sock integer socket file descriptor indicating data recipient
+* @param pointers to local copies of web100 variables
+* @return Integer 0
+*      @TODO this method can be altered to return void
+*
+*/
 int
 web100_logvars(int *Timeouts, int *SumRTT, int *CountRTT,
   int *PktsRetrans, int *FastRetran, int *DataPktsOut, int *AckPktsOut,
@@ -489,8 +657,17 @@
 }


-/* Routine to read snaplog file and determine the number of times the
+/**
+ * Routine to read snaplog file and determine the number of times the
  * congestion window is reduced.
+ *
+ * @param agent pointer to a web100_agent
+ * @param logname pointer to name of logfile
+ * @param *dec_cnt pointer to integer indicating number of times decreased
+ * @param *same_cnt pointer to integer indicating number of times kept same
+ * @param *inc_cnt pointer to integer indicating number of times  
incremented
+ * cn pointer to web100_connection
+ * @return Integer, 0 on success, -1 on failure
  */

 int
@@ -505,6 +682,7 @@
   web100_group* group;
   web100_agent* agnt;

+  // open snaplog file to read values
   if ((log = web100_log_open_read(logname)) == NULL)
     return(0);
   if ((snap = web100_snapshot_alloc_from_log(log)) == NULL)
@@ -513,14 +691,19 @@
     return(-1);
   if ((group = web100_get_log_group(log)) == NULL)
     return(-1);
+
+  // Find current values of the congestion window
   if (web100_agent_find_var_and_group(agnt, "CurCwnd", &group, &var) !=  
WEB100_ERR_SUCCESS)
     return(-1);
   s2 = 0;
   cnt = 0;
+
+  // get values and update counts
   while (web100_snap_from_log(snap, log) == 0) {
     if (cnt++ == 0)
       continue;
     s1 = s2;
+    // Parse snapshot, returning variable values
     rt = web100_snap_read(var, snap, buff);
     s2 = atoi(web100_value_to_text(web100_get_var_type(var), buff));
     if (cnt < 20) {
@@ -544,6 +727,13 @@
   return(0);
 }

+/**
+ * Generate TCP/IP checksum for our packet
+ *
+ * @param buff pointer to buffer
+ * @param nwords integer length (in bytes) of the header
+ * @return unsigned short checksum
+ */
 unsigned short
 csum(unsigned short *buff, int nwords)
 {
@@ -555,6 +745,8 @@
   register u_short *w = buff;
   register int nleft = nwords;

+  // make 16 bit words out of every couple of 8 bit words and
+  // add up
   while (nleft > 1) {
     sum += *w++;
     nleft -= 2;
@@ -565,12 +757,24 @@
     sum += answer;
   }

+  // form 16 bit words, add and store
   sum = (sum >> 16) + (sum & 0xffff);
+  // then add carries to the sume
   sum += (sum >> 16);
+
+  // 1s complement of the above yields checksum
   answer = ~sum;
   return(answer);
 }

+/**
+ * Try to close out connections in an unexpected or erroneous state.
+ *
+ * This function seems unused currently.
+ *
+ * @return integer, 0 if kill succeeded, and
+ *       -1 if kill failed or there was nothing to kill
+ */
 int
 KillHung(void)

@@ -687,9 +891,11 @@
       hung = 1;

     }
+    // returns the next connection in the sequence
     conn = web100_connection_next(conn);
   }

+  // close and free allocated agent
   web100_detach(agent);
   /* free(pkt); */
   if (hung == 0)