@section 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:

@itemize @bullet
@item @strong{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.

@item @strong{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.

@item @strong{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.

@item @strong{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.
@end itemize

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 
@file{package.html} file in
@file{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.


@section 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 @code{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.


@section Timer Support

@c This duplicates a FAQ entry.  One should clearly be refering to the
@c other, but I don't know which.  This sounds like something a bit too
@c detailed for README, but who knows.

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
@option{-period} runtime argument:
@example
./ovm -period=@var{nnn} @var{<main class name> <args>}
@end example
where @var{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, @file{librk-rt.a}, is available by setting the
@env{LIBRARY_PATH} environment variable when running configure, and when
building the OVM and an OVM image.

@section Known Problems

The Ovm program (@command{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 @kbd{@key{ctrl}-Z}) and then
restart it using fg.

@section Hacking Ovm

Contributions are welcome, please submit bug reports to
@uref{http://www.ovmj.org/~mantis/}.  If you have questions or want to
contribute, contact us at @email{ovm@@mail.ovmj.org}.


@section Ovm on the web

@itemize @bullet
@item @uref{http://www.ovmj.org/}
@item @uref{http://www.ovmj.org/mailman/listinfo/ovm}
@item @uref{http://www.ovmj.org/~mantis/}
@end itemize

