NetSim Network Simulator README.TXT File
B. Cameron Lesiuk, October, 2000
clesiuk@m83.com   http://ghost.hn.org/

Note:
Please don't email me unless you have SERIOUSLY BURNING QUESTIONS about 
this stuff. First, because I'm too busy to offer any degree of support
for this thing and I may not reply to email. Secondly, because this 
is provided AS IS - it's not in a very polished state, it's overly complex
in places, and it doesn't always work. I *KNOW* it doesn't do some things
very well, so I am not going to be inclined to answer emails telling me this
or asking how to get around inherent limitations of the simulator.

============================================================================
DISCLAIMER: All source code is provided AS IS for information only. No warranty
of any kind are provided with this source code or affiliated utilities. 
The author makes no claims as to the usefullness of this code for anything 
whatsoever. The author doesn't claim it works at all, not even in a way 
described in any paper or documentation. USE AT YOUR OWN RISK!!!

LICENSE: This code is released to the public domain. Do what you want
with it. 

CLAIM OF OWNERSHIP: NetSim is written 100% from scratch by B. Cameron Lesiuk
using no 3rd party or proprietary libraries or code snipets which would 
otherwise hinder the release of this code to the public domain.
============================================================================

Greetings! In this distribution you will find the source code and
documentation (what passes for documentation anyways) for NetSim. I wrote
NetSim first as part of a directed studies course and later enhanced it
to support my work in my thesis. 

NetSim is NOT a super-complex full-blown simulator like NS. I wrote NetSim
because I found NS too complicated to wrap my little brain around, and ns
is also much larger than I needed. So NetSim is essentially a "NS on 
diet pills". 

NetSim is written entirely in C. It is NOT event based (stupid me); it
increments time using time slices - whether something happens in that
timeslice or not. You can modify the size of the time slices by changing
the value of NSTICK in network.h. 

The documentation for NetSim is somewhat non-existant; it can be found
in the source and .net files. network.h has the main documentation of
the code structure - read it in conjunction with netsim.net and you
should be able to start to piece together the platform.

If this is your first wack at this thing, you should probably start
by reading the makefile and trying to just build the sucker. Just
type:
  make clean 
  make dep 
  make
  netsim
and it hopefully will work. You'll get some junk printed to the screen, 
and you'll get a .nam file output which you can view with nam. nam is 
a network animator and can be acquired independently - check out the 
web pages for ns. 

As of the time of this writing, I have NetSim tuned to support my
thesis. Modules like wireless.c are not fully developed (ie: don't support
.nam output) and are not even completely debugged. However, the ones
that are used in the default .net file DO seem to work quite well. In 
particular, wire.c and dsr.c. 

NOTE: Although dsr.c and wire.c both support mediums with more than two
interfaces, I don't know how to make .nam files to animate it. Thus, 
you CAN use NetSim to simulate multi-drop mediums, but you can't SHOW
anyone (unless you add the functionality yourself - hint hint). But showing
is usually merely a thing for seminars - you probably just want statistics
and such for regular research, so this isn't much of an impediment.

Ok, let me run through the modules and give a brief description of 
what's what.

BASIC SIMULATOR NETWORKING MODULES
----------------------------------
main.c      - the entry point for the program. Worth a read. It has some
              documentation at the start of it. A good place to start.

network.c   - This should be your second place to look. These modules
network.h     implement the basic network operation, independent of 
              protocols, mediums, and so forth. 

hwmgr.c     - this is the "tie point" where the various modules 
hwmgr.h       for the protocols, traffic generators, and mediums are 
              brought together.

memmgr.c    - I have had a LOT of memory leak problems with this simulator.
memmgr.h      In particular, I think the wireless.c module is extremely
              flakey. I wrote memmgr.c to try to track down some of the
	      problems, but I had mixed success. In the default distribution
	      of NetSim, this module is disabled. I would suggest you leave
	      it disabled because I think memmgr is flakey too, or in the
	      very least, fragile.

nsfile.c    - This module just reads in the .net file (parses it) and 
nsfile.h      constructs a network in memory from the .net file specification.

schedule.c  - Implements a simple event scheduler. If I was to do this again, 
schedule.h    I'd make the entire simulator run off an event-based scheduler.
              But as of right now the only thing that uses scheduled events
	      is the medium state functionality to bring links up or down
	      at specified times. 

nam.c       - These files support .nam file output. However, the protocol
nam.h         and medium implementations still have to support .nam files
              by calling the routines in this module at the correct time
	      with the correct information.


PROTOCOL, MEDIUM, AND PACKET GENERATION FILES 
---------------------------------------------
magicmedium.c - These four files implement a "magical" medium and 
magicmedium.h   network layer routing protocol which can "magically"
magicnet.c      deliver packets from anywhere to anywhere instantly. 
magicnet.h      I wrote these to test the original networking engine.
                They provide an example of the simplest network and
		medium implementation possible.

pksource.c  - This module implements two packet generation algorithms.
pksource.h    They are both pretty simple.

dsr.c       - my implementation of the Dynamic Source Routing (DSR)
dsr.h         protocol. I wrote this optimized as though it's running
              on a network made from embedded microcontrollers. But you
	      should be able to tinker with it to emulate other platforms.

wire.c      - Implements a wired physical medium (link) like ethernet 
wire.h        or I2C or CAN bus. 

wireless.c  - Implements a wireless medium where link connectivity 
wireless.h    is deremined by how close nodes are toghether. FLAKY AND
              I'M NOT SURE IF THIS IS WORKING WITH THE CURRENT NETSIM
	      MODULES. This module does NOT currently support .nam output
	      files.

OTHER FILES
-----------
mkdep.c     - This is a stand-alone utility to automatically generate
              dependency information in the makefile. It has nothing
	      to do per-se with the operation of NetSim.


OK, now that you know what everything does, I am going to leave you to it.
Good luck, and I hope this in some way helps you in your work.

