README

   1 JamVM 1.5.0
   2 ===========
   3
   4 Welcome to the twenty-third release of JamVM!
   5
   6 JamVM is a Java Virtual Machine which conforms to the JVM
   7 specification version 2 (blue book).  In comparison to most other
   8 VM's (free and commercial) it is extremely small, with a stripped
   9 executable on PowerPC of only ~170K, and Intel 130K.  However, unlike
  10 other small VMs (e.g. KVM) it is designed to support the full
  11 specification, and includes support for object finalisation,
  12 soft/weak/phantom references, the Java Native Interface (JNI) and
  13 the Reflection API.
  14
  15 Supported Architectures
  16 =======================
  17
  18 JamVM currently only includes an interpreter (keeps it small).  This
  19 means it is easy to port to new architectures as most of the code
  20 is written in C.  So far, JamVM has been built and tested on :
  21
  22 Linux
  23 -----
  24
  25 - PowerPC: for many years my main platform, so this is well tested.
  26            Built and tested on G3 and G4 systems.
  27
  28 - i386: built and tested on i586, i686 (Pentium III), Pentium 4,
  29         Athlon and Core 2 Duo.  At least an i486 is needed because
  30         JamVM uses the cmpxchg instruction, which was first introduced
  31         on the i486.
  32
  33 - ARM: Originally ported and tested on the iPAQ running Linux (3950,
  34        with xscale PXA250 processor, though it should work on StrongARM).
  35        Later development on Neo1973 (ARM920T core).  Little and Big Endian
  36        machines are supported, soft/kernel FP emulation, and OABI or
  37        EABI.
  38
  39 - AMD64: built and tested on AMD Athlon 64, Pentium 4 and Core 2 Duo
  40          (using EM64T).
  41
  42 - MIPS: built and tested on mipsel using the O32 ABI.  The system
  43         was an embedded wireless router.
  44
  45 Mac OS X/Darwin
  46 ---------------
  47
  48 - PowerPC: built and tested on Mac OS X 10.3 (Panther) and 10.4
  49            (Tiger) on G3, G4 and G5 systems.  It should also work
  50            on 10.2, but you may need to install Fink.  Note, gcc-3.3
  51            gives better performance than gcc-4.0.
  52
  53 - PowerPC64 (a.k.a G5):
  54            to build a 64-bit executable CFLAGS must include
  55            the flag -arch ppc64.  If no option is given a 32-bit
  56            executable is built by default.
  57
  58 - i386: JamVM has been built and tested on the Apple MacBook Pro
  59         (Intel Core Duo and Core 2 Duo).
  60
  61
  62 BSD Variants
  63 ------------
  64
  65 OpenBSD  : i386, powerpc, ARM, AMD64 (x86_64).
  66 FreeBSD  : i386, powerpc, ARM, AMD64 (x86_64).
  67 KFreeBSD : i386
  68
  69
  70 Class Libraries
  71 ===============
  72
  73 JamVM is designed to use the GNU classpath Java class library (see
  74 http://www.gnu.org/software/classpath).  A number of classes are
  75 reference classes which must be modified for a particular VM.  These are
  76 provided and built along with JamVM (see INSTALL).  JamVM 1.5.0 works with
  77 Classpath from version 0.92 to 0.96 (the latest development snapshot).
  78 It should also work with the latest version direct from CVS (but check
  79 the Classpath mailing lists for possible patches).  Later snapshots of
  80 Classpath may also work, if no modifications have been made to the VM
  81 interface.
  82
  83 Note, JamVM 1.5.0 will not work with versions of Classpath earlier than
  84 0.92, nor will it work with the class library from Sun or IBM's Virtual
  85 Machines, or OpenJDK.
  86
  87 Building and Installing
  88 =======================
  89
  90 Please see the INSTALL file for full instructions.
  91
  92 Running
  93 =======
  94
  95 You don't need to setup any environment variables to run JamVM.  By default,
  96 JamVM installs in /usr/local/jamvm/bin (see INSTALL for how to change it).
  97 Add /usr/local/jamvm/bin to your path, and you should be able to simply run
  98 `jamvm'.
  99
 100 CLASSPATH, -classpath, -bootclasspath and LD_LIBRARY_PATH variables
 101 -------------------------------------------------------------------
 102
 103 The location of user classes can be specified on the JamVM command line using
 104 -classpath (or -cp) or via the CLASSPATH environment variable.  If neither is
 105 specified, the classpath defaults to '.', i.e. the current directory.  The
 106 -classpath option takes priority -- if this is specified, CLASSPATH is ignored.
 107
 108 The system classes (GNU Classpath and JamVM's VM classes) are loaded via the
 109 system class loader.  By default it searches the GNU Classpath installation
 110 directory and JamVM's installation location.  This can be overridden using the
 111 -Xbootclasspath command line option, or the BOOTCLASSPATH variable.
 112
 113 By default JamVM searches the GNU Classpath installation directory and the
 114 current directory ('.') for native libraries.  Extra directories can be
 115 specified using the LD_LIBRARY_PATH environment variable.
 116
 117 Testing
 118 =======
 119
 120 Currently JamVM has been used to run fairly major command-line programs
 121 including Javac, SPECJvm 98 benchmark suite, jBYTEmark and Mauve.  It has
 122 also been successfully used with Jetty (a Java-based web server and servlet
 123 container, Tomcat, JEdit and Eclipse.
 124
 125 FEEDBACK
 126 ========
 127
 128 I welcome feedback of any kind, e.g. bug reports, suggestions, etc.  I'm always
 129 interested to hear how and if people are using JamVM so even if you don't have
 130 a problem drop me an email (email address at the bottom).
 131
 132 JamVM "Features"
 133 ================
 134
 135 For those interested in the design of virtual machines, JamVM includes a number
 136 of optimisations to improve speed and reduce foot-print.  A list, in no
 137 particular order, is given below.
 138
 139 - Uses native threading (posix threads).  Full thread implementation
 140   including Thread.interrupt()
 141
 142 - Object references are direct pointers (i.e. no handles)
 143
 144 - Supports class loaders
 145
 146 - Efficient thin locks for fast locking in uncontended cases (the
 147   majority of locking) without using spin-locking
 148
 149 - Two word object header to minimise heap overhead (lock word and
 150   class pointer)
 151
 152 - Execution engine supports many levels of optimisation (see
 153   configure --help) from basic switched interpreter to inline-threaded
 154   interpreter with stack-caching (equivalent performance to a simple
 155   JIT).
 156
 157 - Stop-the-world mark and sweep garbage collector
 158
 159 - Thread suspension uses signals to reduce supend latency and improve
 160   performance (no suspension checks during normal execution)
 161
 162 - Full object finalisation support within the garbage collector
 163   (with finaliser thread)
 164
 165 - Full GC support for Soft, Weak and Phantom References.  References
 166   are enqueued using a seperate thread (the reference handler)
 167
 168 - Full GC support for class and class-loader unloading (including
 169   associated shared libraries)
 170
 171 - GC utilitises a mark/sweep collector with compaction
 172
 173 - Garbage collector can run synchronously or asynchronously within its
 174   own thread
 175
 176 - String constants within class files are stored in hash table to
 177   minimise class data overhead (string constants shared between all
 178   classes)
 179
 180 - Supports JNI and dynamic loading for use with standard libraries
 181
 182 - Uses its own lightweight native interface for internal native methods
 183   without overhead of JNI
 184
 185 - JamVM is written in C, with a small amount of platform dependent
 186   assembler, and is easily portable to other architectures.
 187
 188
 189 That's it!
 190
 191 Robert Lougher <rob@lougher.org.uk>
 192 28th October 2007.