\input texinfo
@c use postscript fonts
@c @iftex
@c \usepackage{times}
@c @end iftex


@setfilename ovm.info
@settitle Ovm Users Manual

@dircategory Programming
@direntry
        * ovm: (ovm).  A configurable JVM generator
@end direntry

@macro javadoc{tail}
@uref{http://www.ovmj.org/doc/javadoc/\tail\}
@end macro

@macro pkgdoc{pkg}
@javadoc{\pkg\/package-summary.html}
@end macro

@ifnottex
@copying
Copyright @copyright{} 2004-2007 Purdue University @c others?
@end copying
@end ifnottex

@titlepage
@title Ovm Users Manual
@author The Ovm Development Team

@ignore
@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end ignore

@end titlepage
     
@c So the toc is printed at the start.
@contents
     
@ifnottex
@node Top
@top Ovm Users Manual

@insertcopying

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.

@end ifnottex

@menu
@c * Copying Conditions::          such as they are
* Overview::                   Ovm in a nutshell
* gen-ovm Tutorial::           Getting started with Ovm
* Invoking gen-ovm::           @command{gen-ovm} takes many options
* Invoking ovm-config::        @command{ovm-config} takes the same options
* Invoking gen-spec-ovm::      @command{gen-spec-ovm} takes even more
* Invoking ovm::               The resulting executable takes many options 
                               of its own
* Using Ovm::                  Hints for working with Ovm virtual machines
* Ovm Internals::              An overview of the code itself.
@c * Stitcher::         The InvisibleStitcher configuration language
@c * Repository::       The @code{ovm.core.repository} data structures
@c * Extending OVM::    Replacing Ovm components
* Frequently Asked Questions:: with answers
* Index::
@end menu

@c chapter 0
@c @node Copying Conditions
@c @chapter Copying Conditions
@c @include COPYING

@c Chapter 1
@node Overview
@chapter Overview

@include README.texi

@c Chapter 2
@node gen-ovm Tutorial
@chapter Getting started with Ovm

@include TUTORIAL.texi

@c Maybe it is time to simplify the usage message, and move some of the
@c text into this manual.
@c Chapter 3
@node Invoking gen-ovm
@chapter Invoking @command{gen-ovm}

@pindex gen-ovm
@cindex invoking gen-ovm

Run @code{gen-ovm -?} for a list of all options.

@node Invoking ovm-config
@chapter Invoking @command{ovm-config}
@pindex ovm-config
@cindex inspecting ovm configurations

The @command{ovm-config} command takes the same set of options as
@command{gen-ovm}, and can be used to read the values of these
options.  This is actually useful, since many @command{gen-ovm}
options take default values that depend on the rest of the
configuration, and on where Ovm code resides.

@cindex bootclasspath
For instance, @command{ovm-config} can extract the
@option{-bootclasspath} that applications are linked against.
@samp{ovm-config -threads=JVM get-string bootclasspath} will print the
bootclasspath used in standard java configurations and 
@samp{ovm-config -threads=RealtimeJVM get-string bootclasspath} will
print the bootclasspath used in RTSJ configurations.

@cindex image file
The @command{ovm-config} command can also return information about
Ovm's global configuration.  If the image file name,
@xref{Invoking ovm}, is needed at runtime, 
@samp{ovm-config get-string image-argument} will print the base name
of that file (@code{img}), otherwise it will print an empty string.
The @command{ovm-config} command can also display Ovm's value for the
@code{java.home} property, when invoked as follows:
@samp{ovm-config get-string ovm-home}.

@node Invoking gen-spec-ovm
@chapter Invoking @command{gen-spec-ovm}

@pindex gen-spec-ovm
@cindex compiling SPECjvm98

@example
gen-spec-ovm @var{option}* @option{--}? @var{gen-ovm option}*
@end example

@command{gen-spec-ovm} is a thin wrapper around @command{gen-ovm} that
builds a virtual machine to execute the SPECjvm98 benchmark suite.
@command{gen-spec-ovm} knows the magic incantations needed to compile
SPECjvm98 inside Ovm, and achieve the best performance.
@command{gen-spec-ovm} can also pass configuration options on to
@command{gen-ovm}.

@command{gen-spec-ovm} takes three options:
@table @option
@item --spec-dir=@var{directory}
      Gives the path to the SPECjvm98 directory..  The default value
      (@file{/p/sss/project/SPECjvm98}) works within Purdue.
@item --test=@var{list}
      where @var{list} is a comma seperated list of benchmarks to
      compile.  By default, all benchmarks are compiled into a single
      executable, but @code{gen-spec-ovm --test=javac} only compiles
      @code{_213_javac}.
@item --applive
      Invoke @command{gen-ovm} with @option{-app-methods-live} rather
      than @option{-ud-reflective-methods=...}.
@end table

Option processing stops after @samp{--}, or before the first argument
not prefixed by @samp{--}, and remaining arguments are passed to
@code{gen-ovm}.

The following example, when run from the SPECjvm98 directory, will
execute a single iteration of the @code{_213_javac} benchmark:
@example
> mkdir ../ovm-bin
> cd ../ovm-bin
> gen-spec-ovm --spec-dir=../SPECjvm98
> cd ../SPECjvm98
> ../ovm-bin/ovm SpecApplication -s100 _213_javac
@end example

@node Invoking ovm
@chapter Invoking ovm virtual machines

The @command{gen-ovm} command and its wrappers produce virtual machine
executables called @command{ovm}.  Like most Java virtual machines,
@command{ovm} takes command lines that consist vm-specific arguments,
followed by a main class name, and arguments to the main method.

In some cases, the order of vm-specific options is also important.  If
the path to an image file is required, this must be the first argument
to @command{ovm}, and if low-level engine-specific options are
provided, these must appear before all other VM options.  As usual, VM
options must be provided before the application name and arguments.

@section The image file
@cindex image file

An ovm executable consist of two major parts.  A standard executable,
and an initial oject graph.  On elf and mach-O systems, the object
graph is typically embedded into the executable as a non-standard
segment, but sometimes the linker tricks to make this happen break
down.  In such cases, configure complains loudly, and the path to
object graph file, @code{img}, must be explicitly passed to the
virtual machine as the first argument.

@section Engine-specific options

In some execution engines, C code does limited argument processing
before execution of the VM's java implemenation begins.  These
engine-specific options must come before general VM options, but after
the @code{img} file (if needed).

@table @option
@item -v
      Turns on tracing in the interpreter
@item -V
      Turns on more tracing in the interpreter
@item -dump-method-sizes
      Prints the size of each java method compiled by j2c
@end table

@section VM options

@subsection Debugging Options
@table @option
@item -?
@item -help
      Prints a (relatively) short usage message.
@item -panic-delay=@var{seconds}
      When a panic delay of n is specified, the VM will delay for n
      seconds between reporting a panic situation and calling abort.
      This time can be used to attach the running VM process to a
      debugger.
@item -panic-trace
      When set, a stack trace will be printed for every panic.
@item -dumpStacks
      Print a stacktrace of every live thread when SIGUSR1 is received.
@item -dumpEvMan
      Print the state of the event manager when SIGUSR1 is received.
@item -dumpAll
      Print both a stacktrace and the state of the event manager when
      SIGUSR1 is received.
@item -doexectests
      Run low-level regression tests
@item -noforking
      Do not fork a subprocess for each of the regression tests run by
      -doexectests
@end table

@subsection Profiling Options
@table @option
@item -timing
      Measure the time spent in nanoseconds between calling the
      application's main method and final VM exit.
@item -timer-pc-trace-buf-size=@var{size}
      Record the intervals between pollcheck calls up to the specified
      buffer size
@item -pcp-histo-size=@var{max-usec}
      Enables event profiling, and specifies the maximum latency in
      microseconds to include in the latency histogram
@item -pcp-trace-buf=size=@var{n-entries}
      The trace buffer stores the time when each of the last n events
      was received in C code, and the latency before it could be
      handled by an application-level java thread.  This parameter
      controls the buffer's size.
@item -pcp-skip-pa
      Avoid tracing when interrupts are disabled
@end table
      
@subsection Memory Management Options
@table @option
@item -dump-image-profile
      Prints a summary of the initial object graph at startup.
@item -verbose:gc
      Prints an information message at each garbage collection.
@item -diagnose:gc
      Enable GC-related diagnostic checks and debug output.  In the
      mostly-copying collector, this option will detect access to free
      pages, and dump the contents of the heap or another MemoryArea
      when memory is exhausted.
@item -disable-image-barrier
      Disable the mprotect-based write barrier used to speed up root
      scanning.  This option comes in handy when debugging on
      platforms such as MacOS, where the debugger interacts strangley
      with SIGSEGV and SIGBUS handlers.
@end table

RTGC options.  The incremental collector takes a number of runtime
options similar to those IBM's metronome garbage collector:
@table @option
@item -disable-concurrent-gc
@item -gc-stack-uninterruptible
@item -gc-mark-uninterruptible
@item -gc-sweep-uniterruptible
@item -gc-enable-time-trace
@item -profile-alloc
@item -profile-mem-usage
@item -gc-threshold
@item -size-histo
@item -gc-timer-mutator-counts
@end table

@subsection Scheduler Options
@table @option
@item -period=@var{usec}
      Set the timer period in microseconds.  The timer period
      determines the resolution of operations such as timed wait and
      periodic realtime thread release.
@item -period-multiplier=@var{factor}
@item -priority=@var{prio}
      Set the priority of the ovm process itself.  System priorities
      and ovm priorities are independent, and ovm's single kernel
      thread always runs at the priority specified by this option.
@item -pc-max-count=@var{count}
      set the PollcheckManager maxCount.
@end table

@subsection Classpath Options
The system classpath can be defined at runtime, but not changed.  If
@option{-classpath=@var{p}} was given to @command{gen-ovm},
@xref{Invoking gen-ovm}, it can not be overriden after application
classes have been pre-loaded from @var{p}.  If @command{gen-ovm} was
not given a classpath, the search path may be found in several ways

@itemize @bullet
@item 
@option{-classpath @var{p}}, @option{-cp @var{p}}, and
@option{-Djava.class.path=@var{p}} are all equivalent, and
override any default classpath settings.
@item 
If a classpath was not specified on the command line, the 
@code{CLASSPATH} environment variable is checked.
@item
If the classpath is not specified through either the command
line or the environment, a default value of @file{.} is chosen.
@end itemize

@subsection System Properties
Properties can be set with the standard 
@code{-D@var{name}=@var{value}} argument convention.

@section Application Name and Arguments

As with other JVMs, an application class name and arguments can be
provided after all JVM options.  Unlike in most JVMs, the application
name passed to OVM may be optional.  If a main class name was provided
to @command{gen-ovm}, as @samp{gen-ovm -main=@var{C}}, ovm will
replace a main class name of @code{--} with @var{C}.  Furthermore, if
there are no application arguments, the trailing @code{--} argument
may be omitted.  In other words, @samp{ovm @var{C}}, @samp{ovm --},
and @samp{ovm} are all equivalent.

@node Using Ovm
@chapter Using Ovm

This chapter contains a number of hints on how to use Ovm with minimal
pain.  It describes how to reflect on a virtual machine's
configuration, how to do nearly source-level debugging, and how to
configure popular development environments for the ovm kernel.

@menu
* Configuration Properties::   Finding ovm's configuration at runtime
* gdb Tutorial::               Using gdb to debug Java programs
* Eclipse Support::            Using eclipse to debug ovm bootstrapping
* JDE Support::                Using Emacs' JDE mode to write ovm code
@end menu

@c Perhaps this section and the gdb tutorial should be merged under a
@c section called using ovm virtual machines.  There should also be
@c some discussion on how to build reflection lists, and we should
@c start building default simpeljit executables for certain configs

@node Configuration Properties
@section Configuration Properties
Much information about an Ovm virtual machine's configuration is
exposed at runtime through system properties.  The regression test
suite uses configuration properties extensively to avoid testing
non-existent features.  Because these configuration properties may be
useful in other contexts, here is a complete list (as of 5-31-07):

@table @var
@item org.ovmj.supportsGC
@samp{"true"} if garbage will be collected.

@item org.ovmj.supportsFinalizers
@samp{"true"} if finalizers will be called when objects become
unreachable.

@item org.ovmj.supportsAreaOf
@samp{"true"} if Realtime Java's @samp{MemoryArea.getMemoryArea} is
implemented correctly.

@item org.ovmj.supportsScopeChecks
@samp{"true"} if Realtime Java's @samp{IllegalAssignmentError} and
@samp{MemoryAccessError} will be generated on bad memory accesses.

@item org.ovmj.staticBuild
Is @samp{"true"} when dynamic classloading is not supported.

@item org.ovmj.supportsTransactions
Is @samp{"true"} when Preemptible Atomic Regions are available.

@item org.ovmj.timedWaitRunsFast
When this property is @samp{"true"} it indicates an
incompatiblity between the memory manager and the default
implementation of high resolution timers.  The fix seems to involve
choosing a value for @samp{-thread} that uses an alternate high
resolution timer implementation.

@item org.ovmj.boot.class.path
Exposes the search path for ovm's bootstrap classloader.

@item sun.boot.class.path
Exposes the search path for ovm's bootstrap classloader, and is
provided for compatiblity with applications such as bloat.

@item gnu.classpath.home.url
Exposes classpath's resource directory.  Unlike in typical classpath
ports, this is a directory within a jar file.
@end table

@node gdb Tutorial
@section gdb Tutorial

@include gdb-tutorial.texi

@node Eclipse Support
@section Eclipse Support

@include eclipse.texi

@node JDE Support
@section JDE Support

Ovm's makefiles support JDE.  Run @samp{make prj.el} in the
@file{src} directory to create a JDE project file.   You can also run 
@samp{make java-tags} to use tags-search and friends inside emacs.

@node Ovm Internals
@chapter Ovm Internals

Ovm's javadoc documentation (available at @javadoc{}) tends to be
either incomplete, outdated or wildly inaccurate.  For instance,
@pkgdoc{ovm/core/domain} describes an early idea for split between
class and instance types.  This sketch of an implemenation that may
never have existed is in some ways more appealing than the reality of
the code, but of limited use when learning about the current design.

However, some javadoc comments are both current and accurate.  For
instance @pkgdoc{s3/services/bootimage} provides an up-to-date
overview of the VM-generation process.

@c Chapter n
@node Frequently Asked Questions
@chapter Frequently Asked Questions

@include FAQ.texi

@node Index
@unnumbered Index
@printindex cp

@bye
