Aries Decentralized Abstract Machine (ADAM) system simulator, multi-node version.
5/3/2002 bunnie@mit.edu

adam.jar    -- java classes for the simulator.
adamB.jar   -- experimental simulator version, beware.
splash.gif  -- must be in the same directory as adam.jar
defaultException.asm --  must also be in the same directory as adam.jar
default.net -- a starter netlist, you should create your own using the
               ADAM netlist generator built into ASS, however
archdoc.pdf -- architecture documentation, DRAFT version. A handy
               thing that explains what the heck this simulator is trying
               to simulate (this doc is not my thesis, just a chapter of it--
               a fuller explanation is in the thesis)
netlists/   -- netlists used for testing, for reference only
tests/      -- regression test suite (.asm files)
old/        -- single-node ADAM simulator
makeBin.c   -- utility program to convert ASCII decimal text delimitted by
               carriage returns into binary files compatible with the FILE
               command
code/       -- "People" test code for ASS, supplemental (N-Body in particular)

2/19/2002:
to run the ADAM System Simulator (ASS), use this command line:

java -classpath adam.jar adam.Adam

You will probably need a java 1.3 compliant JVM.

ASS will run .asm code generated by the couatl compiler.

See http://web.mit.edu/benmv/aries/pub/

for the compiler, examples, test code and compiler run instructions...

enjoy!

------------------------------------------------------------------------------
                                 -CHANGELOG-

2/27/2002:

Added command line mode support and various bug fixes.
To use command line mode support, do

java -classpath adam.jar adam.Adam -commandline -runto    ...

Other options included are -quiet and -debug

2/28/2002: (v0.7)

Added NOT, SIC instructions. Fixed FLUSHQ instruction. FLUSHQ does
not work on mapped queues. Updated archdoc.pdf to reflect new
instructions.

3/1/2002: (v0.75)

Added MOVECL label, qc and JMPL instructions.

4/9/2002: (v1.0beta)

Added multi-node simulation capability.
Added multi-threaded simulation feature.
Added done combiner tree for inter-thread synchronization.
Reliable delivery transport protocol with in-sequence connections added.
New GUI added with keyboard shortcuts and limited debug features.
New command line mode.
Ability to create netlists, only 4^N machine sizes supported (all generated
  netlists are randomized)
Added remote memory capability references.
Added forwarding pointer resolution and temporal bidirectional pointers.
Added thread garbage collection (still need mem map GC)
Added EXCH instruction
Data migration mechanism
Thread migration mechanism
Added SPAWN, SPAWNC, ALLOCATE, ALLOCATEC with distance/hotness metrics
  (backward compatibility maintained)
Added MIGRATE qa, qb instruction (not documented in archdoc.pdf; for
  testing only). qa is the capability that is to be migrated; qb is
  either a word or a capability that specifies the destination node.
  If qb is a capability, the destination node is assumed to be the
  nearest destination to the capability processor ID. 

Known bugs:
 -needs FILE instruction
 -subtle thread state with concurrent load/store bugs, solutions known

4/9/2002: (v1.0.1)

Added FILE instruction, format is FILE "filename.bin", qc
  filename.bin must exist in the same directory as adam.jar. The
  format of the data is 64-bit words, little endian, binary data.
  makeBin.c is a C program that can convert a sequence of 32-bit
  decimal values in ASCII text, with a value on each line followed
  by a carriage return, into a properly formatted binary file for
  the ADAM FILE instruction.

4/11/2002: (v1.1)

Memory locking is now done properly (hopefully). To make migrations
  threadsafe, mem ops are now limited to one outstanding request
  per memory location, any number of concurrent requests to different
  locations. Beware deadlock based on load-dependant stores. 
MSYNC instruction added. MSYNC stalls until all pending memory operations
  have completed.

4/14/2002: (v1.2)
Fixed bug in virtual memory routine (add vs. set bug) that was causing
  problems in lines.asm.
Improved SPAWN/ALLOCATE remote random distribution algorithm, still yet
  to prove if its tree selection is truly random.

4/15/2002: (v1.3)
Fixed BRL bug (link got PC, not PC + 1)
Fixed remote spawn bugs, hopefully. Quicksort with random load dispersal
  works, at least.

4/23/2002: (v1.4alpha)
Bug fixes to: scheduler, migration, pending memory operation requests,
Added a work-stealing engine, disabled in this build.
This build has high verbosity for debugging messages, especially on
  migration activity.
ANCHOR instruction added. Prevents a thread from migrating, ever. 
The pre-emptive scheduling feature can cause improperly written code to 
  malfunction.  
The following code sequence does not work:
  MML  q7, q8
  MMS  q10, q11
  MOVE @q13, q10
  MOVE @q20, q10
  MOVE @q13, q7
  MOVE @q21, q7
  MOVE q8, q11    *
  MOVE @q13, q10

This is because the instruction with a * next to it must execute
for the store mapping to 


4/24/2002: (v1.4beta)
Added RADIUS, qc; puts the network radius into qc. Radius is the
  max number of up routes in the system.

4/29/200: (v1.5)
Added load balancing. Work stealing and work pushing implmented. 
Thresholds set to nominal effort for load balancing. Supress load
balancing with -nolb; recommended if you see any weirdness, as the
load balancing protocol is pretty complicated and has not been
thoroughly tested. 

Also added file logging for load balancing feature. This may require
the directory ../benchmark to be created; I will strip this 
functionality out eventually, or add a command-line switch to turn
it off.

Also added FRANDOM and SQRT for doing N-Body simulations.

4/29/2002: (v1.5b)
FSUBC fixed; used an FSUB template by accident in the type dispatch.
Also improved error reporting on type exceptions.

4/30/2002: (v1.6)
Fixed serious memory leak problem (thread GC wasn't freeing up code space)
Improved performance; PipeDelay.Vector.elements was a gating item;
  now PipeDelay.LinkedList.Iterator is the gating item :P 
Improved exception reporting to include arguments of the exceptioned
  instruction.
Seemed to have broken load balancing in subtle ways, suspect interaction
  with aggressive GC. 

5/1/2002: (v1.6.2)
Fixed copyCodeTo null pointer problem--did not set the immortal bit on
  code that was loaded in manually. Also lead to a lot of cleaning up
  of the code management and registry infrastructure.
Fixed serious memory forwarding pointer bug--was extracting capBase, not
  capBeginning to determine forwarding pointer location in the handling
  of nonlocal requests.
Memory migration infrastructure in place, but permanently disabled
  beacues it is not tested.
Fixed floating point number corruption by network interface--missing an _
  in a variable name.

5/2/2002: (v1.6.3)
Fixed memory migration aliasing pointer bug. memory.get() ops return
  stuff that I assume never changes but actually does get mutated by
  the runtime later during migration (nulling of local memory when
  it is forwarded)
Fixed a strange, strange case for niSendHelper() call in PQF; if a queue
  has data in it and it is mapped, it aggravates a case that apparently
  was never caught in testing. ASSERT added to check if it happens again.

5/2/2002: (v1.6.4)
FILE instruction fixed to swap itself in as resident upon execution.
  A gross hack was used to make this work. Beware. Probably not 
  a good idea to migrate a thread while it is executing a FILE instruction.

5/2/2002: (v1.6.5)
Fixed bug in PQF send request for resident lines that are mapped.
  I was sending the mapped queue's destination VQN as the current queue's
  VQN. oops.

5/3/2002: (v1.7)
"Dumbest bug. Ever." Fixed a bug which caused the PhyDriver() to accumulate
  data infinitely, causing the network to look really deep/long latency.
  But only under heavily loaded conditions. 
Also broke some false dependancies in the transport interface; all generic
  route destinations used the same "destAddr" tag, which caused them all
  to use the same connection ID, and also caused them to be delivered in
  order. Different generic destinations were assigned to distinct 
  functionalities; it is not okay, however, to generate random destination
  tags as the out connection table quickly overflows in that case.

5/4/2002: (v1.7.1)
Added EXTCID, EXTVQN instructions. Use like this:
	MOVECC    0, q0		; test extcid/extvqn
	SPAWNC    q0, begin, q1
	MAPQC     q0, q0, q1
	MOVECL    0, q4
	EXTCID    @q4, q2
	PRINTQ    q2
	EXTVQN    q4, q2
	PRINTQ    q2

Also some tweaks to the migration algorithm, but they are all disabled
  anyways in this release.

5/4/2002: (v1.7.2)
Tweaked EXTCID, EXTVQN instructions to use a different semantic. Like this:

	MOVECC    0, q0		; test extcid/extvqn
	SPAWNC    q0, begin, q1
	MAPQC     q0, q0, q1
	EXTCID    q0, q2
	PRINTQ    q2
	EXTVQN    q0, q2
	PRINTQ    q2

In other words, the first argument is interpreted as a constant value,
and not a queue to take values from.

5/5/2002: (v1.7.2a)
FILE values are now marked as mutable, as read-only caching is broken.
  A stop-gap fix. This should be fixed later...