README
******

What is Ovm?
============

   Ovm is a tool for generating virtual machines.  Ovm includes a
variety of compilers, garbage collectors, and threading systems that
can be used to create a free-standing VM.  This VM can (and currently
must) be specialized to a particular application.  Ovm is currently
able generate virtual machines for ordinary Java programs, and programs
written to the Real-time Specification for Java.

   Note that Ovm is not yet feature-complete and not fully compliant
with the JVM specification.  Missing features include:

   * *dynamic loading* - Like many ahead-of-time compilers for
     real-time/embedded systems, the Ovm does not support dynamic
     loading of classes. In the future we expect to support this via
     some form of mixed-mode operation and/or using the JIT compiler.

   * *weak references and finalization* - There is no support for weak
     references but heap finalizers are run.  Finalizers for objects
     allocated in RTSJ scoped memory are also run.

   * *Non-core JDK API's that rely on native code* - Ovm does not
     support the AWT and other API's that are non-core. Ovm depends on
     GNU Classpath for all of the JDK API's, but must provide its own
     special code to replace all native calls.

   * *JNI support* - Ovm does not support JNI and it is not planned at
     the present. Much native code is replaced in Ovm by Java code
     operating in what we term the "executive domain". There are ways
     to provide additional native code support but there are highly
     specialized and not intended for general application use.

   Code using dynamic loading, native calls or finalizers will need to
be adapted to work with Ovm.

   The implementation of the real-time APIs is also incomplete - see the
`package.html' file in `src/syslib/user/ovm_realtime/javax/realtime'
for details.

   This is a BETA release.  Ovm still has known bugs that can lead to
unexpected behavior, especially when migrating large applications to
Ovm.

Usage
=====

   Ovm is regularly tested on Linux/x86, Linux/ppc, and OS X/ppc.  The
JIT only works on x86.  Ovm requires a Sun, IBM, or Apple release of
Java 1.4, or 1.5 (ensure you compile with -source 1.3), and gcc 3.x to
build.  256 MB of main memory are also required, 1 GB is recommended.

   In order to run Java applications under Ovm, it is strongly
recommended that you compile the applications against Ovm's version of
the JDK (which is based on GNU classpath).  This is the easiest way to
ensure that you do not rely on library functionality that is not
available.  Instructions on how to compile Java code against the Ovm
JDK are in the file TUTORIAL.  The TUTORIAL also describes how to run
the SPEC JVM and the real-time benchmarks.

   Also note that all class files must have been compiled to the format
defined by the `javac -target 1.1' setting. This restriction will be
removed in the future.

   At this point in time, Ovm always requires whole-world compilation of
the application.  Ovm has three execution backends, an interpreter, a
JIT and J2C which is a front-end to GCC.  Both the interpreter and the
JIT are intended to be used in conjunction with dynamic loading in the
future.  At this stage, building Ovm with these configurations is only
useful for development purposes.  All benchmarking should always be
done with the J2C configuration with gcc-3.4.

Timer Support
=============

   OVM uses a default timer interrupt rate of 10ms. This affects all
timed operations, such as sleeps, waits, RTSJ periodic thread release,
and RTSJ timers. The timer interrupt rate can be set at runtime using
the `-period' runtime argument:
     ./ovm -period=NNN <MAIN CLASS NAME> <ARGS>
   where NNN is a value in microseconds. The requested value will be
rounded up to a multiple of the supported underlying timer resolution. A
warning is printed if you ask for a timer interrupt rate that is shorter
than the supported timer resolution, but no warning is printed if the
rate needs to be rounded up.  OVM reports the actual timer interrupt
rate being used at start-up time.

   On the majority of Linux systems the supported timer resolution is
10ms. This cannot be changed. Apparently in 2.6 kernel Linux systems
this will reduce to 1ms. When running on the licensed Timesys Linux RT
system a high resolution implementation of the POSIX real-time timers is
available, with a resolution of 1us. To use these timers you must ensure
that the Timesys library, `librk-rt.a', is available by setting the
`LIBRARY_PATH' environment variable when running configure, and when
building the OVM and an OVM image.

Known Problems
==============

   The Ovm program (`gen-ovm'), may very rarely hang after calling out
to a subprocess.  This appears to be a bug in Linux implemenations of
Java 1.4+.  Ovm attempts to detect and work around the problem, but this
code is extremely difficult to test. One simple trick that sometimes
unhangs things is to stop the process (use `<ctrl>-Z') and then restart
it using fg.

Hacking Ovm
===========

   Contributions are welcome, please submit bug reports to
`http://www.ovmj.org/~mantis/'.  If you have questions or want to
contribute, contact us at <ovm@mail.ovmj.org>.

Ovm on the web
==============

   * `http://www.ovmj.org/'

   * `http://www.ovmj.org/mailman/listinfo/ovm'

   * `http://www.ovmj.org/~mantis/'

