README for ~clark/dirt/tools/xplot/ directory   	Michele Clark  8/11/98
=============================================

Switches common to all tools:
-----------------------------
-dump: 	ascii file of statistics 
-out: 	xplot file to generate
-g:    	turn debugging info on  (maybe not used in all...)

Notes:
------
o Executables compiled for FreeBSD are in ~clark/dirt/tools/FreeBSD/
o Input file must include packet recv timestamp, packet sent timestamp, 
  sequence number, and # of bytes in packet
o Input file format is currently for data from the nanoManipulator
o To customize for different input file formats, change fscanf() line
o For how to re-compile, look at ~clark/dirt/tools/xplot/Makefile

consecLossPlot.c	  consecutive packets lost vs. time of detection
----------------
  - No Additional Switches
  - Plots:
	o red dot         -- # consecutive packets lost
	o yellow dot at 0 -- out-of-order


deltaPlot.c	(recv delta - send delta) vs. receive time
-----------
  - Additional Switches:
	-a: calculate abs (recv delta - send delta)
	-f: plot per frame, not per packet
	-s: calculate sum (delta0, delta1, ...)
	-z: same as -s, but set sum := 0, when sum < 0
  - Formulas:
        o recvDelta = recvTimePacket2 - recvTimePacket1  (adj packets only) 
	o sendDelta = sendTimePacket2 - sendTimePacket1  (adj packets only)
	o transit   = recvDelta - sendDelta
	o sum       = sum of transits
  - Plots:
	o green dot -- transit, or sum
	o blue line -- connects adjacent transits, or sums
  - Notes: 
	o Can also be used to plot results of video simulator w/frames 
	  (#define _VIDEO)


diffPlot.c	(receive time - send time) vs. receive time
----------
  - No Additional Switches
  - Formulas:
	o diff = send time - recv time
  - Plots:
	o green dot -- diff


interPlot.c	  receive interval vs. receive time
-----------
  - No Additional Switches
  - Formulas:  
        o recvDelta             = recvTime2 - recvTime1  (adj packets only) 
	o recvDeltaSum          = sum of recvDeltas
	o avg interarrival time = recvDeltaSum / # total packets received
  - Plots:
	o red dot   -- recvDelta
	o blue line -- avg interarrival time


jitterPlot.c	  smoothed interarrival jitter vs. time
------------
  - Additional Switches:
	-f: plot per frame, not per packet	
  - Formulas:
        o recvDelta     = recvTimePacket2 - recvTimePacket1  (adj packets only)
	o sendDelta     = sendTimePacket2 - sendTimePacket1  (adj packets only)
	o instantJitter = recvDelta - sendDelta
	o jitter        = jitter + ((instantJitter - jitter) / 16)
  - Plots:
	o green dot -- jitter
	o blue line -- connects adjacent jitter
	o red dot   -- abs (instantaneous jitter) 
  - Notes: 
	o Can also be used to plot results of video simulator w/frames 
	  (#define _VIDEO)


latencyPlot.c		estimated and normalized latency vs. time
-------------
  - Additional Switches:
	-c: connect the dots
	-f: plot per frame, not per packet	
	-i secs: plot latency in intervals
	-l: turn legend on
	-m: don't output min latency to stderr
	-p: plot packet latencies   [default]
	-s seqNum: seqNum where to cut off data
	-t: read dump file as ascii text
	-z: start y axis at 0
	
  - Formulas:
	o latency     = recvTime - sendTime  
	o min latency = min latency between two packets
	o latency     -= min latency   
  - Plots:
	o green dot -- latency of in-order packet OR complete frame
	o red dot -- latency of packet where lost packets detected OR 
		     incomplete frame
	o blue dot -- latency of ooo packet
	o yellow line -- connect adjacent latencies


lossPercentPlot.c	percentage lost vs. time
------------------
  - No Additional Switches
  - Formulas:
	o lost            = total packets lost
	o percentLost     = lost / # total packets received
	o intervalLost    = lost - lastLost
	o intervalPercent = intervalLost / # interval packets
  - Plots:
	o red dot     -- intervalPercent over 5s interval
	o yellow line -- connect dots
	o blue line   -- percentLost every 5s


normalDeltaPlot.c	normalized (recv delta - send delta) vs. receive time
-----------------
  - Additional Switches:
	-a: calculate abs (recv delta - send delta)
	-s: calculate sum (delta0, delta1, ...)
	-z: same as -s, but set sum := 0, when sum < 0
  - Formulas:
        o recvDelta = recvTimePacket2 - recvTimePacket1  (adj packets only) 
	o sendDelta = sendTimePacket2 - sendTimePacket1  (adj packets only)
	o transit   = recvDelta - sendDelta
	o sum       = sum of transits
	o avg	    = average transit time
	o transit   -= avg
  - Plots:
	o green dot -- transit, or sum
	o blue line -- connects adjacent transits, or sums


pointPlot.c	recv interval vs. time
-----------
  - No Additional Switches
  - Formulas:  
	o recvDelta         = lastRecvTime - recvTime
	o recvDeltaSum      = sum of recvDeltas
	o avg interval time = recvDeltaSum / # total packets sent
  - Plots:
	o red dot   -- recvDelta
	o blue line -- avg interval time 


sendInterPlot.c	  send interval vs. time
---------------
  - Additional Switches:
	-plot send: plot actual send interval
	-plot mscope: plot send interval from microscope
  - Formulas:  
	o sendDelta         = lastSendTime - sendTime
	o sendDeltaSum      = sum of sendDeltas
	o avg interval time = sendDeltaSum / # total packets sent
  - Plots:
	o red dot   -- sendDelta
	o blue line -- avg interval time


seqNumPlot.c	  seq num vs. receive time
------------
  - Additional Switches:
	-c: connect dots
	-f: plot per frame, not per packet
	-l: plot lost packets, not received
  - Plots:
	o red dot   -- seqNum
	o blue line -- connect dots
  - Notes: 
	o Can also be used to plot results of video simulator w/frames 
	  (#define _VIDEO)


thruPlot.c	  thruput vs. time
----------
  - Additional Switches:
	-i: size of interval, in packets  (default: 10)
  - Formulas:
        o recvDelta          = recvTimeThisPacket - recvTimeLastPacket
	o nbytes             = bytes received in this packet
	o thruBytes          = bytes received this interval
	o dataBytes          = bytes received entire run
	o interval tput      = thruBytes / recvDelta (in seconds)
	o avg tput over run  = dataBytes / recvDelta (in seconds)
	o instantaneout tput = nbytes / recvDelta (in seconds)
  - Plots:
	o red line   -- interval tput
	o blue line  -- average tput over entire run every interval
	o yellow dot -- instantaneous tput every packet