BASICS
======

GLOBAL SCHEDULER (src/mmsched)

The global scheduler is implemented in C (in media-net/mmsched/):

./schedsvr [-p port] [-h hostname] [-c config] [-f BRITE.config.file] [-u user db] [-e]
  -p port       HTTP port for config specs (def=7777)
  -h host       address to send reports to (def=localhost)
  -u db name of user database (def=users.db)
  -c config     network configuration number (def=3)
  -f BRITE network description file (def=)
  -e treat links as addresses and send to them

for example, ./schedsvr -f outbritefile for a BRITE topology or
             ./schedsvr -c 4 for the built-in diamond configuration

The -c option defines "built-in" configurations.  These are defined at the
top of mmsched/mmsched.c.  The struct definitions for the various
datastructures are in mmsched/mmsched.h.  For more information on BRITE and
its network configuration files, see http://www.cs.bu.edu/brite/.

More information on the global scheduler can be found in the README file in
that directory.

LOCAL SCHEDULER (src/lsched)

The local scheduler is implemented in Cyclone (in media-net/):

medianet [-p portnum] [-s specfile] [-q sendQsize]

where portnum is the port to listen for HTTP connections on,
specifile is the XML description of the computations to run, and sendQsize
is the size of the outgoing queue for each send operation.  A number of
sample configurations are in src/lsched/configs.

By default, portnum is 80, specfile is none, and sendQsize is 8.

When using the local scheduler with the global scheduler, you should not
specify the -s argument.  Instead, the global scheduler will connect on the
web interface and provide the configuration.  To use the web interface
manually, point your browser at the HTTP port with target "config" as

http://hostname:7771/config

where 7771 is the portnum you started medianet with, and hostname is the
name of the machine it's running on.

SENDING/RECEIVING APPLICATIONS (src/apps)

receiver: This is a simple program for connecting to MediaNet, which prints
  out the text of any packets it receives.  Usage:

  ./receiver [-d] [-u] [port]
    -d disconnect on port close
    -u use UDP (default is TCP)
    default port=5000

  The port given is the one to listen on for connections (in the case of
  TCP) or packets (for UDP).

sender: This allows you to type in a line of text, which gets turned into a
  packet and is sent into MediaNet.  Usage:

  ./sender [-s n sz d] [-u] [host port]
    -s n sz   send n generated buffers of sz bytes, n>0, 0<sz<65535,
                with d busy-waiting iterations between sends
    -u        use UDP (default is TCP)
    default port=5000 host=localhost

  You can connect the sender to the receiver application directly, or
  connect to MediaNet and have them communicate through it.

tracereceiver: This is a receiver of MPEG video streams, that prints output
  statistics based on the frames it receives.  Usage:

    ./tracereceiver [port]

  The port is the TCP port to listen on.  If not port is provided, 5000 is
  used. The output is going to be one or more lines of the following form:

    seq N size B time T b/w BW FT REF STATUS

  where
   N is the frame sequence number (we added, not MPEG)
   B is the size of the frame in bytes
   T is the time the frame was received, relative to the first frame
     arriving
   BW is the current bandwidth at the time the frame was received, as
     averaged over the last second.
   FT frame type (either I, P, B or G, which is the GOP header)
   REF is the temporal reference of the frame (MPEG indicator)
   STATUS is either OK or BAD, depending on whether the decode would work

  There are some scripts in the media-net/scripts/ directory that process
  this output to generate graphs as shown in the paper.

mpgsender/mpgsender: This is program that takes a MPEG-2 video file,
  separates it into packets, one per frame, and sends it into MediaNet.
  These packets can be processed by tracereceiver, as described above.
  Usage:

    mpgsender hostname port mpgfile BPseq [num repeats]

  Here hostname and port are the host and port to connect to (via TCP), and
  mpgfile is the MPEG file to stream along the connection.  BPseq is a
  series of three flags which indicate whether or not to drop B frames, drop
  P frames, and include a sequence number per frame.  So if for this option
  you did 110, you would be dropping both P and B frames, and not including
  sequence numbers, while if you did 001 (recommended), you would not drop
  any frames and would add sequence numbers.  Tracereceiver needs sequence
  numbers added to work properly.

ttcp/ttcp: This is a modified version of the well-known TTCP program to work
  properly with MediaNet.  See the README in that directory for more
  information.

PRACTICAL USAGE
===============

There are a bunch of scripts you can use to start things up.  These are
largely generic, just assuming you have ssh installed, but also have parts
specific to Emulab (see http://www.emulab.net).

  media-net/scripts/bowtie.sh: starts/stops 8 medianet nodes on different
    machines, each on the same port (7771).  It does this by ssh'ing to
    those machines, and invoking the startLS/stopLS script there.  bowtie.sh
    is specific to the emulab topology we used, so it will have to be
    changed to work with a different set of nodes; startLS and stopLs should
    be fine as is.  Use the script as

    bowtie.sh start

    or

    bowtie.sh stop

  media-net/scripts/{startGS,stopGS}: similarly start and stop the global
    scheduler.  It should be run on the machine that you want the global
    scheduler running on.

  media-net/mmsched/mn_config: this sends a user configuration to the global
    scheduler, which then configures the local media-net nodes with its
    computed schedule.  Takes two parameters:

    ./mn_config user specfile host [x=just-init]

    where user should be either mike or rvr (assuming you're using the
    users.db in media-net/mmsched), and specfile will be an XML global
    configuration file; some examples are in the media-net/scripts/*
    directories, and in the media-net/mmsched/specs directory.  One used
    in the paper is MPEGpriotrace.xml; so

    ./mn_config mike specs/MPEGpriotrace.xml

    would start the paper setup.

  media-net/scripts/startsender: this starts up the video sender that will
    connect to media-net.  The script should be run on the host of the
    MediaNet "entry-point;" that is, on the host whose MediaNet server
    should be directly connected to.  This uses the
    media-net/src/apps/mpgsender/mpgsender.exe program to stream the video.
    Usage:

   ./startsender port

   where port is the port that the local MediaNet local server is waiting to
   receive on (i.e. it has a recv operation listening on that port).

  media-net/scripts/stopsender: the dual of startsender.  You need to
    specify the same port number that you started it with, and run it on the
    same machine.

  media-net/scripts/starttrace: this starts the tracereceiver program,
    described above, for receiving video streams.  Like the
    video sender, it should be run on the machine that runs the local server
    it directly connects to:

    ./starttrace port

    where port is the name of the port to listen on, to be connected to by a
    send connection running on the local server.  

  media-net/scripts/stopstrace: stops the trace program, as stopsender,
    above.

  media-net/scripts/doexp.sh: this combines the above scripts to create test
    scenarios.  It should be run from the same directory as a test
    description file, passed to stdin, e.g.

    cd scripts/LineGlobal; ./doexp.sh < EXP

    (This assumes that doexp.sh is symlinked to be in this directory, which
    it is not on a fresh checkout of CVS.)  The test scenarios describe the
    events that are to take place, and execute the above scripts to make
    them happen.  

    The following description is a bit out of date.  You should look at
    doexp.sh to understand things for sure.  Look at scripts/*/EXP for
    examples.

    Here are the basic commands.  For example:

0 STARTUP Diamond 5 localhost

    at time 0, start running everything (i.e. the global scheduler and the
    local schedulers), and use the "Diamond" configuration (-c 4 for GS and
    ./diamond.sh for the local schedulers).  An alternative is "line" for
    just two nodes connected to each other, or "y" for nodes connected in a
    Y pattern (one sender and two receivers).

2 CONFIG rvr mmsched/specs/MPEGtrace.xml

    at time 2, configure with the MPEGtrace.xml file, using mn_config.

2 START 5001 5000

    at time 2, start the video on ports 5001, 5000

17 BW 7771 link1 100000

    at time 17, change the bandwidth on link1 to be 100000

32 BW 7771 link3 100000
47 BW 7771 link3 50000
62 BW 7771 link1 50000
77 BW 7771 link3 180000
102 BW 7771 link1 100000
117 STOP 5001 5000

   stop the video

122 SHUTDOWN diamond

   end the experiment.

   For some reason you also have to manually kill the global scheduler (ps
   and look for schedsvr and kill it).

