README for the OCDMA LAN simulator

1. Introduction
---------------

The OCDMA Local Area Network simulator simulates a shared, broadcast Local 
Area Network. It simulates a network of several nodes connected by a 
passive optic coupler. 

The physical layer is based on Optical CDMA. Several physical layer parameters are configurable:
(a) Bandwidth (chipping rate) or the network
(b) Codeset parameters (Length, weight, kappa)
(c) Codeset used

The media access control protocol is an Interference Sensing/Interference Detection based protocol. The following parameters can be configured: 
(a) Media access algorithm (Aloha, Selfish, Threshold, Code estimation [1],[2])
(b) Sensing window
(c) Sensing thresholds
(d) Backoff times

The simulator runs using traffic files. The traffic files consist of records for each packet. 
The trace file has the following parameters:
(a) Arrival time of the packet
(b) Source, destination addresses 
(c) Packet sizes 

2. Building the simulator
-------------------------

Download the code to a directory
Type "make"
An executable called "linesim" should be created

3. Running the simulator
------------------------

3a. Trace file 

A sample trace file trace.10.in is provided with the simulator code.
The format is 

<timestamp of packet arrival at interface card in seconds> <size of packet in bytes> <src address> <src port> <dst address> <dst port> <packet id>

<pktid> is a unique identifier for each packet

3b.Codeset file format
A sample codeset file codes.30.5.3.txt is provided with the simulator code.
The naming format of the codeset file is codes.<code length>.<weight>.<kappa>.txt 

The codeset file format is below:
<Number of codewords in the codeset>
<Weight of the codeset>
Codeword1
Codeword2
.
. 
.
.

3c. Running the simulator

linesim <Chipping rate in Mb/s> <Codeset length> <Weight of codeset> <Kappa>  <Sensing window in bits> <Trace file specifier (trace.$specifier.in)>  <Media access protocol/algorithm> <othreshold> <mthreshold> <Backoff duration in us> <Seed>

<Trace file specifier> is the parameter that specifies the trace file to use. 
E.g. if the trace file is trace.10.in then <specifier> = 10
<Seed> is a random seed

For more information about the meaning of the simulation parameters, 
refer to [1], [2].

E.g. a 1000 Gb/s chipping rate with a (30,5,3) code using a Threshold based 
media access control algorithm with thresholds of (2,2) and a sensing window
of 10 bits and backoff time of 10us, the command line would be:

./linesim 10000 30 5 3 10 10000 2 4 2 200 234

The simulator reads the input trace file, runs the simulation and dumps the output to an output trace file.The name of the output trace file is trace.<specifier>.out

The output trace file format is 
<timestamp of packet transmission in seconds> <packet size in bytes>  <source addr>.<src port> <dst addr>.<dst port> <packet id> <codeword> <number of defers> <state of packet (Received/Dropped)> <channel access delay>

Note that the timestamps in the output file will not be in order (they are the
transmission times). Packets are ordered in the order that they are received

At the end of the run, the simulator provides the following results:
(a) Fraction of packets lost due to interference
(b) Network throughput


4. Known limitations
The last few packets of the input trace file will not be read. 
Hence, the output trace file will contain fewer packets than the input 
trace file


5. References

[1]	P. Kamath, J. D. Touch, and J. A. Bannister, ``Algorithms for Interference 
Sensing in Optical CDMA Networks,'' in IEEE International Conference on
Communications (ICC), June 2004.

[2]	P. Kamath, J. D. Touch, and J. A. Bannister, ``The Need for Media Access 
Control in Optical CDMA Networks,'' in IEEE Infocom, March 2004.