             MDP Agent for NS-2 Network Simulator
            ======================================
            
    This directory contains files to build the Berkeley ns-2
simulator (4Oct200 Snapshot, ns-21b6, or ns-21b5) with the
capability  to run the MDPv2 protocol.  Source files and an example
script to create appropriate symbolic links for the MDP-enabled
ns-2 build are included.  A number of simulation scripts (tcl) and
utilities to provide post-analysis and visualization of results are
also included.
            
The following files make up this directory:

(Note that you will find some extraneous files as well which are
 temporary files and test scripts and notes of mine created as
 I work on the code and conduct my own simulations.  The distributions
 released aren't always stripped of these sorts of files)

BUILDING AND INSTALLATION FILES

   Makefile.in   - Modified version of ns-2's "Makefile."in with to
                   support above.  (Use ns21b6-Makefile.in or
                   ns21b6-Makefile.in for older release builds)

   packet.h      - Modified version of ns-2's "packet.h" with MDP
                   packet types defined.  (Use ns21b6-packet.h or
                   ns21b6-packet.h for older release builds)

   nsMdpAgent.h  - Header file for ns-2 MDPv2 Agent class
   
   nsMdpAgent.cpp - Implementation file for ns-2 MDPv2 Agent.
   
   patch-ns.sh   - Simple shell script to mod ns-2 source tree
                   for build with MDPv2 Agent.
                   (YOU WILL NEED TO EDIT THIS. (see below))

SCRIPTS

   These are various ns test scripts which use the NS MDP Agent.
   These are located in the "scripts" directory.  There are 
   additional scripts besides those listed here.  Those listed
   here are the ones we will try to maintain.
				 
   simplemdp.tcl - Example ns-2 script using "Agent/MDP" with one
                   server and a configurable number of clients
                   
   mdpvstcp.tcl  - Relatively simple script for constructing
                   simulations  of MDP flows (w/ congestion control)
                   competing with TCP flows for bandwidth on a
                   topology with a single bottleneck link. (One
                   server & one client per MDP flow)
                   
   multi-mdpvstcp.tcl  - Variation of "mdpvstcp.tcl" with multiple
                         clients per MDP flow.
                         
   mcc.tcl       - Similar to "mdpvstcp.tcl" but also has option
                   to use ACIRI's TFRC agent competing along-side
                   optional MDP & TCP flows
                         
   cbrvstcp.tcl  - Simulation depicting TCP's performance in the
                   presence of constant bit rate (cbr) flow.
                   
   rmcc          - Directory containing more complex scripts for
                   evaluating MDP (or potentially other) multicast
                   congestion control over topologies with multiple
                   bottlenecks and multiple, possibly time-varying
                   TCP flows.

PLOT-TOOLS
                   
   rateplot.cpp, lossplot.cpp, lpplot.cpp, repplot.cpp 
                 - These are utility programs for post-processing
                   ns-2 (and sometimes MDP's own) trace/log files.
                   (We generally use Gnuplot and these programs will
                   generate data files with headers Gnuplot can
                   load)
                   
   Here is a series of Gnuplot scripts which plot data from
   an MDP debug log file name "mdpLog.txt" which is created
   when many of the scripts above are run.  These files
   create graphs which plot a single MDP congestion control
   server's (or in some case single client) specific or set
   of data which play a role in MDP's congestion control 
   mechanism.  The idea is to use these graphs to determine
   the reasons for the congestion control algorithms
   behavior under certain circumstances. For the most part,
   these scripts should be run with a single server or in
   some cases a single client.  
   
   (Your simulation script can turn MDP logging on/off and 
   direct logging to a specific file (or stdout by default))
   
   These Gnuplot scripts are:
                   
   rate.gp  - Plots the MDP server's current transmit rates:
              TCP Analytical Model rate, actual tx rate,
   
   loss.gp  - Plots the current loss estimate the MDP server
              is using in determining its rate.  This is the
              loss reported by the current "bottleneck"
              representative.
   
   rtt.gp   - Plots the current rtt and rtt deviation estimate 
              the MDP server is using in determining its rate.  
              This is the loss reported by the current "bottleneck" 
              representative.

   li.gp    - Plots the receiver estimates of the current "loss
              interval" (1/loss rate).  Plots lines include
              Actual interval, old MDP interval estimate,
              ACIRI TFRC-link estimate.
                              

Requirements:

  gcc compiler (Version 2.7.2 or later), NS 2.1b5 
  
  gnuplot for many of the graphs.

INSTALLATION INSTRUCTIONS
=============================

0) Extract this stuff.

1) Get NS.  We recommend getting ns-allinone from 
      http://www-mash.CS.Berkeley.EDU/ns/ns-build.html#allinone

   (Currently, it is ns-2.1b6)

2) Check and fix NS bugs:
     http://www-mash.CS.Berkeley.EDU/ns/ns-problems.html

3) (Optional) You might try to install NS and play with the demo

4) Modify the script "patch-ns.sh" in this directory.  Edit NS_PREFIX_DIR
   to where you  place your ns distribution.  (mine is in
   "/home/adamson/ns2/ns-allinone-2.1b6/")

5)  Run "patch-ns.sh", it will create symbolic links from NS directories
    to MDP.  "patch-ns.sh" will also replace some NS files, e.g.
    Makefile.in with our version.  See the detail in "patch-ns.sh" for
    what files have to be linked/replaced.

6) If you skipped step 3: (you'll have to build all components)
   ---------------------
     cd $NS_PREFIX_DIR 
     ./install

   If you did not skip step 3: (you'll simply rebuild certain components)
   --------------------------
     cd $NS_PREFIX_DIR/ns-2
	 configure
	 make clean (although a "make depend" _might_ do)
     make ns
      
7) Run ns with our script

   cd $NS_PREFIX_DIR
   ns ~/NS-MDP/SRC/simple-mcast.tcl

------------------------------------------------------------------------------------
NOTES:
=====

 This adaptation of MDPv2 code for NS usees the following approach:

 The "UdpSocket" class used by MDPv2 (and incidentally some other
 apps I've written) relies on underlying operating system support
 related to a "socket".  Operating systems supply calls for
 sending/receiving packets, joining/leaving multicast groups,
 setting the multicast ttl, etc.  So for simulation purposes, the
 file "simUdpSocket.cpp" allows for simulation agents (ns-2, OPNET,
 or maybe eventually other) to provide these behaviors. Note that
 the "NetworkAddress" class MDPv2 uses contains built-in support for
 address conventions used in the ns-2 and OPNET simulators.

 The simUdpSocket class relies on the "NsMdpAgent" to provide those
 functions (and maintain state for them).  Since the "Agent" class
 is central to the instantiation of a  "typical" ns-2 simultation
 entity (and a certain amount of functionality is provided to
 support "Agent" configuration from ns-2 Tcl scripts), the
 NsMdpAgent class is designed to correspond to a single MDPv2
 application instantiation.

 This current starter implementation only provides for one
 NsUdpSocket per NsMdpAgent, thus we will be limited to one
 MdpSession per NsMdpAgent when this first cut of the code is
 complete. However, it would be easy to extend the NsMdpAgent to
 support more than one NsUdpSocket and that may be accomplished at
 some point.  This point may become academic however as it will be
 possible to have multiple NsMdpAgents per ns-2 Node anyway.
 
Authors:
========
  Brian Adamson (Newlink) 
  Joe Macker (NRL) 
  Apinun Tunpan (ISR) University of Maryland College Park 
  Scott Corson (ISR) University of Maryland College Park
  Josh Day (NRL/WVU)
  Ian Downard (NRL)
  
  The code is considered experimental and subject to changes.  At
this time, all distributions to other party than our working group
must be approved by the authors.
  
Credits:
========

  MDPv2 is the work of
    Joe Macker (NRL) <macker@itd.nrl.navy.mil> and
    Brian Adamson (Newlink) <adamson@itd.nrl.navy.mil>

  NS version 2 is the work of UCB/LBNL/VINT

Last Updated:  12 October 2000
 
