file js_architecture.txt
created 2005-06-12 by whygee@f-cpu.org

This file explains how the javascript code is "architectured"
in order for others to dig into it and eventually
catch bugs and smash them, or (why not ???) add features.


First comes the vspsim.html file (or sometimes vspsim.php
when server-side features are needed).

During the rough browser compatibility section,
when it's ok, some code is inserted to include external .js files
from the same directory (non-compliant browsers don't
go further and display the "red message") :

vsp_arch.js
  this one comes first, containing definitions and functions
  that are used by the rest of the files. Currently :
  int2hex, message FIFO and error handling.
vsp_reg.js
  This one defines the registers : external names, internal names,
  features, properties, initialisation and modification, management
  of the change history...
vsp_mem.js
  The memory files, just like for the registers : definition,
  modification (API with hooks) etc.
vsp_instr.js
  defines the instruction format, opcodes, fields...
vsp_eu.js
  The functions in this file implement the operations
  of the Execution Units.
vsp_exec.js
  Executes one clock cycle by connecting all the components
  (regs, mem, eu...) together.
vsp_symbols.js
  This file manages the list of user-defined symbols
  (constants, labels etc.) used during debug and interactive
  assembly & disassembly
vsp_asm.js
  This file does the assembly of instructions
  for interactive debug and coding
vsp_disasm.js
  Encoding and decoding of instructions for easy display
  and interactive coding.
vsp_status.js
  This one encodes and decodes strings for backup/restoration
  of the CPU state. It then sends / receives data to/from other
  means : PHP pipes, cookies, scratchpad, XMLHTTPRequest...
vspsim.js
  this is the last file, dealing with the user interaction,
  mouse events... so it needs all the above files to be parsed
  before starting. Most prone to browser incompatibilities,
  bugs and other nasty things.

Note that to ease porting (to C for example), the files are
sorted in order of dependency. This is needed anyway because
most files define static general variables.

Most naughty side effects come from the (early) fusion of the UI
with the sim machine (particularly the registers). Most spaghetti
are located in vspsim.js wich uses all the primitives defined before.
Now it should be a bit cleaner but be careful.

Some additional files (like test_asso.html, test_fifo.html)
are just proof-of-concept for some of the algos used in the
simulator.