\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename vmintegration.info
@settitle GNU Classpath VM Integration Guide
@c %**end of header

@setchapternewpage none

@ifinfo
This file contains important information you will need to know if you
are going to write an interface between GNU Classpath and a Virtual
Machine.

Copyright (C) 1998-2002 Free Software Foundation, Inc.

@end ifinfo

@titlepage
@title GNU Classpath VM Integration Guide
@author John Keiser
@author C. Brian Jones
@author Mark Wielaard

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2002 Free Software Foundation, Inc.
@sp 2
Permission is granted to make and distribute verbatim copies of
this document provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
document under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.

@end titlepage

@ifinfo
@node Top, Introduction, (dir), (dir)
@top GNU Classpath Hacker's Guide

This file contains important information you will need to know if you
are going to write an interface between GNU Classpath and a Virtual
Machine.

This document is incomplete, as we are still in alpha with the interface.

@end ifinfo

@menu
* Introduction::                An introduction to the Classpath project
* Initialization::              Initializing the classes
* Classpath Hooks::             Hooks from Classpath to the VM
* VM Hooks::                    Hooks from the underlying VM to Classpath

@end menu

@node Introduction, Initialization, Top, Top
@comment node-name, next, previous, up
@chapter Introduction

The Classpath Project's ambition to be a 100% clean room implementation
of the standard Java class libraries cannot be fulfilled without some
level of integration with the Virtual Machine, the underlying machinery
that actually runs Java.

There are several VMs out there, here is a small list.

@itemize @bullet
@item @uref{http://www.japhar.org,Japhar}
Japhar was the first VM to use GNU Classpath.  Today you can see that
sort of relationship in the source tree which denotes several Japhar
specific files as a reference implementation of those pieces.  This VM
has been primarily tested against Linux and lacks garbage collections, a
JIT, and suffers recently from slow development.

@item @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}
Intel surprised us not long ago with the release of this rather advanced
VM that uses GNU Classpath for a set of class libraries and works on
Linux and Windows 2000.

@item @uref{http://www.sablevm.org/,SableVM}
SableVM is a robust, extremely portable, efficient, and
specifications-compliant Java Virtual Machine that aims to be easy to
maintain and to extend. It features a state-of-the-art, efficient
interpreter engine. Its source code is very accessible and easy to
understand, and has many robustness features that have been the object
of careful design.

@item @uref{http://www.kaffe.org,Kaffe}
Kaffe is an advanced VM and together with its own class libraries
provides a Java 1.1 compatible environment.

@item @uref{http://www.mozilla.org/projects/ef,Electrical Fire}
The Electrical File VM continues to be listed as a Mozilla project
though development has been somewhat quiet.  A number of concepts from
EF were expected at one point to be rolled into Japhar, but that
development has not occured as of yet.

@item @uref{http://latte.snu.ac.kr/,LaTTe}
This VM project so far supports only Sun UltraSparc processors using the
proprietary Solaris 2.5.1 or higher operating system.  LaTTe was derived
from Kaffe but claims a number of improvements.

@item @uref{http://gcc.gnu.org/java/,GNU Compiler for Java (GCJ)}
This is a portable, optimizing, ahead-of-time compiler for the Java
Programming Language. It can compile Java source code directly to native
machine code, Java source code to Java bytecode (class files), and Java
bytecode to native machine code. Compiled applications are linked with the
GCJ runtime, libgcj which is based on the GNU Classpath code, which provides
the core class libraries, a garbage collector, and a bytecode interpreter.
libgcj can dynamically load and interpret class files, resulting in mixed
compiled/interpreted applications.
GCJ is part of the GNU Compiler Collection (@uref{http://gcc.gnu.org/,GCC}).
On march 6 2000 the libgcj and GNU Classpath projects were officially merged
and there is active work on merging all the classes between the projects.

@item @uref{http://kissme.sourceforge.net/,Kissme}
This is a free Java Virtual Machine that is being developed on GNU/Linux
and can run console java applications.  kissme also provides support for
orthogonally persistent java.

@end itemize

In the past integration efforts were focused mainly on Japhar with an eye
towards getting Electrical Fire to work.  Most information contained in
this document is gleaned from these efforts. Recently more work has been
done on getting gcj, orp and kissme to work out of the box with GNU Classpath
but there is much to do before that becomes a reality.


@node Initialization, Classpath Hooks, Introduction, Top
@comment node-name, next, previous, up
@chapter Initialization

The order of initialization, as far as I can tell, doesn't matter just
yet.  However, when we move to 1.2 support, it probably will matter, so
we'll have a note in here at that time.

The current initialization order is currently documented in the
Runtime.java source file.

@node Classpath Hooks, VM Hooks, Initialization, Top
@comment node-name, next, previous, up
@chapter Classpath Hooks

Several core classes must be implemented by the VM for Classpath to
work.  These classes are:

@itemize @bullet
@item java.lang.Class
@item java.lang.Runtime
@item java.lang.Thread
@item java.lang.reflect.Constructor
@item java.lang.reflect.Method
@item java.lang.reflect.Field
@end itemize

You also need to implement some helper classes in java.lang that classes
from Classpath call out to to get certain VM-specific dirty work done:

@itemize @bullet
@item java.lang.VMObject
is the bridge between the low level Object facilities such
as makeing a clone, getting the class of the object and the wait/notify
semantics.
@item java.lang.VMClassLoader
provides methods for defining and resolving core and primitive classes.
@item java.lang.VMSystem
is used to initialize the System properties, the System.arraycopy
method and the identityHashCode of an Object.
@item java.lang.VMSecurityManager
provides the class context (stack trace) of the currently
executing thread and a way to get the currently active ClassLoader.
@item java.lang.VMThrowable
used to hold the VM state of a throwable, created when a Throwable is
created or the fillInStacktrace() method is called, when the actual stack
trace is needed (a lot of exceptions are never actually used), the
getStackTrace() method is used to create a real StackTraceElement array
for the exception.
@end itemize

Some of the classes you implement for the VM will need to call back to
package-private methods in Classpath:

@itemize @bullet
@item java.lang.ThreadGroup.addThread(Thread)
Call this method from Thread when a new Thread is created, to add it to
the group.

@item java.lang.ThreadGroup.removeThread(Thread)
Call this method from Thread when a Thread is stopped or destroyed.

@end itemize


@node VM Hooks,  , Classpath Hooks, Top
@comment node-name, next, previous, up
@chapter VM Hooks

VMs need to do some dirty work; there are some things in the VM that
unfortunately are dependent on the internal structure of various
classes.  This is a guide to all of the things the VM itself needs to
know about classes.

@itemize @bullet
@item java.lang.Class @*
You, the VM, get to create this Class, so you may define the internal
structure any way you wish.  You probably have code somewhere to
translate your internal class structure into a Class object.  That is
the only known place where this matters.  Some VMs do not create the
Class object at the point where the class is defined; instead, they wait
until a Class object is actually used.

@item Array Classes @*
When you are creating an array class, you should set the ClassLoader of
the array class to the ClassLoader of its component type.  Whenever you
add a class to a ClassLoader, you need to notify the ClassLoader and
add the new Class to its internal cache of classes.  To do this, call
ClassLoader.addVMCreatedClass(Class).  @emph{Note: this is written in
anticipation of 1.2 support and does not apply just yet.}

@item Primordial Class Loader @*
When the primordial class loader loads a class, it needs to tell
Classpath what it has done in order for security stuff to work right.
To do this, call the static method
ClassLoader.newPrimordialClass(Class).

Even the first few core classes need to do this; in order to do it,
simply call this method @emph{after} the initial class loading has been
done.  No harm will come, as long as you follow the guidelines in the
@pxref{Initialization} section.

@emph{Note: this is written in anticipation of 1.2 support and does not
apply just yet.}

@item Top-level Exception Handler @*
Exceptions take care of themselves in Classpath; all you need to do in
the top-level exception handler is call Throwable.printStackTrace().

@item Security and Traces @*
There will eventually be a feature in the 1.2 security that keeps the
AccessController from having to evaluate @emph{all} of the
ProtectionDomains every time a security check is made.  I think a common
case is a single method doing a lot of things that require security
checks.  However, I don't want to bog down the method stack too much, so
this feature of the VM will have the AccessController for a thread
calling out to the VM to tell it how high it was on the stack when it
made the last security request.  Every time the stack goes lower than
that number, the VM will decrement the number.  The AccessController
will remember what the accumulated protection status was at every stack
level (an AccessControlContext) and use that aggregated information to
do the check.  I am not sure, however, whether the savings are
substantial enough to outweigh the integer check and set after every
method call.  I will investigate.

@item Threading @*
I figured I'd put this here because a VM guy might be wondering about it.
We implement ThreadGroup, but that class is almost entirely
VM-independent.  The root ThreadGroup, a static field called
ThreadGroup.root, should be initialized by Classpath, but if you wish to
reinitialize it yourself, there should be no harm.

@end itemize


@bye