docs/mjc2wsl.txt

   1 mjc2wsl tool
   2 ============================================================
   3
   4 This tool converts MicroJava bytecode into WSL code.
   5
   6 The specification currently supported is from 1999. There
   7 are some changes introduced later. For instance there is the
   8 2006 specifcation but there were no big changes, mostly some
   9 pieces of the language and bytecode were removed, presumably
  10 for simplification and more focus on the concepts.
  11
  12 More details about the specifications can be found in the
  13 MicroJava folder in the docs folder.
  14
  15 For usage guides run the tool without parameters, or with
  16 "-h" for the basic help, or with "--help" for the longer
  17 help screen.
  18
  19
  20 What works
  21 ----------
  22
  23 Currently all of the commands of the 99 specification are
  24 reconised and processed properly. All tested examples showed
  25 the same behaviour when executing the original bytecode and
  26 executing the translated WSL code.
  27
  28 Some details below:
  29
  30 There are virtual stacks to simulate both the expresion and
  31 the method stack.
  32
  33 There are arrays representing the static variables and the
  34 local variables.
  35
  36 The local variables arrays is swaped out on recursive calls.
  37
  38 Objects and arrays are stored in arrays with all the regular
  39 access code mapping properly.
  40
  41
  42 What is different
  43 -----------------
  44
  45 Objects and arrays are not directly held on a single heap,
  46 and the memory maping is simulated to behave the same, but
  47 there is no rounding for direct access to pieces of memory.
  48
  49 Object and arrays are actually held in different memory
  50 storages.
  51
  52 There is not stack pointer or frame pointer, the local
  53 variables array is swaped out as needed.
  54
  55
  56 What does not
  57 -------------
  58
  59 Character codes are not converted to actuall characters when
  60 printed on the screen.
  61
  62 The heap is not actually simulated byte-per-byte, so any
  63 code that would attempt to optimise by doing so would not
  64 work. Note however that the language specification is not
  65 allowing direct access to the memory, neither is the
  66 bytecode actually working directly with the heap, and that
  67 array and object access are done by specialised commands.
  68 Still there is an option for using fields beyond the actuall
  69 object that could produce unexpected behaviour.
  70 Array access in the MJVM does check for indexe out of bounds
  71 errors.
  72
  73 The size of the heap is not taken into consideration when
  74 allocating new arrays and objects. What this means is that
  75 there will be no heap overflow exception thrown, since our
  76 heap is seemingly endless.
  77
  78 Null access does not throw explicit errors, although it
  79 will cause problems with the list access.