NDT-DEV email list created

Revision: 651
Author:   

Date:     Fri Sep 23 13:50:35 2011
Log:      More inline documentation for server files;initial version of  
addition of protocol validation log
http://code.google.com/p/ndt/source/detail?r=651

Modified:
 /branches/kkumar_code_organize/FILES
 /branches/kkumar_code_organize/contrib/Tcpbw1001.java
 /branches/kkumar_code_organize/src/analyze.c
 /branches/kkumar_code_organize/src/logging.c
 /branches/kkumar_code_organize/src/logging.h
 /branches/kkumar_code_organize/src/mrange.c
 /branches/kkumar_code_organize/src/network.c
 /branches/kkumar_code_organize/src/test_meta_srv.c
 /branches/kkumar_code_organize/src/test_sfw_srv.c
 /branches/kkumar_code_organize/src/testoptions.c
 /branches/kkumar_code_organize/src/testoptions.h
 /branches/kkumar_code_organize/src/usage.c
 /branches/kkumar_code_organize/src/web100-util.c
 /branches/kkumar_code_organize/src/web100srv.c
 /branches/kkumar_code_organize/src/web100srv.h

=======================================
--- /branches/kkumar_code_organize/FILES        Fri Aug 26 14:06:20 2011
+++ /branches/kkumar_code_organize/FILES        Fri Sep 23 13:50:35 2011
@@ -41,7 +41,7 @@
 in the 'Applet' sub-directory
 Makefile.am      - Used by configure to build the runnable Makefile
 Makefile.in      - Used by configure to build the runnable Makefile
-Tcpbw100.java, StatusPanel.java, Protocol.java, Message.java,  
UserAgentTools.java, NDTConstants.java, OsfwWorker.java, NewFrame.java,  
ResultsTextPane.java, MessageType.java, NDTUtils.java
+Tcpbw100.java, StatusPanel.java, Protocol.java, Message.java,  
UserAgentTools.java, NDTConstants.java, OsfwWorker.java, NewFrame.java,  
ResultsTextPane.java, MessageType.java, NDTUtils.java
                 - The source code for the client side java applet and 
related classes
 *.class          - Corresponding java class versions of the client applet  
and related classes
 Tcpbw100$N.class - java subclasses of the client applet
=======================================
--- /branches/kkumar_code_organize/contrib/Tcpbw1001.java	Sun Aug 19  
03:26:07 2007
+++ /branches/kkumar_code_organize/contrib/Tcpbw1001.java	Fri Sep 23  
13:50:35 2011
@@ -77,16 +77,16 @@
 {
        TextArea results, diagnosis, statistics, reports;
        String inresult, outresult, errmsg;
-       Button startTest;
-       Button disMiss, disMiss2;
+       Button _buttonStartTest;
+       Button _buttonDismiss, _buttonStatsDismiss;
        Button copy, copy2;
-       Button deTails;
-       Button sTatistics;
-       Button mailTo;
+       Button _buttonDetails;
+       Button _buttonStatistics;
+       Button _buttonMailTo;
        Label lab1, lab2, lab3, lab4;
-       boolean Randomize, failed, cancopy;
+       boolean _bRandomize, failed, cancopy;
        URL location;
-       clsFrame f, ff;
+       NewFrame f, ff;
        String s;
        Frame frame;
        double t;
@@ -131,7 +131,7 @@
                setLayout(new FlowLayout(FlowLayout.CENTER, 5, 5));
                showStatus("Tcpbw100 ready");
                failed = false ;
-               Randomize = false;
+               _bRandomize = false;
                cancopy = false;

 /*************************************************************************
@@ -155,28 +155,28 @@
 /************************************************************************/

                results.append("click START to begin\n");
-               startTest = new Button("START");
-               startTest.addActionListener(this);
-               add("West", startTest);
+               _buttonStartTest = new Button("START");
+               _buttonStartTest.addActionListener(this);
+               add("West", _buttonStartTest);
                Panel mPanel = new Panel();
-               sTatistics = new Button("Statistics");
-               sTatistics.addActionListener(this);
-               sTatistics.setEnabled(false);
-               deTails = new Button("More Details...");
-               deTails.addActionListener(this);
-               deTails.setEnabled(false);
-               mailTo = new Button("Report Problem");
-               mailTo.addActionListener(this);
-               mailTo.setEnabled(false);
+               _buttonStatistics = new Button("Statistics");
+               _buttonStatistics.addActionListener(this);
+               _buttonStatistics.setEnabled(false);
+               _buttonDetails = new Button("More Details...");
+               _buttonDetails.addActionListener(this);
+               _buttonDetails.setEnabled(false);
+               _buttonMailTo = new Button("Report Problem");
+               _buttonMailTo.addActionListener(this);
+               _buttonMailTo.setEnabled(false);

 /*************************************************************************
 * Changed by Seth Peery on 2006-08-04
 * Change values here to remove buttons from the applet.
 * Note that these lines are relocated from above.
 */
-        //      mPanel.add(mailTo);
-                mPanel.add(deTails);
-                mPanel.add(sTatistics);
+        //      mPanel.add(_buttonMailTo);
+                mPanel.add(_buttonDetails);
+                mPanel.add(_buttonStatistics);
 /************************************************************************/

                add("South", mPanel);
@@ -187,10 +187,10 @@
        public void runtest() {
                diagnose();
                statistics();
-               startTest.setEnabled(false);
-               deTails.setEnabled(false);
-               sTatistics.setEnabled(false);
-               mailTo.setEnabled(false);
+               _buttonStartTest.setEnabled(false);
+               _buttonDetails.setEnabled(false);
+               _buttonStatistics.setEnabled(false);
+               _buttonMailTo.setEnabled(false);

                try {
                        dottcp();
@@ -204,12 +204,12 @@
                        results.append(errmsg);
                }

-               deTails.setEnabled(true);
-               sTatistics.setEnabled(true);
-               mailTo.setEnabled(true);
+               _buttonDetails.setEnabled(true);
+               _buttonStatistics.setEnabled(true);
+               _buttonMailTo.setEnabled(true);
                showStatus("Tcpbw100 done");
                results.append("\nclick START to re-test\n");
-               startTest.setEnabled(true);
+               _buttonStartTest.setEnabled(true);
        }


@@ -456,7 +456,7 @@
                t = System.currentTimeMillis();
                stop_time = t + 10000; // ten seconds
                do {
-                       // if (Randomize) rng.nextBytes(buff2);
+                       // if (_bRandomize) rng.nextBytes(buff2);
                        out.write(buff2, 0, buff2.length);
                        pkts++;
                } while (System.currentTimeMillis() < stop_time);
@@ -1334,24 +1334,24 @@
                showStatus("Get WEB100 Variables");

                if (f == null) {
-                       f = new clsFrame();
+                       f = new NewFrame();
                }
                f.setTitle("Web100 Variables");
                Panel buttons = new Panel();
                f.add("South", buttons);

-               disMiss = new Button("Close");
-               disMiss.addActionListener(this);
+               _buttonDismiss = new Button("Close");
+               _buttonDismiss.addActionListener(this);

                copy = new Button("Copy");
                copy.addActionListener(this);

                diagnosis = new TextArea("WEB100 Kernel Variables:\n", 15,30);
                diagnosis.setEditable(true);
-               disMiss.setEnabled(true);
+               _buttonDismiss.setEnabled(true);
                copy.setEnabled(cancopy);

-               buttons.add("West", disMiss);
+               buttons.add("West", _buttonDismiss);
                buttons.add("East", copy);
                f.add(diagnosis);
                f.pack();
@@ -1363,24 +1363,24 @@
                showStatus("Print Detailed Statistics");

                if (ff == null) {
-                       ff = new clsFrame();
+                       ff = new NewFrame();
                }
                ff.setTitle("Detailed Statistics");
                Panel buttons = new Panel();
                ff.add("South", buttons);

-               disMiss2 = new Button("Close");
-               disMiss2.addActionListener(this);
+               _buttonStatsDismiss = new Button("Close");
+               _buttonStatsDismiss.addActionListener(this);

                copy2 = new Button("Copy");
                copy2.addActionListener(this);

                statistics = new TextArea("WEB100 Enabled Statistics:\n", 
25,70);
                statistics.setEditable(true);
-               disMiss2.setEnabled(true);
+               _buttonStatsDismiss.setEnabled(true);
                copy2.setEnabled(cancopy);

-               buttons.add("West", disMiss2);
+               buttons.add("West", _buttonStatsDismiss);
                buttons.add("East", copy2);
                ff.add(statistics);
                ff.pack();
@@ -1393,7 +1393,7 @@
                // System.err.println("Processing WINDOW event #" 
+event.getID());
                // System.err.println("Processing event " + source);

-               if (source == startTest) {
+               if (source == _buttonStartTest) {
                        if(f != null) {
                                f.toBack();
                                f.dispose();
@@ -1408,19 +1408,19 @@
                        runtest();
                }

-               else if (source == deTails) {
-                       deTails.setEnabled(false);
+               else if (source == _buttonDetails) {
+                       _buttonDetails.setEnabled(false);
                        f.setResizable(true);
                        f.show();
-                       deTails.setEnabled(true);
+                       _buttonDetails.setEnabled(true);
                }

-               else if (source == disMiss) {
+               else if (source == _buttonDismiss) {
                        f.toBack();
                        f.dispose();
                }

-               else if (source == disMiss2) {
+               else if (source == _buttonStatsDismiss) {
                        ff.toBack();
                        ff.dispose();
                }
@@ -1446,20 +1446,20 @@
                        statistics.selectAll();
                }

-               else if (source == sTatistics) {
-                       sTatistics.setEnabled(false);
+               else if (source == _buttonStatistics) {
+                       _buttonStatistics.setEnabled(false);
                        ff.setResizable(true);
                        ff.show();
-                       sTatistics.setEnabled(true);
+                       _buttonStatistics.setEnabled(true);
                }

-               else if (source == mailTo) {
+               else if (source == _buttonMailTo) {
                        int i;
                        char key;
                        String to[], from[], comments[];
                        String Name, Host;

-                       mailTo.setEnabled(false);
+                       _buttonMailTo.setEnabled(false);
                        // envoke mailto: function
                        showStatus("Tcpbw100 Invoking Mailto function...");

@@ -1493,8 +1493,8 @@
        }  // actionPerformed()


-       public class clsFrame extends Frame {
-               public clsFrame() {
+       public class NewFrame extends Frame {
+               public NewFrame() {
                        addWindowListener(new WindowAdapter() {
                                public void windowClosing(WindowEvent event) {
                                        // System.err.println("Handling window 
closing event");
@@ -1503,6 +1503,6 @@
                        });
                        // System.err.println("Extended Frame class - 
RAC9/15/03");
                }
-       } // class: clsFrame
+       } // class: NewFrame

 } // class: Tcpbw100
=======================================
--- /branches/kkumar_code_organize/src/analyze.c        Wed Apr  8 12:34:07 
2009
+++ /branches/kkumar_code_organize/src/analyze.c        Fri Sep 23 13:50:35 
2011
@@ -34,6 +34,7 @@
 #include "logging.h"

 #define LOGFILE "web100srv.log"
+#define PROTOLOGFILE "web100srvprotocol.log" //kk protocol validation
 #define WEB100_VARS 128  /*number of web100 variables you want to access*/
 #define WEB100_FILE "web100_variables"  /*names of the variables to  
access*/
 #define BUFFSIZE 512
@@ -44,6 +45,7 @@
 char *rmt_host;
 char *VarFileName=NULL;
 char *LogFileName=NULL;
+char *ProtoLogFileName=NULL; // Log file used to log protocol validation  
logs
 double avgrtt, loss, loss2, rttsec, bw, bw2, rwin, swin, cwin, speed;
 double rwintime, cwndtime, sendtime, timesec;
 int n, m, one=1;
@@ -394,7 +396,8 @@
   int debug = 0;

   iponly = 0;
-  while ((c = getopt_long(argc, argv, "dnhl:v", long_options, 0)) != -1) {
+  //while ((c = getopt_long(argc, argv, "dnhl:v", long_options, 0)) != -1)  
{
+  while ((c = getopt_long(argc, argv, "udnhl:v", long_options, 0)) != -1)  
{ //protocol validation, kk
     switch (c) {
       case 'h':
         analyze_long_usage("ANL/Internet2 NDT version " VERSION "  
(analyze)");
@@ -406,6 +409,11 @@
       case 'l':
         LogFileName = optarg;
         break;
+      //kk for protocol validation
+      case 'u':
+              ProtoLogFileName = optarg;
+              break;
+      //end protocol validation
       case 'n':
         iponly=1;
         break;
@@ -430,6 +438,14 @@
   }
   log_println(1, "log file = %s", LogFileName);

+  //protocol validation. kk new
+  if (ProtoLogFileName == NULL) {
+     sprintf(tmpstr, "%s/%s", BASEDIR, PROTOLOGFILE);
+     ProtoLogFileName = tmpstr;
+  }
+  log_println(1, "log file = %s", ProtoLogFileName);
+  //end protocol validation
+
   if ((fp = fopen(LogFileName, "r")) == NULL)
     err_sys("Missing Log file ");

=======================================
--- /branches/kkumar_code_organize/src/logging.c        Tue Sep 13 07:04:10 
2011
+++ /branches/kkumar_code_organize/src/logging.c        Fri Sep 23 13:50:35 
2011
@@ -24,6 +24,7 @@
 static int                _debuglevel        = 0;
 static char*              _programname       = "";
 static char*              LogFileName        = BASEDIR"/"LOGFILE;
+static char*              ProtoLogFileName    = BASEDIR"/"PROTOLOGFILE;
 static I2ErrHandle        _errorhandler_nl   = NULL;
 static I2ErrHandle        _errorhandler      = NULL;
 static I2LogImmediateAttr _immediateattr_nl;
@@ -61,7 +62,7 @@
   unsigned char in[16384];
   unsigned char out[16384];

-    /* allocate deflate state */
+    // allocate deflate state
     strm.zalloc = Z_NULL;
     strm.zfree = Z_NULL;
     strm.opaque = Z_NULL;
@@ -80,7 +81,7 @@
 	log_println(6, "zlib_def(): failed to open dest file '%s' for writing",  
dest_fn);
        return -4;
     }
-    /* compress until end of file */
+    // compress until end of file
     do {
         strm.avail_in = fread(in, 1, 16384, source);
         if (ferror(source)) {
@@ -90,8 +91,8 @@
         flush = feof(source) ? Z_FINISH : Z_NO_FLUSH;
         strm.next_in = in;

-        /* run deflate() on input until output buffer not full, finish
- *            compression if all of source has been read in */
+        // run deflate() on input until output buffer not full, finish
+        //   compression if all of source has been read in
         do {
             strm.avail_out = 16384;
             strm.next_out = out;
@@ -122,10 +123,9 @@
 /* #endif */

 /**
- * Function name: log_init
- * Description: Initializes the logging system.
- * Arguments: progname - the name of the program
- *            debuglvl - the debug level
+ * Initialize the logging system.
+ * @param progname The name of the program
+ * @param debuglvl The debug level
  */

 void
@@ -190,6 +190,30 @@
 {
   LogFileName = filename;
 }
+
+/**
+ * Function name: set_protologfile
+ * Description: Sets the log filename.
+ * Arguments: filename - new log filename
+ */
+
+void
+set_protologfile(char* filename)
+{
+       ProtoLogFileName = filename;
+}
+
+/**
+ * Function name: get_protocollogfile
+ * Description: Returns the protocol validation log filename.
+ * Returns: The log filename
+ */
+
+char*
+get_protologfile()
+{
+  return ProtoLogFileName;
+}

 /**
  * Function name: get_debuglvl
=======================================
--- /branches/kkumar_code_organize/src/logging.h        Sun May  8 04:04:21 
2011
+++ /branches/kkumar_code_organize/src/logging.h        Fri Sep 23 13:50:35 
2011
@@ -15,6 +15,7 @@
 #include <sys/types.h>

 #define LOGFILE "web100srv.log"   /* Name of log file */
+#define PROTOLOGFILE "web100srvprotocol.log"   /* Name of protocol  
validation log file */

 void log_init(char* progname, int debuglvl);
 void set_debuglvl(int debuglvl);
@@ -36,32 +37,40 @@

 int zlib_def(char *src_fn);

+/**
+ * Format used to exchange meta test data between client->server.
+ * */
 struct metaentry {
-  char key[64];
-  char value[256];
-  struct metaentry* next;
+  char key[64]; // key name
+  char value[256]; // value associated with this meta key
+  struct metaentry* next; // pointer to next link
 };

+/**
+ * Used to save results of meta tests.
+ * These values (most) are thes logged in the
+ *  meta data file created  for every session
+ * */
 struct metadata {
-    char c2s_snaplog[64];
-    char c2s_ndttrace[64];
-    char s2c_snaplog[64];
-    char s2c_ndttrace[64];
-    char CPU_time[64];
-    char summary[256];
-    char date[32];
-    char time[16];
-    char client_ip[64];
-    struct sockaddr_storage c_addr;
-    char client_name[64];
-    char client_os[32];
-    char client_browser[32];
-    int  ctl_port;
-    char server_ip[64];
-    char server_name[64];
-    char server_os[32];
-    int  family;
-    struct metaentry* additional;
+    char c2s_snaplog[64]; // C->S test Snaplog file name
+    char c2s_ndttrace[64]; // C->S NDT trace file name
+    char s2c_snaplog[64]; // S->C test Snaplog file name
+    char s2c_ndttrace[64]; // S->C NDT trace file name
+    char CPU_time[64]; // CPU time file
+    char summary[256]; // Summary data
+    char date[32]; // Date and,
+    char time[16]; // time
+    char client_ip[64]; // Client IP Address
+    struct sockaddr_storage c_addr; // client socket details, not logged
+    char client_name[64]; // client's host-name
+    char client_os[32]; // client OS name
+    char client_browser[32]; // client's browser name
+    int  ctl_port; // ? todo map use
+    char server_ip[64]; // server IP address
+    char server_name[64]; // server's host-name
+    char server_os[32]; // server os name
+    int  family; // IP family
+    struct metaentry* additional; // all other additional data
 };

 struct metadata meta;
=======================================
--- /branches/kkumar_code_organize/src/mrange.c Thu Sep  8 09:20:22 2011
+++ /branches/kkumar_code_organize/src/mrange.c Fri Sep 23 13:50:35 2011
@@ -90,16 +90,15 @@
   return 0;
 }

-/*
- * Function name: mrange_next
- * Description: Checks if a given number (passed in as string argument)
+/**
+ * Checks if a given number (passed in as string argument)
  *  is available as a valid integer in the free pool. For example,
  *  if we construct a list of valid port ranges, then this function
  *  could be used to parse through the list to check for a usable port
  *
- * Arguments: text - the string containing port
- * Returns: char* containing 0 if the argument port is invalid
- *          char* containing the port number if port is valid
+ * @param port  string containing port
+ * @returns char* containing 0 if the argument is invalid,
+ *  or the port passed as parameter, if valid
  */

 char*
=======================================
--- /branches/kkumar_code_organize/src/network.c        Fri Sep 16 08:39:32 
2011
+++ /branches/kkumar_code_organize/src/network.c        Fri Sep 23 13:50:35 
2011
@@ -371,9 +371,9 @@
  * Returns: 0 - success,
  *          !0 - error code.
  *        Error codes:
- *        -1 : Cannot write message header information
- *        -2 : Cannot write message data
- *        -3 : TODO: cannot write after retries?
+ *        -1 - Cannot write to socket at all
+ *        -2 - Cannot complete writing full message data into socket
+ *        -3 - Cannot write after retries
  *
  */

@@ -382,18 +382,19 @@
 {
   unsigned char buff[3];
   int rc, i;
+  FILE *fp; //kk

   assert(msg);
   assert(len >= 0);

  /*  memset(0, buff, 3); */
   // set message type and length into message itself
-  // TODO why the shift operator? store into byte
   buff[0] = type;
   buff[1] = len >> 8;
   buff[2] = len;

-  //What is 5 here? TODO
+  //TODO could define a constant for 5, or leave it that way here
+  // retry sending data 5 times
   for (i=0; i<5; i++) {
        // Write initial data about length and type to socket
     rc = writen(ctlSocket, buff, 3);
@@ -405,7 +406,7 @@
       return -1;
   }

-  //TODO
+  // Exceeded retries, return as "failed trying to write"
   if (i == 5)
     return -3;

@@ -424,6 +425,16 @@
   if (i == 5)
     return -3;
   log_println(8, ">>> send_msg: type=%d, len=%d, msg=%s, pid=%d", type,  
len, msg, getpid());
+  // kk start
+  fp = fopen(get_protologfile(),"a");
+  if (fp == NULL) {
+	  log_println(0, "Unable to open protocol log file '%s', continuing on  
without logging", get_logfile());
+  }
+  else {
+	  fprintf(fp, "Sent message: type=%d, len=%d, msg=%s, pid=%d on  
socket=%d\n", type, len, msg, getpid(), ctlSocket);
+         fclose(fp);
+  }
+  // kk end
   return 0;
 }

@@ -447,6 +458,7 @@
 {
   unsigned char buff[3];
   int length;
+  FILE *fp; //kk

   assert(type);
   assert(msg);
@@ -473,6 +485,18 @@
     return -3;
   }
   log_println(8, "<<< recv_msg: type=%d, len=%d", *type, *len);
+  //kk here
+  fp = fopen(get_protologfile(),"a");
+  if (fp == NULL) {
+	  log_println(0, "Unable to open protocol log file '%s', continuing on  
without logging", get_logfile());
+  }
+  else {
+	  //fprintf(fp, "Rcd message: type=%d, len=%d, msg=%s, pid=%d on  
socket=%d\n", *type, *len, (char*)msg, getpid(), ctlSocket);
+	  fprintf(fp, "Rcd message: type=%d, len=%d,pid=%d on socket=%d\n",  
*type, *len, getpid(), ctlSocket);
+
+         fclose(fp);
+  }
+  //end kk
   return 0;
 }

=======================================
--- /branches/kkumar_code_organize/src/test_meta_srv.c	Sun May  8 04:04:21  
2011
+++ /branches/kkumar_code_organize/src/test_meta_srv.c	Fri Sep 23 13:50:35  
2011
@@ -19,15 +19,23 @@
 #include "utils.h"
 #include "testoptions.h"

-/*
- * Function name: test_meta_srv
- * Description: Performs the META test.
- * Arguments: ctlsockfd - the client control socket descriptor
- *            agent - the Web100 agent used to track the connection
- *            testOptions - the test options
- *            conn_options - the connection options
- * Returns: 0 - success,
+/**
+ * Performs the META test.
+ * @param ctlsockfd Client control socket descriptor
+ * @param agent Web100 agent used to track the connection
+ * @param testOptions The test options
+ * @param conn_options The connection options
+ * @returns 0 - success,
  *          >0 - error code.
+ *          Error codes:
+ *           -1 - Cannot write message header information while attempting  
to send
+ *                      TEST_START message
+ *          -2 - Cannot write message data while attempting to send
+ *                      TEST_START message
+ *          1 - Message reception errors/inconsistencies
+ *			2 - Unexpected message type received/no message received due to  
timeout
+ *                     3 - Received message is invalid
+ *                     4 - Invalid data format in received message
  */

 int
@@ -35,7 +43,7 @@
 {
   int j;
   int msgLen, msgType;
-  char buff[BUFFSIZE+1];
+  char buff[BUFFSIZE+1]; // TODO
   struct metaentry *new_entry = NULL;
   char* value;

@@ -43,45 +51,53 @@
     setCurrentTest(TEST_META);
     log_println(1, " <-- META test -->");

-
+    // first message exchanged is am empty TEST_PREPARE message
     j = send_msg(ctlsockfd, TEST_PREPARE, "", 0);
-    if (j == -1 || j == -2) {
+    if (j == -1 || j == -2) { // Cannot write message headers/data
        log_println(6, "META Error!, Test start message not sent!");
        return j;
     }

+    // Now, transmit an empty TEST_START message
     if (send_msg(ctlsockfd, TEST_START, "", 0) < 0) {
          log_println(6, "META test - Test-start message failed");
        }

        while (1) {
          msgLen = sizeof(buff);
+         // Now read the meta data sent by client.
+
          if (recv_msg(ctlsockfd, &msgType, buff, &msgLen)) {
+                 // message reading error
         log_println(0, "Protocol error!");
         sprintf(buff, "Server (META test): Invalid meta data received");
         send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
         return 1;
       }
       if (check_msg_type("META test", TEST_MSG, msgType, buff, msgLen)) {
+         // expected a TEST_MSG only
         log_println(0, "Fault, unexpected message received!");
         sprintf(buff, "Server (META test): Invalid meta data received");
         send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
         return 2;
       }
       if (msgLen < 0) {
+         //  meta data should be present at this stage
         log_println(0, "Improper message");
         sprintf(buff, "Server (META test): Invalid meta data received");
         send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
         return 3;
       }

+      // Received empty TEST_MSG. All meta_data has been received, and test
+      //  can be finalized.
       if (msgLen == 0) {
         break;
       }

       buff[msgLen] = 0;
       value = index(buff, ':');
-      if (value == NULL) {
+      if (value == NULL) { // key-value separates by ":"
         log_println(0, "Improper message");
         sprintf(buff, "Server (META test): Invalid meta data received");
         send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
@@ -90,6 +106,8 @@
       *value = 0;
       value++;

+      // get the recommended set of data expected: client os name , client  
browser name,
+      //why not if else-if for the whole set? TODO
       if (strcmp(META_CLIENT_OS, buff) == 0) {
         snprintf(meta.client_os, sizeof(meta.client_os), "%s", value);
         /*continue;*/
@@ -100,6 +118,7 @@
         /*continue;*/
       }

+      // now get all the key-value tuples
          if (new_entry) {
 	    new_entry->next = (struct metaentry *) malloc(sizeof(struct  
metaentry));
            new_entry = new_entry->next;
@@ -112,6 +131,7 @@
          snprintf(new_entry->value, sizeof(new_entry->value), "%s", value);
        }

+       // Finalize test by sending appropriate message, and setting status
        if (send_msg(ctlsockfd, TEST_FINALIZE, "", 0) < 0) {
          log_println(6, "META test - failed to send finalize message");
        }
=======================================
--- /branches/kkumar_code_organize/src/test_sfw_srv.c	Fri Sep 16 08:39:32  
2011
+++ /branches/kkumar_code_organize/src/test_sfw_srv.c	Fri Sep 23 13:50:35  
2011
@@ -113,7 +113,7 @@
  *                     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
+ *                     3 - Received message is invalid
  *                     4 - Client port number not received
  *                     5 - Unable to resolve client address
  */
=======================================
--- /branches/kkumar_code_organize/src/testoptions.c	Fri Sep 16 08:39:32  
2011
+++ /branches/kkumar_code_organize/src/testoptions.c	Fri Sep 23 13:50:35  
2011
@@ -1,7 +1,7 @@
 /*
  * This file contains the functions needed to handle various tests.
  *
- * Jakub S�awi�ski 2006-06-24
+ * Jakub S�awi�ski 2006-06-24
  * 

  */

@@ -18,7 +18,8 @@
 #include "protocol.h"
 #include "I2util/util.h"

-int mon_pipe1[2], mon_pipe2[2];
+int mon_pipe1[2];
+int mon_pipe2[2]; // used to store PIDs of pipes created for snap data in  
S2c test
 static int currentTest = TEST_NONE;

 typedef struct snapArgs {
@@ -42,11 +43,10 @@
 static int decreasing = 0;

 /**
- * Function name: findCwndPeaks
- * Description: Count the CWND peaks and record the minimal and maximum  
one.
- * Arguments: agent - the Web100 agent used to track the connection
- *            peaks - the structure containing CWND peaks information
- *            snap - the web100 snapshot structure
+ * Count the CWND peaks from a snapshot and record the minimal and maximum  
one.
+ * @param agent Web100 agent used to track the connection
+ * @param peaks Structure containing CWND peaks information
+ * @param snap Web100 snapshot structure
  */

 void
@@ -70,7 +70,9 @@
       }
   }
   else {
-      if (CurCwnd < prevCWNDval) {
+         // current congestion window < previous value, so, decreasing
+         if (CurCwnd < prevCWNDval) {
+                 // update values based on actual values
           if (prevCWNDval > peaks->max) {
               peaks->max = prevCWNDval;
           }
@@ -79,7 +81,8 @@
           }
           decreasing = 1;
       }
-      else if (CurCwnd > prevCWNDval) {
+      else if (CurCwnd > prevCWNDval) { // current congestion window size  
> previous value,
+                                                                       // 
not decreasing.
           if ((peaks->min == -1) || (prevCWNDval < peaks->min)) {
               peaks->min = prevCWNDval;
           }
@@ -89,10 +92,9 @@
   prevCWNDval = CurCwnd;
 }

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

 void
@@ -105,12 +107,11 @@
   log_println(0, "Unknown (%d) signal was caught", signo);
 }

-/*
- * Function name: snapWorker
- * Description: Writes the snap logs with fixed time intervals in separate
- *              thread.
- * Arguments: arg - pointer to the snapshot structure
- * Returns: NULL
+/**
+ * Write the snap logs with fixed time intervals in a separate
+ *              thread, locking and releasing resources as necessary
+ * @param arg pointer to the snapshot structure
+ * @return void pointer null
  */

 void*
@@ -155,12 +156,11 @@
     return NULL;
 }

-/*
- * Function name: add_test_to_suite
- * Description: Adds test id to the test suite
- * Arguments: first - first test indicator
- *            buff - test suite description
- *            test_id - id of the test
+/**
+ * Adds test id to the test suite
+ * @param first first test indicator
+ * @param buff test suite description
+ * @param test_id id of the test
  */
 void
 add_test_to_suite(int* first, char * buff, int test_id)
@@ -177,14 +177,19 @@
   }
 }

-/*
- * Function name: initialize_tests
- * Description: Initializes the tests for the client.
- * Arguments: ctlsockfd - the client control socket descriptor
- *            options - the test options
- *            buff - the connection options
- * Returns: 0 - success,
+/**
+ * Initialize the tests for the client.
+ * @param ctlsockfd Client control socket descriptor
+ * @param options   Test options
+ * @param buff                 Connection options
+ * @return integer 0 on success,
  *          >0 - error code.
+ *          Error codes:
+ *          -1 message reading in error
+ *                     -2 Invalid test request
+ *                     -3 Invalid test suite request
+ *                     -4 client timed out
+ *
  */

 int
@@ -198,7 +203,7 @@
   assert(ctlsockfd != -1);
   assert(options);

-  /* read the test suite request */
+  // read the test suite request
   if (recv_msg(ctlsockfd, &msgType, &useropt, &msgLen)) {
       sprintf(buff, "Invalid test suite request");
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
@@ -208,16 +213,19 @@
       sprintf(buff, "Client timeout");
       return (-4);
   }
+  // Expecting a MSG_LOGIN with payload byte indicating tests to be run
   if ((msgType != MSG_LOGIN) || (msgLen != 1)) {
       sprintf(buff, "Invalid test request");
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       return (-2);
   }
   if (!(useropt & (TEST_MID | TEST_C2S | TEST_S2C | TEST_SFW | TEST_STATUS  
| TEST_META))) {
+                         // message received does not indicate a valid test!
       sprintf(buff, "Invalid test suite request");
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       return (-3);
   }
+  // construct test suite request based on user options received
   if (useropt & TEST_MID) {
     add_test_to_suite(&first, buff, TEST_MID);
   }
@@ -236,16 +244,26 @@
   return useropt;
 }

-/*
- * Function name: test_mid
- * Description: Performs the Middlebox test.
- * Arguments: ctlsockfd - the client control socket descriptor
- *            agent - the Web100 agent used to track the connection
- *            options - the test options
- *            s2c2spd - the S2C throughput results (evaluated by the MID  
TEST)
- *            conn_options - the connection options
+/**
+ * Perform the Middlebox test.
+ * @param ctlsockfd Client control socket descriptor
+ * @param agent Web100 agent used to track the connection
+ * @param options  Test options
+ * @param s2c2spd In-out parameter for S2C throughput results (evaluated  
by the MID TEST),
+ * @param conn_options Connection options
  * Returns: 0 - success,
  *          >0 - error code.
+ *          Error codes:
+ *                             -1 - Listener socket creation failed
+ *                             -3-web100 connection data not obtained
+ *				-100 -timeout while waitinf for client to connect to serverÕs  
ephemeral port
+ *                             -errono- Other specific socket error numbers
+ *                             -101 - Retries exceeded while waiting for 
client to connect
+ *                             -102 - Retries exceeded while waiting for 
data from connected client
+ *                             1 - Message reception errors/inconsistencies
+ *				2 - Unexpected message type received/no message received due to  
timeout
+ *                             3 Ð Received message is invalid
+ *
  */

 int
@@ -254,7 +272,8 @@
   int maxseg=1456;
   /* int maxseg=1456, largewin=16*1024*1024; */
   /* int seg_size, win_size; */
-  int midsfd, j, ret;
+  int midsfd; // socket file-descriptor, used in throuput test from S->C
+  int j, ret;
   struct sockaddr_storage cli_addr;
   /* socklen_t optlen, clilen; */
   socklen_t clilen;
@@ -273,9 +292,12 @@
   assert(options);
   assert(s2c2spd);

-  if (options->midopt) {
+  if (options->midopt) { // ready to run middlebox tests
     setCurrentTest(TEST_MID);
     log_println(1, " <-- %d - Middlebox test -->", options->child0);
+
+    // determine port to be used. Compute based on options set earlier
+    // by reading from config file, or use default port3 (3003),
     strcpy(listenmidport, PORT3);

     if (options->midsockport) {
@@ -298,6 +320,9 @@
 */

     while (midsrv_addr == NULL) {
+
+    	// attempt to bind to a new port and obtain address structure with  
details of listening port
+
         midsrv_addr = CreateListenSocket(NULL,
                 (options->multiple ? mrange_next(listenmidport) :  
listenmidport), conn_options, 0);
         if (midsrv_addr == NULL) {
@@ -311,22 +336,25 @@
             log_println(0, "WARNING: ephemeral port number was bound");
             break;
         }
-        if (options->multiple == 0) {
+        if (options->multiple == 0) { // todo
             break;
         }
     }
     if (midsrv_addr == NULL) {
       log_println(0, "Server (Middlebox test): CreateListenSocket  
failed: %s", strerror(errno));
       sprintf(buff, "Server (Middlebox test): CreateListenSocket  
failed: %s", strerror(errno));
-      send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
+      send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff)); //todo protocol  
validation log
       return -1;
     }
+
+    // get socket FD and the ephemeral port number that client will  
connect to
     options->midsockfd = I2AddrFD(midsrv_addr);
     options->midsockport = I2AddrPort(midsrv_addr);
     log_println(1, "  -- port: %d", options->midsockport);

+    // send this port number to client
     sprintf(buff, "%d", options->midsockport);
-    if ((ret = send_msg(ctlsockfd, TEST_PREPARE, buff, strlen(buff))) < 0)
+    if ((ret = send_msg(ctlsockfd, TEST_PREPARE, buff, strlen(buff))) < 0)  
//protocol validation log
        return ret;

     /* set mss to 1456 (strange value), and large snd/rcv buffers
@@ -353,25 +381,31 @@
      * will be done in the future.
      */
     clilen = sizeof(cli_addr);
+
+    // Wait on listening socket and read data once ready.
+    // Choose a retry count of "5" to wait for activity on the socket
     FD_ZERO(&rfd);
     FD_SET(options->midsockfd, &rfd);
     sel_tv.tv_sec = 5;
     sel_tv.tv_usec = 0;
-    for (j=0; j<5; j++) {
+    for (j=0; j<5; j++) { // TODO 5 constant declaration
       ret = select((options->midsockfd)+1, &rfd, NULL, NULL, &sel_tv);
-      if ((ret == -1) && (errno == EINTR))
+      if ((ret == -1) && (errno == EINTR)) // socket interruption.  
continue waiting for activity on socket
        continue;
-      if (ret == 0)
-       return -100;  /* timeout */
-      if (ret < 0)
+      if (ret == 0)  // timeout
+       return -100;
+      if (ret < 0) // other socket errors, exit
        return -errno;
-      if (j == 4)
+      if (j == 4) // retry exceeded. Quit
        return -101;
 midfd:
+
+	  // if a valid connection request is received, client has connected.  
Proceed.
+         // Note the new socket fd used in the throughput test is this 
(midsfd)
       if ((midsfd = accept(options->midsockfd, (struct sockaddr *)  
&cli_addr, &clilen)) > 0)
        break;

-      if ((midsfd == -1) && (errno == EINTR))
+      if ((midsfd == -1) && (errno == EINTR)) // socket interrupted, wait  
some more
        goto midfd;

       sprintf(tmpstr, "-------     middlebox connection setup returned  
because (%d)", errno);
@@ -382,40 +416,53 @@
       if (j == 4)
        return -102;
     }
+
+    // get meta test details copied into results
     memcpy(&meta.c_addr, &cli_addr, clilen);
     /* meta.c_addr = cli_addr; */
     meta.family = ((struct sockaddr *) &cli_addr)->sa_family;

     buff[0] = '\0';
+    // get web100 connection data
     if ((conn = web100_connection_from_socket(agent, midsfd)) == NULL) {
         log_println(0, "!!!!!!!!!!!  test_mid() failed to get web100  
connection data, rc=%d", errno);
         /* exit(-1); */
-       return -3;
-    }
+        return -3;
+    }
+
+    // Perform S->C throughput test. Obtained results in "buff"
     web100_middlebox(midsfd, agent, conn, buff);
+
+    // Transmit results in the form of a TEST_MSG message
     send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
+
+    // Expect client to send throughput as calculated at its end
+
     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 (Middlebox test): Invalid CWND limited  
throughput received");
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       return 1;
     }
-    if (check_msg_type("Middlebox test", TEST_MSG, msgType, buff, msgLen))  
{
+    if (check_msg_type("Middlebox test", TEST_MSG, msgType, buff, msgLen))  
{ // only TEST_MSG type valid
       sprintf(buff, "Server (Middlebox test): Invalid CWND limited  
throughput received");
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       return 2;
     }
-    if (msgLen <= 0) {
+    if (msgLen <= 0) { // received message's length has to be a valid one
       log_println(0, "Improper message");
       sprintf(buff, "Server (Middlebox test): Invalid CWND limited  
throughput received");
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       return 3;
     }
+
+    // message payload from client == midbox S->c throughput
     buff[msgLen] = 0;
-    *s2c2spd = atof(buff);
+    *s2c2spd = atof(buff); //todo s2c2spd could be named better
     log_println(4, "CWND limited throughput = %0.0f kbps (%s)", *s2c2spd,  
buff);

+    // finalize the midbox test ; disabling socket used for throughput  
test and closing out both sockets
     shutdown(midsfd, SHUT_WR);
     close(midsfd);
     close(options->midsockfd);
@@ -428,15 +475,22 @@
   return 0;
 }

-/*
- * Function name: test_c2s
- * Description: Performs the C2S Throughput test.
- * Arguments: ctlsockfd - the client control socket descriptor
- *            agent - the Web100 agent used to track the connection
- *            testOptions - the test options
- *            conn_options - the connection options
- * Returns: 0 - success,
- *          >0 - error code.
+/**
+ * Perform the C2S Throughput test.
+ * @param ctlsockfd Client control socket descriptor
+ * @param agent Web100 agent used to track the connection
+ * @param testOptions Test options
+ * @param conn_options Connection options
+ * @return 0 - success,
+ *          >0 - error code
+ *          Error codes:
+ *          -1 - Listener socket creation failed -100 -timeout
+ *              while waitin for client to connect to serverÕs ephemeral  
port
+ *			-100 - timeout while waitinf for client to connect to serverÕs  
ephemeral port
+ *                     -errno - Other specific socket error numbers
+ *                     -101 - Retries exceeded while waiting for client to 
connect
+ *                     -102 - Retries exceeded while waiting for data from 
connected client
+ *
  */

 int
@@ -462,7 +516,7 @@
   char listenc2sport[10];
   pthread_t workerThreadId;
   char namebuf[256], dir[128];
-  size_t nameBufLen = 255;
+  size_t nameBufLen = 255; // TODO constant?
   char isoTime[64];
   DIR *dp;
   FILE *fp;
@@ -481,6 +535,8 @@
     log_println(1, " <-- %d - C2S throughput test -->",  
testOptions->child0);
     strcpy(listenc2sport, PORT2);

+    // Determine port to be used. Compute based on options set earlier
+    // by reading from config file, or use default port2 (3002).
     if (testOptions->c2ssockport) {
       sprintf(listenc2sport, "%d", testOptions->c2ssockport);
     }
@@ -492,6 +548,7 @@
       strcpy(listenc2sport, "0");
     }

+    // attempt to bind to a new port and obtain address structure with  
details of listening port
     while (c2ssrv_addr == NULL) {
       c2ssrv_addr = CreateListenSocket(NULL,
           (testOptions->multiple ? mrange_next(listenc2sport) :  
listenc2sport), conn_options, 0);
@@ -509,6 +566,8 @@
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       return -1;
     }
+
+    // get socket FD and the ephemeral port number that client will  
connect to run tests
     testOptions->c2ssockfd = I2AddrFD(c2ssrv_addr);
     testOptions->c2ssockport = I2AddrPort(c2ssrv_addr);
     log_println(1, "  -- port: %d", testOptions->c2ssockport);
@@ -538,49 +597,61 @@

     log_println(1, "Sending 'GO' signal, to tell client %d to head for the  
next test", testOptions->child0);
     sprintf(buff, "%d", testOptions->c2ssockport);
+
+    // send TEST_PREPARE message with ephemreal port detail, indicating  
start of tests
     if ((ret = send_msg(ctlsockfd, TEST_PREPARE, buff, strlen(buff))) < 0)
        return ret;

+    // Wait on listening socket and read data once ready.
+    // Retry 5 times,  waiting for activity on the socket
     clilen = sizeof(cli_addr);
     log_println(6, "child %d - sent c2s prepare to client",  
testOptions->child0);
     FD_ZERO(&rfd);
     FD_SET(testOptions->c2ssockfd, &rfd);
     sel_tv.tv_sec = 5;
     sel_tv.tv_usec = 0;
-    for (j=0; j<5; j++) {
+    for (j=0; j<5; j++) { //todo 5 constant decl
       ret = select((testOptions->c2ssockfd)+1, &rfd, NULL, NULL, &sel_tv);
-      if ((ret == -1) && (errno == EINTR))
-       continue;
-      if (ret == 0)
-       return -100;  /* timeout */
-      if (ret < 0)
-       return -errno;
-      if (j == 4)
-       return -101;
+      if ((ret == -1) && (errno == EINTR)) // socket interrupted. continue  
waiting for activity on socket
+         continue;
+      if (ret == 0)    // timeout
+         return -100;
+      if (ret < 0)          // other socket errors. exit
+         return -errno;
+      if (j == 4)              // retry exceeded. exit
+         return -101;
 recfd:
+
+	  // If a valid connection request is received, client has connected.  
Proceed.
+      // Note the new socket fd - recvsfd- used in the throughput test
       recvsfd = accept(testOptions->c2ssockfd, (struct sockaddr *)  
&cli_addr, &clilen);
       if (recvsfd > 0) {
        log_println(6, "accept() for %d completed", testOptions->child0);
        break;
       }
-      if ((recvsfd == -1) && (errno == EINTR)) {
+      if ((recvsfd == -1) && (errno == EINTR)) { // socket interrupted,  
wait some more
 	log_println(6, "Child %d interrupted while waiting for accept() to  
complete",
                testOptions->child0);
        goto recfd;
       }
       log_println(6, "-------     C2S connection setup for %d returned  
because (%d)",
                testOptions->child0, errno);
-      if (recvsfd < 0)
+      if (recvsfd < 0) // other socket errors,      quit
        return -errno;
-      if (j == 4) {
+      if (j == 4) {    // retry exceeded, quit
 	log_println(6, "c2s child %d, uable to open connection, return from  
test", testOptions->child0);
         return -102;
       }
     }
+
+    // Get address associated with the throughput test. Used for packet  
tracing
     log_println(6, "child %d - c2s ready for test with fd=%d",  
testOptions->child0, recvsfd);
     src_addr = I2AddrByLocalSockFD(get_errhandle(), recvsfd, 0);
+
+    // Get web100 connection. Used to collect web100 variable statistics
     conn = web100_connection_from_socket(agent, recvsfd);

+    // set up packet tracing. Collected data is used for bottleneck link  
calculations
     if (getuid() == 0) {
       pipe(mon_pipe1);
       if ((mon_pid1 = fork()) == 0) {
@@ -594,6 +665,8 @@
                device, &pair, "c2s", options->compress);
         exit(0);    /* Packet trace finished, terminate gracefully */
       }
+
+      // Get data collected from packet tracing into the C2S "ndttrace"  
file
       memset(tmpstr, 0, 256);
       for (i=0; i< 5; i++) {
           ret = read(mon_pipe1[0], tmpstr, 128);
@@ -602,7 +675,8 @@
          break;
       }
       if (strlen(tmpstr) > 5)
-        memcpy(meta.c2s_ndttrace, tmpstr, strlen(tmpstr));  /* name of  
nettrace file passed back from pcap child */
+        memcpy(meta.c2s_ndttrace, tmpstr, strlen(tmpstr));
+                 //name of nettrace file passed back from pcap child
     }

     log_println(5, "C2S test Parent thinks pipe() returned fd0=%d,  
fd1=%d", mon_pipe1[0], mon_pipe1[1]);
@@ -650,6 +724,7 @@
     }
     /* End of test code */

+    // Create C->S log directories, and open the file for writing, if  
snaplog option is enabled
     {
         I2Addr sockAddr = I2AddrBySAddr(get_errhandle(), (struct sockaddr  
*) &cli_addr, clilen, 0, 0);
         memset(namebuf, 0, 256);
@@ -694,13 +769,16 @@
                 fclose(fp);
             }
         }
-    }
+    } //end creating snaplog dirs and opening logfile

     sleep(2);
+
+    // send empty TEST_START indicating start of the test
     send_msg(ctlsockfd, TEST_START, "", 0);
     /* alarm(30); */  /* reset alarm() again, this 10 sec test should  
finish before this signal
                  * is generated.  */

+    // write into snaplog file, based on options. Lock/release resources  
as necessary
     {
         WorkerArgs workerArgs;
         workerArgs.snapArgs = &snapArgs;
@@ -722,56 +800,64 @@
         pthread_mutex_unlock(&mainmutex);
     }

+    // Wait on listening socket and read data once ready.
     t = secs();
-    sel_tv.tv_sec = 11;
+    sel_tv.tv_sec = 11; // time out after 11 seconds
     sel_tv.tv_usec = 0;
     FD_ZERO(&rfd);
     FD_SET(recvsfd, &rfd);
     for (;;) {
       ret = select(recvsfd+1, &rfd, NULL, NULL, &sel_tv);
       if ((ret == -1) && (errno == EINTR)) {
-       continue;
-      }
-      if (ret > 0) {
+         // socket interrupted. Continue waiting for activity on socket
+         continue;
+      }
+      if (ret > 0) { // read from socket
         n = read(recvsfd, buff, sizeof(buff));
-       if ((n == -1) && (errno == EINTR))
+       if ((n == -1) && (errno == EINTR)) // read interrupted,continue 
waiting
          continue;
-        if (n == 0)
+        if (n == 0) // all data has been read
           break;
-        bytes += n;
+        bytes += n; // data byte count has to be increased
         continue;
       }
       break;
     }

     t = secs()-t;
+    //  throughput in kilo bits per sec =
+    //                         (Number of transmitted bytes * 8) / (time 
duration)*(1000)
     *c2sspd = (8.e-3 * bytes) / t;

+    //calculated and assigned the value of the c->s value. hence release  
resources
     if (workerThreadId) {
         pthread_mutex_lock(&mainmutex);
         workerLoop = 0;
         pthread_mutex_unlock(&mainmutex);
         pthread_join(workerThreadId, NULL);
     }
+    // close writing snaplog, if snaplog recording is enabled
     if (options->snaplog) {
         web100_log_close_write(snapArgs.log);
     }

+    // send the server calculated value of C->S throughput as result to  
client
     sprintf(buff, "%6.0f kbps outbound for child %d", *c2sspd,  
testOptions->child0);
     log_println(1, "%s", buff);
-    /* send the c2sspd to the client */
     sprintf(buff, "%0.0f", *c2sspd);
     send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
-    /* get receiver side Web100 stats and write them to the log file */
+
+
+    // get receiver side Web100 stats and write them to the log file.  
close sockets
+
     if (record_reverse == 1)
       web100_get_data_recv(recvsfd, agent, conn, count_vars);
     /* shutdown(recvsfd, SHUT_RD); */
     close(recvsfd);
     close(testOptions->c2ssockfd);

-    /* Next send speed-chk a flag to retrieve the data it collected.
-     * Skip this step if speed-chk isn't running.
-     */
+    // Next, send speed-chk a flag to retrieve the data it collected.
+    // Skip this step if speed-chk isn't running.

     if (getuid() == 0) {
       log_println(1, "Signal USR1(%d) sent to child [%d]", SIGUSR1,  
mon_pid1);
@@ -818,8 +904,10 @@
       }
     }

+    // An empty TEST_FINALIZE message is sent to conclude the test
     send_msg(ctlsockfd, TEST_FINALIZE, "", 0);

+    //  Close opened resources for packet capture
     if (getuid() == 0) {
       for (i=0; i<5; i++) {
         ret = write(mon_pipe1[1], "c", 1);
@@ -844,15 +932,24 @@
   return 0;
 }

-/*
- * Function name: test_s2c
- * Description: Performs the S2C Throughput test.
+/**
+ * Perform the S2C Throughput test.
  * Arguments: ctlsockfd - the client control socket descriptor
  *            agent - the Web100 agent used to track the connection
  *            testOptions - the test options
  *            conn_options - the connection options
  * Returns: 0 - success,
  *          >0 - error code.
+ *          Error codes:
+ * 			 	-1	   - Message reception errors/inconsistencies in clientÕs final  
message, or Listener socket creation failed or cannot write message header  
information while attempting to send
+ *                      TEST_PREPARE message
+ *                             -2         - Cannot write message data while 
attempting to send
+ *                      TEST_PREPARE message, or Unexpected message type 
received
+ *             -3         -  Received message is invalid
+ *          	-100   - timeout while waitinf for client to connect to  
serverÕs ephemeral port
+ *                             -101   - Retries exceeded while waiting for 
client to connect
+ *				-102   - Retries exceeded while waiting for data from connected  
client
+ *                     -errno - Other specific socket error numbers
  */

 int
@@ -874,7 +971,7 @@
   struct timeval sel_tv;
   fd_set rfd;
   char buff[BUFFSIZE+1];
-  int c3=0, i;
+  int c3=0, i; //todo what is c3?
   PortPair pair;
   I2Addr s2csrv_addr=NULL, src_addr=NULL;
   char listens2cport[10];
@@ -900,13 +997,15 @@
   web100_var* var;
   pthread_t workerThreadId;
   int SndMax=0, SndUna=0;
-  int c1=0, c2=0;
+  int c1=0, c2=0; // sent data attempt queue, Draining Queue. TODO name  
appr
   SnapArgs snapArgs;
   snapArgs.snap = NULL;
   snapArgs.log = NULL;
   snapArgs.delay = options->snapDelay;
   wait_sig = 0;

+  // Determine port to be used. Compute based on options set earlier
+  // by reading from config file, or use default port2 (3003)
   if (testOptions->s2copt) {
     setCurrentTest(TEST_S2C);
     log_println(1, " <-- %d - S2C throughput test -->",  
testOptions->child0);
@@ -923,6 +1022,7 @@
       strcpy(listens2cport, "0");
     }

+    // attempt to bind to a new port and obtain address structure with  
details of listening port
     while (s2csrv_addr == NULL) {
       s2csrv_addr = CreateListenSocket(NULL,
           (testOptions->multiple ? mrange_next(listens2cport) :  
listens2cport), conn_options, 0);
@@ -947,6 +1047,8 @@
       send_msg(ctlsockfd, MSG_ERROR, buff, strlen(buff));
       return -1;
     }
+
+    // get socket FD and the ephemeral port number that client will  
connect to run tests
     testOptions->s2csockfd = I2AddrFD(s2csrv_addr);
     testOptions->s2csockport = I2AddrPort(s2csrv_addr);
     log_println(1, "  -- s2c %d port: %d", testOptions->child0,  
testOptions->s2csockport);
@@ -973,22 +1075,22 @@
      * }
      */

-    /* Data received from speed-chk, tell applet to start next test */
+    // Data received from speed-chk. Send TEST_PREPARE "GO" signal with  
port number
     sprintf(buff, "%d", testOptions->s2csockport);
     j = send_msg(ctlsockfd, TEST_PREPARE, buff, strlen(buff));
     if (j == -1) {
 	log_println(6, "S2C %d Error!, Test start message not sent!",  
testOptions->child0);
        return j;
     }
-    if (j == -2) {
+    if (j == -2) { // could not write message data
 	log_println(6, "S2C %d Error!, server port [%s] not sent!",  
testOptions->child0, buff);
        return j;
     }

-    /* ok, await for connect on 3rd port
-     * This is the second throughput test, with data streaming from
-     * the server back to the client.  Again stream data for 10 seconds.
-     */
+    // ok, await for connect on 3rd port
+    // This is the second throughput test, with data streaming from
+    // the server back to the client.  Again stream data for 10 seconds.
+
     log_println(1, "%d waiting for data on testOptions->s2csockfd",  
testOptions->child0);

     clilen = sizeof(cli_addr);
@@ -1001,34 +1103,38 @@
       if ((ret == -1) && (errno == EINTR))
        continue;
       if (ret == 0)
-       return -100;  /* timeout */
+       return -100;  // timeout
       if (ret < 0)
-       return -errno;
+       return -errno;  // other socket errors. exit
       if (j == 4)
-       return -101;
+       return -101;    // retry exceeded. exit
+
+      // If a valid connection request is received, client has connected.  
Proceed.
+      // Note the new socket fd - xmitfd - used in the throughput test
 ximfd:
       xmitsfd = accept(testOptions->s2csockfd, (struct sockaddr *)  
&cli_addr, &clilen);
       if (xmitsfd > 0) {
        log_println(6, "accept() for %d completed", testOptions->child0);
        break;
       }
-      if ((xmitsfd == -1) && (errno == EINTR)) {
+      if ((xmitsfd == -1) && (errno == EINTR)) { // socket interrupted,  
wait some more
 	log_println(6, "Child %d interrupted while waiting for accept() to  
complete",
                testOptions->child0);
        goto ximfd;
       }
       log_println(6, "-------     S2C connection setup for %d returned  
because (%d)",
                testOptions->child0, errno);
-      if (xmitsfd < 0)
+      if (xmitsfd < 0)      // other socket errors, quit
        return -errno;
-      if (++j == 4) {
-	log_println(6, "s2c child %d, uable to open connection, return from  
test", testOptions->child0);
+      if (++j == 4) {   // retry exceeded, quit
+	log_println(6, "s2c child %d, unable to open connection, return from  
test", testOptions->child0);
         return -102;
       }
     }
     src_addr = I2AddrByLocalSockFD(get_errhandle(), xmitsfd, 0);
     conn = web100_connection_from_socket(agent, xmitsfd);

+    // set up packet capture. The data collected is used for bottleneck  
link calculations
     if (xmitsfd > 0) {
       log_println(6, "S2C child %d, ready to fork()", testOptions->child0);
       if (getuid() == 0) {
@@ -1044,15 +1150,16 @@
           exit(0);    /* Packet trace finished, terminate gracefully */
         }
        memset(tmpstr, 0, 256);
-       for (i=0; i< 5; i++) {
+       for (i=0; i< 5; i++) { // read nettrace file name into "tmpstr"
           ret = read(mon_pipe2[0], tmpstr, 128);
-         if ((ret == -1) && (errno == EINTR))
+	  if ((ret == -1) && (errno == EINTR)) // socket interrupted, try reading  
again
            continue;
          break;
        }

        if (strlen(tmpstr) > 5)
-	  memcpy(meta.s2c_ndttrace, tmpstr, strlen(tmpstr));  /* name of nettrace  
file passed back from pcap child */
+         memcpy(meta.s2c_ndttrace, tmpstr, strlen(tmpstr));
+			// name of nettrace file passed back from pcap child copied into meta  
structure
       }

       /* Check, and if needed, set the web100 autotuning function on.   
This improves
@@ -1090,6 +1197,7 @@
       }
       /* End of test code */

+      // create directory to write web100 snaplog trace
       {
         I2Addr sockAddr = I2AddrBySAddr(get_errhandle(), (struct sockaddr  
*) &cli_addr, clilen, 0, 0);
         memset(namebuf, 0, 256);
@@ -1121,6 +1229,8 @@
         group = web100_group_find(agent, "read");
         snapArgs.snap = web100_snapshot_alloc(group, conn);
        I2AddrFree(sockAddr);
+
+               // If snaplog option is enabled, save snaplog trace
         if (options->snaplog) {
            memcpy(meta.s2c_snaplog, dir, strlen(dir));
             fp = fopen(get_logfile(),"a");
@@ -1148,6 +1258,7 @@
       tgroup = web100_group_find(agent, "tune");
       tsnap = web100_snapshot_alloc(tgroup, conn);

+      // fill send buffer with random printable data for throughput test
       bytes = 0;
       k = 0;
       for (j=0; j<=BUFFSIZE; j++) {
@@ -1156,6 +1267,7 @@
         buff[j] = (k++ & 0x7f);
       }

+      // Send message to client indicating TEST_START
       if (send_msg(ctlsockfd, TEST_START, "", 0) < 0)
 	log_println(6, "S2C test - Test-start message failed for pid=%d",  
mon_pid2);
       /* ignore the alrm signal */
@@ -1163,6 +1275,8 @@
       new.sa_handler = catch_s2c_alrm;
       sigaction(SIGALRM, &new, &old);

+      // capture current values (i.e take snap shot) of web_100 variables
+      // Write into snaplog if option is enabled. Hold/release semaphores  
as needed.
       {
           WorkerArgs workerArgs;
           workerArgs.snapArgs = &snapArgs;
@@ -1173,7 +1287,7 @@
               log_println(0, "Cannot create worker thread for writing snap  
log!");
               workerThreadId = 0;
           }
-
+          // acquire semaphore, and write snaplog
           pthread_mutex_lock(&mainmutex);
           workerLoop = 1;
           web100_snap(snapArgs.snap);
@@ -1185,47 +1299,63 @@
       }

       /* alarm(20); */
-      t = secs();
-      s = t + 10.0;
+      t = secs();  // current time
+      s = t + 10.0; // set timeout to 10 s in future

       log_println(6, "S2C child %d begining test", testOptions->child0);
+
       while(secs() < s) {
-        c3++;
-        if (options->avoidSndBlockUp) {
+        c3++; 							// Increment total attempts at sending-> buffer  
control
+        if (options->avoidSndBlockUp) { // Do not block send buffers
             pthread_mutex_lock(&mainmutex);
+
+            // get details of next sequence # to be sent and fetch value  
from snap file
             web100_agent_find_var_and_group(agent, "SndNxt", &group, &var);
             web100_snap_read(var, snapArgs.snap, tmpstr);
             SndMax = atoi(web100_value_to_text(web100_get_var_type(var),  
tmpstr));
+            // get oldest un-acked sequence number
             web100_agent_find_var_and_group(agent, "SndUna", &group, &var);
             web100_snap_read(var, snapArgs.snap, tmpstr);
             SndUna = atoi(web100_value_to_text(web100_get_var_type(var),  
tmpstr));
             pthread_mutex_unlock(&mainmutex);
+
+            // Temporarily stop sending data if you sense that the  
receiving end is overwhelmed
+            // This is calculated by checking if (8192 * 4) <
+            //        ((Next Sequence Number To Be Sent) - (Oldest  
Unacknowledged Sequence Number) - 1)
+            // Increment draining queue value
             if ((RECLTH<<2) < (SndMax - SndUna - 1)) {
                 c1++;
                 continue;
             }
         }

+        // attempt to write random data into the client socket
         n = write(xmitsfd, buff, RECLTH);
-       if ((n == -1) && (errno == EINTR))
+	if ((n == -1) && (errno == EINTR)) // socket interrupted, continue  
attempting to write
          continue;
         if (n < 0)
-          break;
+          break;  // all data written. Exit
         bytes += n;

         if (options->avoidSndBlockUp) {
-          c2++;
-        }
-      }
+          c2++; // increment "sent data" queue
+        }
+      } // Completed end of trying to transmit data for the goodput test
       /* alarm(10); */
       sigaction(SIGALRM, &old, NULL);
       sndqueue = sndq_len(xmitsfd);

+      // finalize the midbox test ; disabling socket used for throughput  
test
       log_println(6, "S2C child %d finished test", testOptions->child0);
       shutdown(xmitsfd, SHUT_WR);  /* end of write's */

+      // get actual time duration during which data was transmitted
       s = secs() - t;
+
+      // Throughput in kbps = (no of bits sent * 8) / (1000 * time data  
was sent)
       x2cspd = (8.e-3 * bytes) / s;
+
+     // Release semaphore, and close snaplog file.  finalize other data
       if (workerThreadId) {
           pthread_mutex_lock(&mainmutex);
           workerLoop = 0;
@@ -1238,15 +1368,18 @@
       web100_snapshot_free(snapArgs.snap);
       /* send the x2cspd to the client */
       memset(buff, 0, sizeof(buff));
+
+      // Send throughput, unsent byte count, total sent byte count to  
client
       sprintf(buff, "%0.0f %d %0.0f", x2cspd, sndqueue, bytes);
       if (send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff)) < 0)
-	log_println(6, "S2C test - failed to send test message to pid=%d",  
mon_pid2);
+    	  log_println(6, "S2C test - failed to send test message to pid=%d",  
mon_pid2);

       web100_snap(rsnap);
       web100_snap(tsnap);

       log_println(1, "sent %d bytes to client in %0.2f seconds",(int)  
bytes, s);
       log_println(1, "Buffer control counters Total = %d, new data = %d,  
Draining Queue = %d", c3, c2, c1);
+
       /* Next send speed-chk a flag to retrieve the data it collected.
        * Skip this step if speed-chk isn't running.
        */
@@ -1306,16 +1439,19 @@
                  * 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);
+    ret = web100_get_data(tsnap, ctlsockfd, agent, count_vars); //send  
web100 data to client
     web100_snapshot_free(tsnap);
-    ret = web100_get_data(rsnap, ctlsockfd, agent, count_vars);
+    ret = web100_get_data(rsnap, ctlsockfd, agent, count_vars); //send  
tuning-related web100 data collected to client
     web100_snapshot_free(rsnap);
+
+    // If sending web100 variables above failed, indicate to client
     if (ret < 0) {
        log_println(6, "S2C - No web100 data received for pid=%d", mon_pid2);
         sprintf(buff, "No Data Collected: 000000");
        send_msg(ctlsockfd, TEST_MSG, buff, strlen(buff));
     }

+    // Wait for message from client. Client sends its calculated  
throughput value
     msgLen = sizeof(buff);
     if (recv_msg(ctlsockfd, &msgType, buff, &msgLen)) {
       log_println(0, "Protocol error!");
@@ -1335,8 +1471,10 @@
       return -3;
     }
     buff[msgLen] = 0;
-    *s2cspd = atoi(buff);
-
+    *s2cspd = atoi(buff); // save Throughput value as seen by client
+
+    // Final activities of ending tests. Close sockets, file descriptors,
+    //    send finalise message to client
     close(xmitsfd);
     if (send_msg(ctlsockfd, TEST_FINALIZE, "", 0) < 0)
 	log_println(6, "S2C test - failed to send finalize message to pid=%d",  
mon_pid2);
@@ -1365,10 +1503,9 @@
   return 0;
 }

-/*
- * Function name: getCurrentTest
- * Description: Returns the id of the currently running test.
- * Returns: The id of the currently running test.
+/**
+ * Return the id of the currently running test.
+ * @return integer id of the currently running test.
  */

 int
@@ -1377,10 +1514,8 @@
   return currentTest;
 }

-/*
- * Function name: setCurrentTest
- * Description: Sets the id of the currently running test.
***The diff for this file has been truncated for email.***
=======================================
--- /branches/kkumar_code_organize/src/testoptions.h	Sun May  8 04:04:21  
2011
+++ /branches/kkumar_code_organize/src/testoptions.h	Fri Sep 23 13:50:35  
2011
@@ -12,7 +12,7 @@
 #include "web100srv.h"

 typedef struct testoptions {
-  int multiple;
+  int multiple; // TODO field comments
   int mainport;

   int midopt;
=======================================
--- /branches/kkumar_code_organize/src/usage.c  Thu Sep  8 09:20:22 2011
+++ /branches/kkumar_code_organize/src/usage.c  Fri Sep 23 13:50:35 2011
@@ -12,11 +12,10 @@
 #include <sys/socket.h>
 #include <assert.h>

-/*
- * Function name: short_usage
- * Description: Prints the short usage of the application.
- * Arguments: prog - the name of the application
- *            info - the text printed in the first line
+/**
+ * Prints the short usage of the application.
+ * @param prog The name of the application
+ * @param info Text printed in the first line
  */

 void
=======================================
--- /branches/kkumar_code_organize/src/web100-util.c	Fri Sep 16 08:39:32  
2011
+++ /branches/kkumar_code_organize/src/web100-util.c	Fri Sep 23 13:50:35  
2011
@@ -217,8 +217,8 @@
     web100_snap_read(var, snap, line);
     SndUna = atoi(web100_value_to_text(web100_get_var_type(var), line));

-    // stop sending data if (buf size * 16) <
-    //  [ (Next Sequence # To Be Sent) - (Oldest Unacknowledged Sequence  
#) - 1 ]
+    // stop sending data if (buf size * 16) <
+    //  	[ (Next Sequence # To Be Sent) - (Oldest Unacknowledged Sequence  
#) - 1 ]
     if ((currentMSSval<<4) < (SndMax - SndUna - 1)) {
       continue;
     }
@@ -299,7 +299,7 @@
     ok = 1;
   }

-  //close file pointers after web100 variables have been fetched
+  // close file pointers after web100 variables have been fetched
   if (fp) {
     fprintf(fp, "\n");
     fclose(fp);
@@ -309,7 +309,9 @@


 /**
- * Collect Web100 stats from a snapshot and transmit to a receiver
+ * Collect Web100 stats from a snapshot and transmit to a receiver.
+ * The transmission is done using a TES_MSG type message and sent to
+ * client reachable via the input parameter socket FD.
  *
  * @param snap pointer to a web100_snapshot taken earlier
  * @param ctlsock integer socket file descriptor indicating data recipient
=======================================
--- /branches/kkumar_code_organize/src/web100srv.c      Sun May  8 04:04:21 
2011
+++ /branches/kkumar_code_organize/src/web100srv.c      Fri Sep 23 13:50:35 
2011
@@ -107,7 +107,9 @@
 int queue=1;
 int view_flag=0;
 int record_reverse=0;
-int testing, waiting, mclients;
+int testing; // a test is currently being performed.
+int waiting; // # of many tests pending
+int mclients; // multiple client mode client count
 int refresh = 30;
 int old_mismatch=0;  /* use the old duplex mismatch detection heuristic */
 /* int sig1, sig2, sig17; */
@@ -198,7 +200,11 @@
   {0, 0, 0, 0}
 };

-/* Process a SIGCHLD signal */
+
+/**
+ * Process a SIGCHLD signal.
+ * @param pid_t Process id to be processed
+ * */
 void
 child_sig(pid_t chld_pid)
 {
@@ -210,15 +216,15 @@
   log_println(2, "Processing SIGCHLD signal for active web100srv process  
[%d], sig17=%d", chld_pid, sig17);

   /* this routine cleans up after a child process has terminated.  There  
are 2 types of
-   * child processes.  The pkt-pair timing children are type 1 and the  
spawnd children to run
+   * child processes.  The pkt-pair timing children are type 1 and the  
spawned children to run
    * the test are type 0.  For the pkt-pair children, just acknowledge  
their signal to keep
-   * them from becoming defunt.  For the type 0 children, use wait3() to  
figure out which
+   * them from becoming defunct.  For the type 0 children, use wait3() to  
figure out which
    * child terminated and then clean up the FIFO queue.
    * RAC 2/8/10
    *
    * Added new type (-1) on 2/11/10.  This type indicates a child has  
terminated due to
    * a communications fault.  For some reason the child is stuck in the  
FIFO queue and
-   * it needs to be removed.  In this csse, the calling function will grab  
the head pointer's
+   * it needs to be removed.  In this case, the calling function will grab  
the head pointer's
    * PID value, call this function with a -1 to remove the entry from the  
FIFO, issue a
    * SIGTERM signal and call this function with the childs PID.  This  
should prevent the
    * code from entering into a loop.
@@ -383,7 +389,11 @@
   log_println(6, "Did we get here???");
 }

-/* Catch termination signal(s) and print message in log file */
+
+/**
+ * Catch termination signal(s) and print message in log file
+ * @param signo Signal number
+ * */
 void
 cleanup(int signo)
 {
@@ -522,7 +532,11 @@
   }
 }

-/* LoadConfig routine copied from Internet2. */
+/** LoadConfig routine copied from Internet2.
+ * @param *name Pointer to Application name
+ * @param **lbuf line buffer
+ * @param *lbuf_max line buffer max - both help keep track of a  
dynamically grown "line" buffer.*/
+
 static void LoadConfig(char* name, char **lbuf, size_t *lbuf_max)
 {
   FILE *conf;
@@ -536,6 +550,7 @@

   log_println(1, " Reading config file %s to obtain options",  
ConfigFileName);

+  // Read the values for various keys and store them in appropriate  
variables
   while ((rc = I2ReadConfVar(conf, rc, key, val, 256, lbuf, lbuf_max)) >  
0) {
     if (strncasecmp(key, "administrator_view", 5) == 0) {
       admin_view = 1;
@@ -735,10 +750,12 @@
   fclose(conf);
 }

-/* This routine walks through the list of queued clients and kills off  
those
- * that don't respond.  New clients (after v3.5.5) will reqpond to this  
query
+/**
+ *  This routine walks through the list of queued clients and kills off  
those
+ * that don't respond.  New clients (after v3.5.5) will respond to this  
query
  * older clients wouldn't, so use the oldclient flag to tell them apart.
  * RAC 7/8/09
+ * @param *head_ptr Pointer to the head of the list
  */
 void *
 zombieWorker(void *head_ptr) {
@@ -772,6 +789,8 @@
            continue;
        }
 	log_println(6, "New client found, checking for response, child=%d",  
tmp_ptr->pid);
+
+       // send "keep-alive" SRV_QUEUE message to client and expect a response
        rc = send_msg(tmp_ptr->ctlsockfd, SRV_QUEUE, tmpstr, strlen(tmpstr));
 	log_println(6, "send_msg() returned %d during zombie check on client %d",  
rc, tmp_ptr->pid);
        FD_ZERO(&rfd);
@@ -782,7 +801,7 @@
          rc = select((tmp_ptr->ctlsockfd)+1, &rfd, NULL, NULL, &sel_tv);
          switch (rc) {
            case 0:
-             /*  a timeout occurred, remove zombie client from list */
+             //  a timeout occurred, remove zombie client from list
 	      log_println(6, "New client didn't respond - must be a zombie, get  
rid of it, child=%d", tmp_ptr->pid);
               while ((rc = sem_wait(&ndtq)) == -1 && errno == EINTR) {
 	        log_println(6, "Waiting for ndtq semaphore to free - adding new  
client 1");
@@ -810,7 +829,7 @@
                child_sig(0);
           */
              break;
-           case -1:
+           case -1: // some error status
              if (errno == EINTR) {
 		log_println(6, "select() interrupted by signal, continue waiting for  
action or timeout");
                continue;
@@ -824,6 +843,12 @@
     return NULL;
 }

+/**
+ * Capture CPU time details
+ *
+ * @param arg* void pointer to the log file sued to record CPU time details
+ * @param void* NULL
+ * */
 void*
 cputimeWorker(void* arg)
 {
@@ -850,6 +875,13 @@

     return NULL;
 }
+
+/**
+ * Capture CPU time details
+ *
+ * @param arg* void pointer to the log file sued to record CPU time details
+ * @param void* NULL
+ * */

 int
 run_test(web100_agent* agent, int ctlsockfd, TestOptions* testopt, char  
*test_suite)
@@ -861,7 +893,7 @@
   char tmpstr[256];
   char isoTime[64];

-  int n;
+  int n; // todo what is n?
   int Timeouts, SumRTT, CountRTT, PktsRetrans, FastRetran, DataPktsOut;
   int AckPktsOut, CurrentMSS, DupAcksIn, AckPktsIn, MaxRwinRcvd, Sndbuf;
   int CurrentCwnd, SndLimTimeRwin, SndLimTimeCwnd, SndLimTimeSender,  
DataBytesOut;
@@ -872,8 +904,12 @@
   int RcvWinScale, SndWinScale;
   int link=100, mismatch=0, bad_cable=0, half_duplex=0, congestion=0,  
totaltime;
   int ret, spd_index;
-  int index, links[16], max, total;
-  int c2sdata = 0, c2sack = 0, s2cdata = 0, s2cack = 0;
+  int index, links[16], max;
+  int total; // total ifspeed ? todo
+  int c2sdata = 0; // C->S data link speed indicator determined using  
results
+  int c2sack = 0;  //
+  int s2cdata = 0; // S->C data link speed indicator determined using  
results
+  int s2cack = 0;
   int j;
   int totalcnt;
   int autotune;
@@ -884,11 +920,17 @@

   double rttsec, rwin, swin, cwin;
   double rwintime, cwndtime, sendtime;
-  double oo_order, waitsec;
-  double bw2, avgrtt, timesec, loss2, RTOidle;
-  double s2cspd, c2sspd;
+  double oo_order; // out-of-order packet ratio
+  double waitsec;
+  double bw2;
+  double avgrtt; // Average roundtrip time
+  double timesec;
+  double loss2;  // Packet loss as calculated from S->c tests. TODO change  
name. There also is no "loss"
+  double RTOidle;
+  double s2cspd; // average throughput
+  double c2sspd;
   double s2c2spd;
-  double spd;
+  double spd; // total send throughput in S->C
   double acks, aspd = 0, tmouts, rtran, dack;
   float runave[4];

@@ -900,17 +942,21 @@
   log_println(4, "Child process %d started", getpid());
   testopt->child0 = getpid();

+  // initialize speed_index array. todo. what is this spd index?
   for (spd_index=0; spd_index<4; spd_index++)
     for (ret=0; ret<256; ret++)
       spds[spd_index][ret] = 0x00;
   spd_index = 0;

+  // obtain web100 connection and check auto-tune status
   conn = web100_connection_from_socket(agent, ctlsockfd);
   autotune = web100_autotune(ctlsockfd, agent, conn);

+  // client needs to be version compatible. Send current version
   sprintf(buff, "v%s", VERSION);
   send_msg(ctlsockfd, MSG_LOGIN, buff, strlen(buff));

+  // initiate test with MSG_LOGIN message. TODO test_suite
   log_println(3, "run_test() routine, asking for test_suite = %s",  
test_suite);
   send_msg(ctlsockfd, MSG_LOGIN, test_suite, strlen(test_suite));
   /* if ((n = initialize_tests(ctlsockfd, &testopt, conn_options))) {
@@ -937,6 +983,7 @@
   }

 /*  alarm(15); */
+  // Run scheduled test. Log error code if necessary
   log_println(6, "Starting middlebox test");
   if ((ret = test_mid(ctlsockfd, agent, &*testopt, conn_options,  
&s2c2spd)) != 0) {
       if (ret < 0)
@@ -982,7 +1029,12 @@
     }
   }

+  // Compute variable values from test results and deduce results
   log_println(4, "Finished testing C2S = %0.2f Mbps, S2C = %0.2f Mbps",  
c2sspd/1000, s2cspd/1000);
+
+  // The section below helps determine link speeds.
+  //    NDT quantizes throughput into one of a group of pre-defined  
bins/buckets that contain
+  //     counters. Get values of these bins (12 in number) and other key  
stats
   for (n=0; n<spd_index; n++) {
      
sscanf(spds[n], "%d %d %d %d %d %d %d %d %d %d %d %d %f %d %d %d %d %d %d",  
&links[0],
         &links[1], &links[2], &links[3], &links[4], &links[5], &links[6],
@@ -992,8 +1044,12 @@
     index = 0;
     total = 0;
     /* for (j=0; j<10; j++) { */
+
     if ((ifspeed == -1) || (ifspeed == 0) || (ifspeed > 10))
-       ifspeed = 10;
+       ifspeed = 10;  // ifspeed was probably not collected in these cases
+
+    // get the ifspeed bin with the biggest counter value.
+    // NDT determines link speed using this
     for (j=0; j<=ifspeed; j++) {
       total += links[j];
       if (max < links[j]) {
@@ -1001,8 +1057,12 @@
         index = j;
       }
     }
+
+    // speed data was not collected correctly
     if (links[index] == -1)
       index = -1;
+
+    // log
     fp = fopen(get_logfile(),"a");
     if (fp == NULL) {
       log_println(0, "Unable to open log file '%s', continuing on without  
logging", get_logfile());
@@ -1013,7 +1073,9 @@
       fclose(fp);
     }

-    /* When the C2S test is disabled, we have to skip the results */
+    // When the C2S test is disabled, we have to skip the results
+    // Note: spd[0] , [1] contains C->S test results
+    // spd[2] , spd [3] contains S->C test results
     switch (n  + (testopt->c2sopt ? 0 : 2)) {
       case 0: c2sdata = index;
               log_print(1, "Client --> Server data detects link = ");
@@ -1027,6 +1089,8 @@
       case 3: s2cack = index;
               log_print(1, "Server <-- Client Ack's detect link = ");
     }
+
+    // classify link speed based on the max ifspeed seen
     switch (index) {
       case -1: log_println(1, "System Fault");     break;
       case 0:  log_println(1, "RTT");              break;
@@ -1041,15 +1105,18 @@
       case 9:  log_println(1, "10 Gigabit Enet");  break;
       case 10: log_println(1, "Retransmissions");  break;
     }
-  }
-
-  /* get some web100 vars */
+  } //end section to determine speed. TODO - break into new function?  
calc_link_speed
+
+  // Get web100 vars
+
+  // ...determine number of times congestion window has been changed
   if (options.cwndDecrease) {
     dec_cnt = inc_cnt = same_cnt = 0;
     CwndDecrease(agent, options.s2c_logname, &dec_cnt, &same_cnt,  
&inc_cnt);
     log_println(2, "####### decreases = %d, increases = %d, no change  
= %d", dec_cnt, inc_cnt, same_cnt);
   }

+  // ...other variables
   web100_logvars(&Timeouts, &SumRTT, &CountRTT,
       &PktsRetrans, &FastRetran, &DataPktsOut,
       &AckPktsOut, &CurrentMSS, &DupAcksIn,
@@ -1064,22 +1131,33 @@
       &CurTimeoutCount, &AbruptTimeouts, &SendStall, &SlowStart,
       &SubsequentTimeouts, &ThruBytesAcked);

+  // end getting web100 variable values
   /* if (rc == 0) { */
-  /* Calculate some values */
+
+  // section to calculate duplex mismatch
+
+  // Calculate average sound trip time and convert to seconds
   avgrtt = (double) SumRTT/CountRTT;
   rttsec = avgrtt * .001;
   /* loss = (double)(PktsRetrans-  
FastRetran)/(double)(DataPktsOut-AckPktsOut); */
+
+  // Calculate packet loss
   loss2 = (double)CongestionSignals/PktsOut;
   if (loss2 == 0) {
     if (c2sdata > 5)
-      loss2 = .0000000001;  /* set to 10^-10 for links faster than FastE */
+      loss2 = .0000000001;  // set to 10^-10 for links faster than FastE
     else
-      loss2 = .000001;    /* set to 10^-6 for now */
+      loss2 = .000001;    // set to 10^-6 for now
   }

+  // Calculate ratio of packets arriving out of order
   oo_order = (double)DupAcksIn/AckPktsIn;
+
+  // calculate theoretical maximum goodput in bits
+  // todo constants for 1024, 8.
   bw2 = (CurrentMSS / (rttsec * sqrt(loss2))) * 8 / 1024 / 1024;

+  //
   if ((SndWinScale > 15) || (Sndbuf < 65535))
     SndWinScale = 0;
   if ((RcvWinScale > 15) || (MaxRwinRcvd < 65535))
@@ -1094,20 +1172,36 @@
   swin = (double)Sndbuf * 8 / 1024 / 1024;
   cwin = (double)MaxCwnd * 8 / 1024 / 1024;

+  // Total test time
   totaltime = SndLimTimeRwin + SndLimTimeCwnd + SndLimTimeSender;
+
+  // time spent being send-limited due to congestion window
   rwintime = (double)SndLimTimeRwin/totaltime;
+
+  // time spent in being receive limited due to client's recv window
   cwndtime = (double)SndLimTimeCwnd/totaltime;
+
+  // time spent in being send-limited due to own fault
   sendtime = (double)SndLimTimeSender/totaltime;
-  timesec = totaltime/1000000;
+  timesec = totaltime/1000000;                 // microsecs
+
+  // Current retransmit timeoutX timeout count = idle time spent waiting  
for packets to arrive
+  // When divided by total test time, they indicate fraction of time spent  
idle due to RTO
   RTOidle = (Timeouts * ((double)CurrentRTO/1000))/timesec;
-  tmouts = (double)Timeouts / PktsOut;
-  rtran = (double)PktsRetrans / PktsOut;
-  acks = (double)AckPktsIn / PktsOut;
-  dack = (double)DupAcksIn / (double)AckPktsIn;
-
+  tmouts = (double)Timeouts / PktsOut;  // timeout fraction //todo rename  
all 4
+  rtran = (double)PktsRetrans / PktsOut; // retrans fraction
+  acks = (double)AckPktsIn / PktsOut; 	 // Fraction of acks recived for  
sent data
+  dack = (double)DupAcksIn / (double)AckPktsIn; // duplicate acks fraction
+
+  // actual throughput in Mbps (totaltime is in microseconds)
   spd = ((double)DataBytesOut / (double)totaltime) * 8;
+         // todo rename spd to "calculated total send throughput"
+
+  // total time spent waiting
   waitsec = (double) (CurrentRTO * Timeouts)/1000;
   log_println(2, "CWND limited test = %0.2f while unlimited = %0.2f",  
s2c2spd, s2cspd);
+
+  // Is goodput measured from from S->C as reported by client > as  
reported by server?
   if ((s2c2spd > s2cspd) && (multiple == 0))
     log_println(2, "Better throughput when CWND is limited, may be duplex  
mismatch");
   else
@@ -1115,20 +1209,35 @@


   /* remove the following line when the new detection code is ready for  
release */
+  // retaining old comment above
+
+  // client link duplex mismatch detection heuristic
   old_mismatch = 1;
   if (old_mismatch == 1) {
-    if ((cwndtime > .9) && (bw2 > 2) && (PktsRetrans/timesec > 2) &&
-        (MaxSsthresh > 0) && (RTOidle > .01) && (link > 2) && (s2cspd <  
s2c2spd) &&
-       (multiple == 0))
-    {  if (s2cspd < c2sspd)
+    if ((cwndtime > .9)  // more than 90% time spent being receiver window  
limited
+               && (bw2 > 2)  // theoretical max goodput > 2mbps
+                       && (PktsRetrans/timesec > 2)
+                                // #of segments with pkt-retransmissions> 2
+                               && (MaxSsthresh > 0)   // max slow start 
threshold > 0
+                                       && (RTOidle > .01) // cumulative RTO 
time > 1% test duration
+                                               && (link > 2)  // not 
wireless link
+                                                       && (s2cspd < s2c2spd) 
//S->C throughput calculated
+                                                                                
               // by server < client value
+                                                               && (multiple 
== 0))
+    {
+	  if (s2cspd < c2sspd) // also, S->C throughput is lesser than C->S  
throughput
       mismatch = 1;
       else
         mismatch = 2;
       link = 0;
     }

-    /* test for uplink with duplex mismatch condition */
-    if (((s2cspd/1000) > 50) && (spd < 5) && (rwintime > .9) && (loss2  
< .01)) {
+    // test for uplink with duplex mismatch condition
+    if (((s2cspd/1000) > 50)                // S->C goodput > 50 Mbps
+               && (spd < 5)                         // actual send throughput 
< 5 Mbps
+                       && (rwintime > .9)   // receive window limited for 
>90% of the time
+                               && (loss2 < .01)) // packet loss < 1%
+    {
       mismatch = 2;
       link = 0;
     }
@@ -1139,38 +1248,52 @@
      *  RAC 5-11-06
      */
   }
-
-  /* estimate is less than throughput, something is wrong */
+  // end section calculating duplex mismatch
+
+  // Section to deduce if there is faulty hardware links
+
+  // estimate is less than actual throughput, something is wrong
   if (bw2 < spd)
     link = 0;

+  // Faulty hardware link heuristic. todo read about error here
   if (((loss2*100)/timesec > 15) && (cwndtime/timesec > .6) &&
       (loss2 < .01) && (MaxSsthresh > 0))
     bad_cable = 1;

-  /* test for Ethernet link (assume Fast E.) */
+  // test for Ethernet link (assume Fast E.)
   if ((spd < 9.5) && (spd > 3.0) && ((s2cspd/1000) < 9.5) &&
       (loss2 < .01) && (oo_order < .035) && (link > 0))
     link = 10;

-  /* test for wireless link */
+  // test for wireless link
   if ((sendtime == 0) && (spd < 5) && (bw2 > 50) &&
       ((SndLimTransRwin/SndLimTransCwnd) == 1) &&
       (rwintime > .90) && (link > 0))
     link = 3;

-  /* test for DSL/Cable modem link */
+  // test for DSL/Cable modem link
   if ((SndLimTimeSender < 600) && (SndLimTransSender == 0) && (spd < 2) &&
       (spd < bw2) && (link > 0))
     link = 2;

+  // full/half link duplex setting heuristic:
+  // receiver-limited- time > 95%,
+  //  .. number of transitions into the 'Receiver Limited' state is  
greater than 30 ps
+  //  ...and the number of transitions into the 'Sender Limited' state is  
greater than 30 per second
+
   if ((rwintime > .95) && (SndLimTransRwin/timesec > 30) &&
       (SndLimTransSender/timesec > 30))
     half_duplex = 1;

+  // congestion detection heuristic
+  // ..Congestion-limited time share > 2%,
+  // ...no duplex mismatch ,
+  // ....max window advt received is > max congestion window used during  
Slow Start
   if ((cwndtime > .02) && (mismatch == 0) && ((cwin/rttsec) <  
(rwin/rttsec)))
     congestion = 1;

+  // Send results and variable values to clients
   sprintf(buff, "c2sData: %d\nc2sAck: %d\ns2cData: %d\ns2cAck: %d\n",
       c2sdata, c2sack, s2cdata, s2cack);
   send_msg(ctlsockfd, MSG_RESULTS, buff, strlen(buff));
@@ -1194,8 +1317,10 @@
   sprintf(buff, "minCWNDpeak: %d\nmaxCWNDpeak: %d\nCWNDpeaks: %d\n",  
peaks.min, peaks.max, peaks.amount);
   send_msg(ctlsockfd, MSG_RESULTS, buff, strlen(buff));

+  // Signal end of test results to client
   send_msg(ctlsockfd, MSG_LOGOUT, "", 0);

+  // Copy collected values into the meta data structures
     sprintf(meta.date, "%s", get_ISOtime(isoTime));
     memcpy(meta.client_ip, rmt_host, strlen(rmt_host));
     memset(tmpstr, 0, 255);
@@ -1227,6 +1352,7 @@
     strncat(meta.summary, tmpstr, strlen(tmpstr));
     writeMeta(options.compress, cputime, options.snaplog, dumptrace);

+   // Write into log files, DB
   fp = fopen(get_logfile(),"a");
   if (fp == NULL) {
     log_println(0, "Unable to open log file '%s', continuing on without  
logging", get_logfile());
@@ -1281,6 +1407,9 @@
     closelog();
     log_println(4, "%s", logstr1);
   }
+
+  // close resources
+
   if (testopt->s2copt) {
     close(testopt->s2csockfd);
   }
@@ -1303,6 +1432,11 @@
   return (0);
 }

+/**
+ * main method
+ * @param argc Number of arguments
+ * @param argv string command line arguments
+ * */
 int
 main(int argc, char** argv)
 {
@@ -1376,25 +1510,26 @@
     }
   }

+  // Initialize logging system, and then read configuration
   log_init(argv[0], debug);

   if (ConfigFileName == NULL)
     ConfigFileName = CONFIGFILE;

-  /*
-   * Load Config file.
-   * lbuf/lbuf_max keep track of a dynamically grown "line" buffer.
-   * (It is grown using realloc.)
-   * This will be used throughout all the config file reading and
-   * should be free'd once all config files have been read.
-   */
+  // Load Config file.
+  // lbuf/lbuf_max keep track of a dynamically grown "line" buffer.
+  // (It is grown using realloc.)
+  // This will be used throughout all the config file reading and
+  // should be free'd once all config files have been read.

   opterr =  optind = 1;
   LoadConfig(argv[0], &lbuf, &lbuf_max);
   debug = 0;

+  // Get server execution options
   while ((c = getopt_long(argc, argv,
-           
GETOPT_LONG_INET6(GETOPT_LONG_EXP("adhmoqrstvzc:x:b:f:i:l:p:T:A:S:")),  
long_options, 0)) != -1) {
+         //  
GETOPT_LONG_INET6(GETOPT_LONG_EXP("adhmoqrstvzc:x:b:f:i:l:p:T:A:S:")),  
long_options, 0)) != -1) {
+		   
GETOPT_LONG_INET6(GETOPT_LONG_EXP("adhmoqrstvzc:x:b:f:i:l:u:p:T:A:S:")),  
long_options, 0)) != -1) { //kk changed for protocol validation
     switch (c) {
       case '4':
         conn_options |= OPT_IPV4_ONLY;
@@ -1414,6 +1549,7 @@
         break;
       case 'p':
         port = optarg;
+
         if (check_int(port, &testopt.mainport)) {
           char tmpText[200];
           snprintf(tmpText, 200, "Invalid primary port number: %s",  
optarg);
@@ -1453,6 +1589,9 @@
       case 'l':
         set_logfile(optarg);
         break;
+      case 'u': //kk addedd case for protocol validation
+              set_protologfile(optarg);
+              break;
       case 'o':
         old_mismatch = 1;
         break;
@@ -1548,10 +1687,10 @@

   testopt.multiple = multiple;

-  /* First check to see if program is running as root.  If not, then warn
-   * the user that link type detection is suspect.  Then downgrade  
effective
-   * userid to non-root user until needed.
-   */
+  // First check to see if program is running as root.  If not, then warn
+  // the user that link type detection is suspect.  Then downgrade  
effective
+  // userid to non-root user until needed.
+
   if (getuid() != 0) {
     log_print(0, "Warning: This program must be run as root to enable the  
Link Type");
     log_println(0, " detection algorithm.\nContinuing execution without  
this algorithm");
@@ -1607,9 +1746,9 @@
   memset(&new, 0, sizeof(new));
   new.sa_handler = cleanup;

-  /* Grab all signals and run them through my cleanup routine.  2/24/05 */
-  /* sigemptyset(&newmask);
-   * sigemptyset(&oldmask); */
+  // Grab all signals and run them through my cleanup routine.  2/24/05 */
+  // sigemptyset(&newmask);
+  // sigemptyset(&oldmask);
   for (i=1; i<32; i++) {
     if ((i == SIGKILL) || (i == SIGSTOP))
       continue;    /* these signals can't be caught */
@@ -1617,9 +1756,9 @@
     /* sigaddset(&newmask, i); */
   }

-  /*
-   * Bind our local address so that the client can send to us.
-   */
+
+  // Bind our local address so that the client can send to us.
+
   if (srcname && !(listenaddr = I2AddrByNode(get_errhandle(), srcname))) {
     err_sys("server: Invalid source address specified");
   }
@@ -1631,25 +1770,25 @@

   log_println(1, "server ready on port %s", port);

-  /* Initialize Web100 structures */
+  // Initialize Web100 structures
   count_vars = web100_init(VarFileName);
   if (count_vars == -1) {
     log_println(0, "No web100 variables file found, terminating program");
     exit (-5);
   }

-  /* The administrator view automatically generates a usage page for the
-   * NDT server.  This page is then accessable to the general public.
-   * At this point read the existing log file and generate the necessary
-   * data.  This data is then updated at the end of each test.
-   * RAC 11/28/03
-   */
+       //   The administrator view automatically generates a usage page for 
the
+       //    NDT server.  This page is then accessible to the general public.
+       //    At this point read the existing log file and generate the 
necessary
+       //    data.  This data is then updated at the end of each test.
+       //    RAC 11/28/03
+
   if (admin_view == 1)
     view_init(refresh);

-  /* Get the server's metadata info (OS name and kernel version
-   * RAC 7/7/09
-   */
+  // Get the server's metadata info (OS name and kernel version
+  // RAC 7/7/09
+
   if ((fp = fopen("/proc/sys/kernel/hostname", "r")) == NULL)
     log_println(0, "Unable to determine server Hostname.");
   else {
@@ -1664,7 +1803,8 @@
   }


-  /* create a log file entry every time the web100srv process starts up. */
+  // create a log file entry every time the web100srv process starts up
+
   ndtpid = getpid();
   tt = time(0);
   log_println(6, "NDT server (v%s) proces [%d] started at %15.15s",  
VERSION, ndtpid, ctime(&tt)+4);
@@ -1681,26 +1821,23 @@
     syslog(LOG_FACILITY|LOG_INFO, "Web100srv (ver %s) process started",
         VERSION);

-  /* scan through the interface device list and get the names/speeds of  
each
-   * if.  The speed data can be used to cap the search for the bottleneck  
link
-   * capacity.  The intent is to reduce the impact of interrupt coalescing  
on
-   * the bottleneck link detection algorithm
-   * RAC 7/14/09
-   */
+  // scan through the interface device list and get the names/speeds of  
each
+  //  if.  The speed data can be used to cap the search for the bottleneck  
link
+  //  capacity.  The intent is to reduce the impact of interrupt  
coalescing on
+  //  the bottleneck link detection algorithm
+  //  RAC 7/14/09
+
   get_iflist();

   for (i=0; iflist.speed[i]>0; i++)
      log_println(4, "Generated iflist with device=%s and if_speed=%d",  
iflist.name[i], iflist.speed[i]);

-  /*
-   * Wait at accept() for a new connection from a client process.
-   */
-
-  /* These 2 flags keep track of running processes.  The 'testing' flag
-   * indicated a test is currently being performed.  The 'waiting' counter
-   * shows how many tests are pending.
-   * Rich Carlson 3/11/04
-   */
+  // Wait at accept() for a new connection from a client process.
+
+  // These 2 flags keep track of running processes.  The 'testing' flag
+  //  indicates a test is currently being performed.  The 'waiting' counter
+  //  shows how many tests are pending.
+  //  Rich Carlson 3/11/04

   options.compress = compress;
   testing = 0;
@@ -1723,7 +1860,7 @@
       log_println(3, "Queue pointer=%d, testing=%d, waiting=%d,  
mclients=%d, zombie_check=%d",
                head_ptr->pid, testing, waiting, mclients, zombie_check);

-    /* moved condition from interrupt handler to here */
+    // moved condition from interrupt handler to here
     /* if ((sig1 > 0) || (sig2 > 0))
      *         check_signal_flags;
      */
@@ -1740,16 +1877,16 @@
     }

     if ((multiple == 1) && (mclients < max_clients) && (waiting >=  
max_clients)) {
-	/* this condition means that there are clients waiting and there are open  
slots
-        * in the test queue, so dispatch another client.
-        * RAC 12/11/09
-        */
+	// This condition means that there are clients waiting and there are open  
slots
+       //   in the test queue, so dispatch another client.
+       //   RAC 12/11/09
+
        log_println(5, "Empty slot in test queue, find new client to 
dispatch");
        /* tmp_ptr = head_ptr; */
        mchild = head_ptr;
        i = 0;
        while (mchild != NULL) {
-          i++;   /* Keep count of how many times we go through this loop */
+          i++;   // Keep count of how many times we go through this loop
 	   log_println(2, "walking queue look for non-running client current=%d,  
running=%d, next=0x%x",
                        mchild->pid, mchild->running, mchild->next);
            if (mchild->running == 0) {
@@ -1770,11 +1907,11 @@
         * if (mchild != head_ptr) {
         */
          tmp_ptr = mchild;
-         /* update queued clients, send message to client when it moves
-          * up in the queue enough to get closer to running a test.  This 
happens
-          * when the client falls into the next lower maxquee bin
-          * RAC 3/21/10
-          */
+         // Update queued clients, send message to client when it moves
+	  //  up in the queue enough to get closer to running a test.  This  
happens
+         //  when the client falls into the next lower maxquee bin
+         //  RAC 3/21/10
+
          int rac;
          if (waiting > (2*max_clients)) {
            for (i=max_clients; i<=waiting; i++) {
@@ -1800,7 +1937,7 @@
 	log_println(6, "Fault: Negative number of clents waiting=%d, mclients=%d,  
nuke them", waiting, mclients);
        while (head_ptr != NULL) {
             /* send_msg(head_ptr->ctlsockfd, SRV_QUEUE, "9933", 4); */
-            send_msg(head_ptr->ctlsockfd, SRV_QUEUE, "9988", 4);
+            send_msg(head_ptr->ctlsockfd, SRV_QUEUE, "9988", 4); // TODO  
constants
            shutdown(head_ptr->ctlsockfd, SHUT_WR);
            close(head_ptr->ctlsockfd);
             tpid = head_ptr->pid;
@@ -1831,21 +1968,19 @@
     }

     if (head_ptr != NULL) {
-        if ((time(0) - head_ptr->stime) > 70)  {
+        if ((time(0) - head_ptr->stime) > 70)  { // TODO: 70 =>  
WAIT_TIME-THRESH
 	    log_println(6, "Fault: Something in queue, but child %d (fd=%d) has  
exceeded wait time",
                        head_ptr->pid, head_ptr->ctlsockfd);
-           /* Should send new 9977 'test aborted' signal to client.  Using 
this
-            * for now.
-            *
-            * rac 3/26/10
-            */
+	    // Should send new 9977 'test aborted' signal to client.  Using this  
for now
+           // rac 3/26/10
+
             log_println(6, "pid=%d, client='%s', stime=%ld, qtime=%ld  
now=%ld", head_ptr->pid, head_ptr->addr,
                         head_ptr->stime, head_ptr->qtime, time(0));
 	    log_println(6, "pipe-fd=%d, running=%d, ctlsockfd=%d, client-type=%d,  
tests='%s'",
                        head_ptr->pipe, head_ptr->running, 
head_ptr->ctlsockfd,
                        head_ptr->oldclient, head_ptr->tests);
             /* send_msg(head_ptr->ctlsockfd, SRV_QUEUE, "9966", 4); */
-            send_msg(head_ptr->ctlsockfd, SRV_QUEUE, "9988", 4);
+            send_msg(head_ptr->ctlsockfd, SRV_QUEUE, "9988", 4); // boot  
the client
            shutdown(head_ptr->ctlsockfd, SHUT_WR);
            close(head_ptr->ctlsockfd);
             tpid = head_ptr->pid;
@@ -1867,35 +2002,35 @@

     FD_ZERO(&rfd);
     FD_SET(listenfd, &rfd);
-    if (waiting > 0) {
-      sel_tv.tv_sec = 3;
+    if (waiting > 0) { // there are clients waiting
+      sel_tv.tv_sec = 3; // todo 3 seconds == WAIT_TIME_SRVR
       sel_tv.tv_usec = 0;
       log_println(3, "Waiting for new connection, timer running");
 sel_11:
       rc = select(listenfd+1, &rfd, NULL, NULL, &sel_tv);
       if ((rc == -1) && (errno == EINTR))
-	/* continue; */  /* a signal caused the select() to exit, re-enter loop &  
check */
+	/* continue; */  // a signal caused the select() to exit, re-enter loop &  
check
        goto sel_11;
       tt = time(0);

     }
     else {
-	/* Nothing is in the queue, so wait forever until a new connection  
request arrives */
+	  // Nothing is in the queue, so wait forever until a new connection  
request arrives
       log_println(3, "Timer not running, waiting for new connection");
       mclients = 0;
 sel_12:
       rc = select(listenfd+1, &rfd, NULL, NULL, NULL);
       if ((rc == -1) && (errno == EINTR))
-	goto sel_12;  /* a signal caused the select() to exit, re-enter loop &  
check */
+	goto sel_12;  // a signal caused the select() to exit, re-enter loop &  
check
     }

     if (rc < 0) {
-	/* an interrupt or signal caused the select() to exit, go back and start  
over */
+      // an interrupt or signal caused the select() to exit, go back and  
start over
       log_println(5, "Select exited with rc = %d", rc);
       continue;
     }

-    if (rc == 0) {    /* select exited due to timer expired */
+    if (rc == 0) {    // select exited due to timer expiration
       log_println(3, "Timer expired while waiting for a new connection");
       /* if ((waiting > 0) && (testing == 0)) */
       if (multiple == 0) {
@@ -1909,7 +2044,7 @@
       }
     } else {
         log_println(3, "New connection received, waiting for accept() to  
complete");
-        if ((waiting > 0) && (testing == 0))
+        if ((waiting > 0) && (testing == 0))  // no clients waiting, no  
test in progress
           goto ChldRdy;
       /* } */
       clilen = sizeof(cli_addr);
@@ -1927,32 +2062,32 @@
        ctlsockfd = 0;
         ctlsockfd = accept(listenfd, (struct sockaddr *) &cli_addr,  
&clilen);
         if ((ctlsockfd == -1) && (errno == EINTR))
-            continue; /*sig child */
+            continue; // sig child
         size_t tmpstrlen = sizeof(tmpstr);
        memset(tmpstr, 0, tmpstrlen);
+               // get addr details based on socket info available
         I2Addr tmp_addr = I2AddrBySockFD(get_errhandle(), ctlsockfd,  
False);
         I2AddrNodeName(tmp_addr, tmpstr, &tmpstrlen);
         /* I2AddrFree(tmp_addr); */
         log_println(4, "New connection received from 0x%x [%s]  
sockfd=%d.", tmp_addr, tmpstr, ctlsockfd);
        break;
       }
-      /* verify that accept really worked and don't process connections  
that hav
-       * failed
-       * RAC 2/11/10
-       */
+
+      // verify that accept really worked and don't process connections  
that've failed
+      // RAC 2/11/10
       if (ctlsockfd <= 0) {
         log_println(4, "New connection request failed sockfd=%d  
reason-%d.", ctlsockfd, errno);
        continue;
       }

-      /* the specially crafted data that kicks off the old clients */
-      for (i=0; i<5; i++) {
+      // the specially crafted data that kicks off the old clients
+      for (i=0; i<5; i++) { // todo 5==SOCKET_IO_RETRY_COUNT
         rc = write(ctlsockfd, "123456 654321", 13);
-       if ((rc == -1) && (errno == EINTR))
+       if ((rc == -1) && (errno == EINTR)) // interrupted, retyr
          continue;
-       if (rc == 13)
+       if (rc == 13) // 13 bytes correctly written, exit
          break;
-       if (rc == -1) {
+       if (rc == -1) { // socket error hindering further retries
          log_println(1, "Initial contact with client failed errno=%d", 
errno);
           close(chld_pipe[0]);
           close(chld_pipe[1]);
@@ -1979,15 +2114,15 @@
       name = tmpstr;
       rmt_host = tmpstr;

-      /* At this point we have received a connection from a client,  
meaning that
-       * a test is being requested.  At this point we should apply any  
policy
-       * or AAA functions to the incoming connection.  If we don't like the
-       * client, we can refuse the connection and loop back to the  
begining.
-       * There would need to be some additional logic installed if this AAA
-       * test relied on more than the client's IP address.  The client  
would
-       * also require modification to allow more credentials to be  
created/passed
-       * between the user and this application.
-       */
+      // At this point we have received a connection from a client,  
meaning that
+      //  a test is being requested.  At this point we should apply any  
policy
+      //  or AAA functions to the incoming connection.  If we don't like  
the
+      //  client, we can refuse the connection and loop back to the  
begining.
+      //  There would need to be some additional logic installed if this  
AAA
+      //  test relied on more than the client's IP address.  The client  
would
+      //  also require modification to allow more credentials to be  
created/passed
+      //  between the user and this application.
+
     }

     if (pipe(chld_pipe) == -1)
@@ -1997,25 +2132,25 @@
     switch (chld_pid) {
       case -1:    /* an error occured, log it and quit */
         log_println(0, "fork() failed, errno = %d", errno);
-       /* todo: handle error and continue */
+        /* todo: handle error and continue */
         break;
-      default:    /* this is the parent process, handle scheduling and
-                   * queuing of multiple incoming clients
-                   */
+      default:    // this is the parent process, handle scheduling and
+                  // queuing of multiple incoming clients
+
         log_println(5, "Parent process spawned child = %d", chld_pid);
         log_println(5, "Parent thinks pipe() returned fd0=%d, fd1=%d",  
chld_pipe[0], chld_pipe[1]);

          close(chld_pipe[0]);

-        /* Check to see if we have more than max_clients waiting in the  
queue
-         * If so, tell them to go away.
-         * changed for M-Lab deployment  1/28/09  RAC
-         */
+        // Check to see if we have more than max_clients waiting in the  
queue
+        //  If so, tell them to go away.
+        //  changed for M-Lab deployment  1/28/09  RAC
+
         if (((multiple == 0) && (waiting >= (max_clients-1))) ||
                ((multiple == 1) && (waiting >= ((4*max_clients)-1)))) {
           log_println(0, "Too many clients/mclients (%d) waiting to be  
served, Please try again later.",
                        chld_pid);
-          sprintf(tmpstr, "9988");
+          sprintf(tmpstr, "9988");  //TODO 9988= server_BUSY_OR_ERROR
           send_msg(ctlsockfd, SRV_QUEUE, tmpstr, strlen(tmpstr));
           close(chld_pipe[0]);
           close(chld_pipe[1]);
@@ -2030,7 +2165,7 @@
         }

        t_opts = initialize_tests(ctlsockfd, &testopt, test_suite);
-       if (t_opts < 1) {
+       if (t_opts < 1) { // some error in initialization routines
 	    log_println(3, "Invalid test suite string '%s' received, terminate  
child", test_suite);
             close(chld_pipe[0]);
             close(chld_pipe[1]);
@@ -2043,7 +2178,7 @@
            }
            continue;
        }
-        while ((rc = sem_wait(&ndtq)) == -1 && errno == EINTR) {
+        while ((rc = sem_wait(&ndtq)) == -1 && errno == EINTR) { // socket  
interrupt, retry
          log_println(6, "Waiting for ndtq semaphore to free - 1");
           continue;
         }
@@ -2052,6 +2187,9 @@
         new_child->pid = chld_pid;
         strncpy(new_child->addr, rmt_host, strlen(rmt_host));
         strncpy(new_child->host, name, strlen(name));
+
+        // compute start time based in the number of waiting clients
+        // set other properties on this child process
        if (multiple == 0)
             new_child->stime = tt + (waiting*45);
        else
@@ -2061,7 +2199,7 @@
        new_child->running = 0;
         new_child->ctlsockfd = ctlsockfd;
        if (t_opts & TEST_STATUS)
-           new_child->oldclient = 1;
+           new_child->oldclient = 1; //todo what does oldclient mean?
        else
            new_child->oldclient = 0;
        memset(new_child->tests, 0, sizeof(test_suite));
@@ -2091,7 +2229,7 @@
           continue;
         }

-        waiting++;
+        waiting++; // new client has arrived and is queue-able. increment  
waiting
         log_println(5, "Incrementing waiting variable now = %d", waiting);
         if (head_ptr == NULL)
           head_ptr = new_child;
@@ -2122,11 +2260,11 @@
           }
         }

-        /* At this point send a message to the client via the ctlsockfd
-         * saying that N clients are waiting in the queue & testing will
-         * begin within Nx60 seconds.  Only if (waiting > 0)
-         * Clients who leave will be handled in the run_test routine.
-         */
+        // At this point send a message to the client via the ctlsockfd
***The diff for this file has been truncated for email.***
=======================================
--- /branches/kkumar_code_organize/src/web100srv.h      Sun Mar 21 11:04:42 
2010
+++ /branches/kkumar_code_organize/src/web100srv.h      Fri Sep 23 13:50:35 
2011
@@ -77,7 +77,7 @@
 typedef struct options {
     u_int32_t limit;
     int snapDelay;
-    char avoidSndBlockUp;
+    char avoidSndBlockUp; // flag set to indicate avoiding  send buffer  
blocking in the S2C test
     char snaplog;
     char cwndDecrease;
     char s2c_logname[128];
@@ -90,18 +90,19 @@
   int port2;
 } PortPair;

+// Structure defining NDT child process
 struct ndtchild {
-       int pid;
-       char addr[64];
-       char host[256];
-       time_t stime;
-       time_t qtime;
-       int pipe;
-       int running;
-       int ctlsockfd;
-       int oldclient;
-       char tests[16];
-       struct ndtchild *next;
+       int pid;                // process id
+       char addr[64];  // IP Address
+       char host[256]; // Hostname
+       time_t stime;   // estimated start time of test
+       time_t qtime;   // time when queued
+       int pipe;               // writing end of pipe
+       int running;    // Is process running?
+       int ctlsockfd;  // Socket file descriptor
+       int oldclient;  // Is old client?
+       char tests[16]; // What tests are scheduled?
+       struct ndtchild *next; // next process in queue
 };

 struct spdpair {