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:

   * *weak references* - There is no support for weak references.

   * *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 native calls or weak references 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.

Obtaining Ovm
=============

This section describes how to get the Ovm source via CVS. If you
already obtained the source files via some other means, skip to the next
section.

   This section does not necessarily assume you have much familiarity
with CVS, but if you are going to be working on or with OVM, it is
suggested that you familiarize yourself with  CVS by looking at the
online documentation at `http://www.cvshome.org'.

Anonymous CVS
-------------

To obtain the source via anonymous CVS, enter the following on the
command line in the directory you want to place your local copy of the
source tree:
     cvs -d :pserver:anonymous@ovmj.org:/var/cvs/OpenVM checkout OpenVM

CVS access via Purdue (for internal developers)
-----------------------------------------------

For internal developers with CVS access via Purdue CS machines, the Ovm
source is located in the `/p/sss/cvs/' directory. Assuming your machine
mounts `/p/sss/cvs/', the command to check out the source is as follows:
     cvs -d /p/sss/cvs checkout OpenVM

   If for some reason the machine you're on does not mount /p/sss/cvs,
you need to do the following:
  1. Set the environment variable CVS_RSH to `ssh'

  2. Run   `cvs -d :ext:yourname@fox.cs.purdue.edu:/p/sss/cvs checkout
     OpenVM'.

   Regardless of the means used to check out the source, CVS should
create a directory called `OpenVM' in the current directory which will
contain all of the current source code.

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.4), 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 -source 1.4 -target 1.4' 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-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 the mailing
list.  If you have questions or want to contribute, contact us at
<ovm@lists.purdue.edu>.

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

   * `http://www.ovmj.org/' describes the Ovm research project and
     provides a list of publications.

   * `http://www.ovmj/org/doc' contains program documentation.

   * `http://lists.purdue.edu/mailman/listinfo/ovm' can be used to
     subscribe to the ovm mailing list.

