vmintegration.texinfo

linux下建立JAVA虚拟机的源码KAFFE

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

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

@setchapternewpage off

@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, 2004, 2005 Free Software Foundation, Inc.

@ifnotplaintext
@dircategory GNU Libraries
@direntry
* VM Integration: (vmintegration).   GNU Classpath VM Integration Guide
@end direntry
@end ifnotplaintext
@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
* JNI Implementation::		Hooking the VM to jni.h
* Miscellaneous VM Requirements::  
@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.hungry.com/old-hungry/products/japhar/,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.  As of June, 2004, it does not appear that ORP
is under active development.

@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 occurred 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.
Licensed under GPL+exception, just as GNU Classpath is.

@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.
@c I don't know what ``orthogonally persistent Java'' is, and I bet
@c there are other people don't know either. -- Steve Augart, 4 June 2004

@item @uref{http://jamvm.sourceforge.net/,JamVM}
A simple, small bytecode interpreter that works out-of-the-box with
pure GNU Classpath; it is emerging as the preferred platform for
quickly testing a new build of GNU Classpath.  Licensed under the GPL.

@item @uref{http://oss.software.ibm.com/jikesrvm,Jikes RVM}
A free runtime environment for Java, written in Java.  Works
out-of-the-box with pure GNU Classpath.  Features an optimizing JIT.
Runs on the x86 and PowerPC architectures, on the AIX, Linux, and Mac
OS/X operating systems.  Licensed under the CPL (Common Public
License).  Extensively documented.  Actively developed as of June,
2004.

@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 initialization order is currently documented in the
@file{Runtime.java} source file.

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

The primary method of interaction between Classpath and the VM is via
the helper classes, which are named after the relevant core library
class, but include an additional `VM' prefix.  The library classes from
Classpath call out to these to get certain VM-specific dirty work done.
A reference copy of each VM class exists.  The majority consist of a
series of static methods, some of which are simply declared
@code{native}, and some which provide a default implementation.  VMs may
either use these as is, or create their own local variations.  When
using the default implementations, the VM is responsible for
implementing any of the code marked as @code{native} which corresponds
to functionality they wish their VM to provide.  When using their own
versions of the classes, VM implementors may choose to change the mix of
native and non-native methods from that below, so as to best suit their
implementation.

@menu
* java.lang::
* gnu.classpath::
* java.util::
* java.io::
* java.security::
* java.net::
* java.nio::
* java.nio.channels::
* gnu.java.nio::
* java.lang.reflect::
* Classpath Callbacks::
@end menu

@node java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks
@comment  node-name,  next,  previous,  up

@section @code{java.lang}

@code{java.lang} is the core Java package, being imported automatically by all
classes.  It includes basic classes as @code{Object} and @code{String}.
A VM must implement at least some parts of this package in order to
become operable.

@menu
* java.lang.VMClass::
* java.lang.VMObject::
* java.lang.VMClassLoader::
* java.lang.VMSystem::
* java.lang.VMThrowable::
* java.lang.VMCompiler::
* java.lang.VMDouble::
* java.lang.VMFloat::
* java.lang.VMProcess::
* java.lang.VMRuntime::
* java.lang.VMString::
* java.lang.VMThread::
* java.lang.VMInstrumentationImpl::
* java.lang.VMMath::
@end menu

@node java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang
@subsection @code{java.lang.VMClass}

The core class, @code{java.lang.Class}, and the corresponding VM class,
@code{java.lang.VMClass}, provide two main functions within GNU Classpath.

@enumerate
@item For basic VM operation, @code{java.lang.Class} provides the link between
the Java-based representation of a class it embodies and the VM's own
internal structure for a class.  @xref{VM Hooks}.

@item As far as the user is concerned, the main function of
@code{java.lang.Class} is as an entry point to the reflection
facilities, and so it also provides this functionality, backed by the
VM class.
@end enumerate

This VM class lists the following methods, organized by the version of the
Java specification in which they occur.  All are @code{native}, unless
otherwise specified, and pertain to reflection.  As a result, the VM only
needs to implement these methods in order to provide reflection support,
and then only to the degree required.

@itemize @bullet
@item 1.0
@itemize @bullet
@item @code{isInterface(Class)} -- This is simply a property test, and matches
the presence of an appropriate flag within the class file.
@item @code{getName(Class)} -- Returns the fully-qualified name of the class.
@item @code{getSuperclass(Class)} -- Returns a @code{Class} instance which
represents the superclass.  Again, the class file contains an element directly
relating to this.  @code{null} is returned for primitives, interfaces and
@code{Object}.
@item @code{getInterfaces(Class)} -- Same as the above, but the implemented
or extended interfaces rather than the superclass.  An empty array should
be returned, rather than @code{null}.
@item @code{getDeclaredClasses(Class,boolean)} -- Returns the internal classes
this instance declares directly.  The flag determines whether or not the
VM should filter out non-public classes.
@item @code{getDeclaredFields(Class,boolean)} -- The same for fields.
@item @code{getDeclaredMethods(Class,boolean)} -- And for methods.
@item @code{getDeclaredConstructors(Class,boolean)} -- And constructors.
@item @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance
which is responsible for the specified class.
@item @code{forName(String)} -- The VM should create a @code{Class} instance
corresponding to the named class.  As noted in @ref{VM Hooks}, the internal
content of the instance is the responsibility of the VM.
@item @code{isArray(Class)} -- Another property test, corresponding to a
class file flag.
@item @code{initialize(Class)} -- The VM should initialize the class fully,
if it has not already done so.
@item @code{loadArrayClass(String,ClassLoader)} -- This is called if