JamVM 1.2.0
===========

Welcome to the seventh release of JamVM!

JamVM is a new Java Virtual Machine which conforms to the JVM
specification version 2 (blue book).  In comparison to most other
VM's (free and commercial) it is extremely small, with a stripped
executable on PowerPC of only ~110K, and Intel 80K.  However, unlike
other small VMs (e.g. KVM) it is designed to support the full
specification, and includes support for object finalisation, the
Java Native Interface (JNI) and the Reflection API.

Supported Architectures
=======================

JamVM currently only includes an interpreter (keeps it small).  This
means it is easy to port to new architectures as most of the code
is written in C.  So far, JamVM has been built and tested on :

- PowerPC: my main platform, so this is the most tested.

- i386: built and tested on i586, i686 (Pentium III) and Pentium IV.
        At least an i486 is needed because JamVM uses the cmpxchg
        instruction, which was first introduced on the i486.

- ARM: ported and tested on the iPAQ running Linux (3950, with xscale
       PXA250 processor, though it should work on StrongARM).

JamVM has only been built and tested on Linux.  It may work on other
Unix systems with the above processors "as is" as long as they support
Posix threads, but I haven't tested.

Class Libraries
===============

JamVM is designed to use the GNU classpath Java class library (see
http://www.gnu.org/software/classpath).  A number of classes are
reference classes which must be modified for a particular VM.  These are
provided and built along with JamVM (see INSTALL).  JamVM 1.2.0 works with
Classpath version 0.09, 0.10 and 0.11 (the latest development snapshot).  It
should also work with the latest version direct from CVS (but check the
Classpath mailing lists for possible patches).  Later snapshots of Classpath
may also work, if no modifications have been made to the VM interface.

Note, JamVM 1.2.0 will not work with versions of Classpath earlier than 0.09,
nor will it work with the class library from Sun or IBM's Virtual Machines.

Building and Installing
=======================

Please see the INSTALL file for full instructions.

Running
=======

You don't need to setup any environment variables to run JamVM.  By default,
JamVM installs in /usr/local/bin (see INSTALL for how to change it).
Therefore, as long as you have /usr/local/bin in your path, you should be
able to simply run `jamvm'.

CLASSPATH, -classpath, -bootclasspath and LD_LIBRARY_PATH variables
-------------------------------------------------------------------

The location of user classes can be specified on the JamVM command line using
-classpath (or -cp) or via the CLASSPATH environment variable.  If neither is
specified, the classpath defaults to '.', i.e. the current directory.  The
-classpath option takes priority -- if this is specified, CLASSPATH is ignored.

The system classes (GNU Classpath and JamVM's VM classes) are loaded via the
system class loader.  By default it searches the GNU Classpath installation
directory and JamVM's installation location.  This can be overridden using the
-bootclasspath command line option.

By default JamVM searches the GNU Classpath installation directory and the
current directory ('.') for native libraries.  Extra directories can be
specified using the LD_LIBRARY_PATH environment variable.

Testing
=======

Currently JamVM has been used to run fairly major command-line programs
including Javac, SPECJvm 98 benchmark suite, jBYTEmark and Mauve.  It has
also been successfully used with Jetty (a Java-based web server and servlet
container).


FEEDBACK
========

I welcome feedback of any kind, e.g. bug reports, suggestions, etc.  I'm always
interested to hear how and if people are using JamVM so even if you don't have
a problem drop me an email (email address at the bottom).


Changes since JamVM 1.1.4
=========================

- Substantially rewritten the interpreter to use "stack-caching".  This is
  an optimisation to eliminate most of the intermediate loads and stores to
  the operand stack.  On desktop PowerPC (e.g. PPC750fx, MPC7447 with large,
  on-chip L2 cache at full processor speed) it achieves a speed increase of
  between 15 and 30%.  On ARM (XScale PXA250) it achieves a speed-up of 
  50%.  Unfortunately, due to the addressing modes of the IA32 (Pentium, etc.)
  and the code produced by gcc, it is actually slower than the old interpreter!
  Because of this, stack-caching is disabled by default on IA32.

- Zip/Jar support is implemented in the bootstrap class loader.  This means
  glibj.zip no longer needs to be unzipped.  This includes resources.

- Fix for edge-conditions in floating-point to integer conversion (floating-
  point value greater than int/long range).

- Fix for very large array allocation, where the required memory overflows a
  32 bit int (fixes the SEGV with Mauve).

- Several other minor bug-fixes (e.g. ExceptionCheck was missed out of the JNI
  i/f table).


Changes Since JamVM 1.1.3
=========================

- JNI enhancements introduced in Java 1.2 implemented.

- Updated to use GNU Classpath 0.09.

- Pre-compiled VM classes will now be rebuilt automatically if Java sources
  change.  Fix to enable build directory to be different to source directory.

- Deprecated compiler warnings in gcc >= 3.3.3 fixed (use of cast expressions
  as lvalues).  JamVM now also builds with gcc 3.5.0.

- Minor bug-fixes and speed optimisations.

- Eclipse now starts up.


Changes Since JamVM 1.1.2
=========================

JamVM 1.1.3 is primarily another bug-fix release.  New functionality will
be included in JamVM 1.1.4.

- Resolution fixes to make JamVM 100% compatible with code produced
  by javac in JDK >= 1.4 and Jikes 1.19.

- New command line options -bootclasspath/a and -bootclasspath/p to prepend
  or append entries to the default bootstrap class loader.

- Default initial heap size increased to 1Mb from 256K.  "Hello World" will
  work with a heap of 75K, but this better reflects desktop application heap
  usage.  In an embedded environment -ms can be used to specify a smaller
  initial heap (e.g. -ms256k).

- Bug fix for private method invocation via JNI and reflection.

- Several other minor bug-fixes.


Changes Since JamVM 1.1.1
=========================

JamVM 1.1.2 is primarily a bug-fix release.  No new major functionality is
included, but many, many bugs have been fixed.  If JamVM didn't work for you
before, give this release a go!  Off the top of my head and in no
particular order:

 - Arraycopy and instanceof fixed for arrays involving different dimensions
   and Object element type

 - Array/inner class/primitive class access flags correctly set (important
   for serialization)

 - Reflection API : method invoke on interface methods now works

 - JNI : method invoke on interface methods now works

 - getResource/getResources implemented for bootstrap class loader

 - ClassLoader.findLoadedClass now handles classes initiated by a
   class loader

 - The thread contextClassLoader is now set

 - The protection domain is now set for a class

 - Many other minor bugs 

JamVM now uses VMRuntime and will now only work with Classpath 0.08.


Changes Since JamVM 1.1.0
=========================

- Now supports classes compiled for target >= 1.2.  In the past, javac inserted
  synthetic methods for interface methods not implemented by abstract classes.
  These are not produced if javac is used with -target 1.2, which is now the
  default with JDK 1.4.  JamVM now inserts these methods if they are not
  supplied by the compiler.
  
- Class loader changes.  JamVM now records initiating loaders so user-defined
  class loaders should be referred to less.

- Updated to use classpath 0.07.

- Java 2 style application class loader/bootstrap class loader split
	 - new command line options -bootclasspath and -classpath (or -cp)
	 - Jar and Zip archives can now be specified in the classpath.

- bug fixes (integration of Classpath 0.06 in JamVM 1.1.0 broke instanceOf)

- Re-worked stack overflow handling.  Previously, the first thread overflow
  would be trapped, but further overflows would not.  A thread may now catch
  StackOverflowException and repeatedly overflow.


Changes Since JamVM 1.0.0
=========================

There's been quite a few changes, including performance improvements and more of
the specification is now implemented (should be everything now but Runtime.exec),
as well as the usual bug-fixes.

- Interface method tables are now implemented.  This means an interface method
  invocation should now be almost as fast as a normal virtual method.

- The full Reflection API is implemented (Constructor, Field, Method, etc.)
  with primitive widening and wrapping and inner class support.

- Updated to use Classpath-0.06 rather than 0.04 (note JamVM won't work with
  0.04 anymore).

- Ported to the ARM architecture.

- Re-worked exception printing - now supports 1.4 style StackTraceElements.

- Interpreter optimisations (more "fast" bytecodes).

- Command line system properties can now be specified (-Dname=value).


JamVM "Features"
================

For those interested in the design of virtual machines, JamVM includes a number
of optimisations to improve speed and reduce foot-print.  A list, in no
particular order, is given below.

- Uses native threading (posix threads).  Full thread implementation
  including Thread.interrupt()

- Object references are direct pointers (i.e. no handles)

- Supports class loaders

- Efficient thin locks for fast locking in uncontended cases (the
  majority of locking) without using spin-locking

- Two word object header to minimise heap overhead (lock word and
  class pointer)

- Execution engine supports basic switched interpreter and threaded
  intepreter, to minimise dispatch overhead (requires gcc value labels)

- Stop-the-world mark and sweep garbage collector

- Thread suspension uses signals to reduce supend latency and improve
  performance (no suspension checks during normal execution)

- Full object finalisation support within the garbage collector
  (with finaliser thread)

- Garbage collector can run synchronously or asynchronously within its
  own thread

- String constants within class files are stored in hash table to
  minimise class data overhead (string constants shared between all
  classes)

- Supports JNI and dynamic loading for use with standard libraries

- Uses its own lightweight native interface for internal native methods
  without overhead of JNI 

- JamVM is written in C, with a small amount of platform dependent
  assembler, and is easily portable to other architectures.


That's it!

Robert Lougher <rob@lougher.demon.co.uk>
9th September 2004.
