obtained gcc-4.6.4.tar.bz2 from upstream website;upstream

verified gcc-4.6.4.tar.bz2.sig;
imported gcc-4.6.4 source tree from verified upstream tarball.

downloading a git-generated archive based on the 'upstream' tag
should provide you with a source tree that is binary identical
to the one extracted from the above tarball.

if you have obtained the source via the command 'git clone',
however, do note that line-endings of files in your working
directory might differ from line-endings of the respective
files in the upstream repository.

1 files changed, 1999 insertions, 0 deletions

diff --git a/libjava/classpath/doc/cp-vmintegration.texinfo b/libjava/classpath/doc/cp-vmintegration.texinfo
new file mode 100644
index 000000000..0b2d78c84
--- /dev/null
+++ b/libjava/classpath/doc/cp-vmintegration.texinfo
@@ -0,0 +1,1999 @@
+\input texinfo @c -*-texinfo-*-
+
+@c %**start of header
+@setfilename cp-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, 2006, 2007 Free Software Foundation, Inc.
+
+@ifnotplaintext
+@dircategory GNU Libraries
+@direntry
+* VM Integration: (cp-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
+* JVMTI Implementation::        Hooking the VM to jvmti.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://jikesrvm.sourceforge.net/,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::
+* gnu.java.lang::
+* gnu.java.lang.management::
+* java.lang.management::
+* 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.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, boolean, ClassLoader)} -- 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@.  The supplied class loader is recorded as that
+which loaded the class, and the boolean specifies whether or not to
+run the class initializer.
+@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
+@code{forName} returns @code{null} and the string specifies an array class.
+The specified array class should be loaded with the supplied class loader.
+@item @code{throwException(Throwable)} -- The VM should throw the supplied
+checked exception, without declaring it.
+@end itemize
+@item 1.1
+@itemize @bullet
+@item @code{isInstance(Class,Object)} -- This is a reflection-based equivalent
+of the @code{instanceof} operator.
+@item @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand for the above,
+removing the need to create an instance to test assignability.  
+@item @code{isPrimitive(Class)} -- Returns true if this class is simply
+a representation of one of the primitive types: @code{boolean}, @code{byte},
+@code{char}, @code{short}, @code{int}, @code{long}, @code{float},
+@code{double} and @code{void}.
+@item @code{getComponentType(Class)} -- Produces a @code{Class} instance which
+represents the type of the members of the array the class instance represents.
+Classes which don't represent an array type return @code{null}.
+@item @code{getModifiers(Class,boolean)} -- Returns an integer which encodes
+the class' modifiers, such as @code{public}.  Again, this relates to
+information stored in the class file.
+@item @code{getDeclaringClass(Class)} -- Returns the class that declared
+an inner or member class, or @code{null} if the instance refers to a top-level
+class.
+@end itemize
+@item 1.5
+@itemize @bullet
+@item @code{isSynthetic(Class)} -- Returns true if the flags for this class
+mark it as synthetic.
+@item @code{isAnnotation(Class)} -- Returns true if the flags for this class
+mark it as an annotation.
+@item @code{isEnum(Class)} -- Returns true if the flags for this class
+mark it as an enumeration.
+@item @code{getSimpleName(Class)} -- Returns the simple name of the class.
+A default implementation is provided, but a more efficient version may instead
+be provided by the VM.
+@item @code{getCanonicalName(Class)} -- Returns the canonical name of the
+class.  A default implementation is provided, but a more efficient
+version may instead be provided by the VM.
+@item @code{getEnclosingClass(Class)} -- Returns the immediately enclosing
+class (null for a top-level class).
+@item @code{getEnclosingConstructor(Class)} -- Returns the constructor
+which immediately encloses the supplied class.
+@item @code{getEnclosingMethod(Class)} -- Returns the method
+which immediately encloses the supplied class.
+@item @code{getClassSignature(Class)} -- Returns the generic signature of
+the class or null if there isn't one.
+@item @code{isAnonymousClass(Class)} -- Returns true if the class is an
+anonymous class.
+@item @code{isLocalClass(Class)} -- Returns true if the class is an
+local class.
+@item @code{isMemberClass(Class)} -- Returns true if the class is an
+member class.
+@end itemize
+@end itemize
+
+@node java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang
+@subsection @code{java.lang.VMObject}
+
+@code{VMObject} is the bridge between the low level @code{Object}
+facilities such as making a clone, getting the class of the object and
+the wait/notify semantics.  This is accomplished using the following
+@code{native} methods.
+
+@itemize @bullet
+@item @code{getClass(Object)} -- Returns the @code{Class} instance for the
+object.  @code{Class} objects are produced by the VM, as described in
+@ref{VM Hooks}.
+@item @code{clone(Cloneable)} -- The VM should produce a low-level clone of the
+specified object, creating a field-by-field shallow copy of the original.
+The only difference between the two is that the new object should still be
+@code{finalizable}, even if the original is not.
+@item @code{notify(Object)} -- The VM should choose one of the threads waiting
+for a lock on the specified object arbitrarily, and wake it.  If the current
+thread does not currently hold the lock on the object, then an
+@code{IllegalMonitorStateException} should be thrown.
+@item @code{notifyAll(Object)} -- Same as the above, but all threads are
+awakened.
+@item @code{wait(Object,long,int)} -- The VM should set the current thread
+into a waiting state, which persists until it receives a notify signal or the
+specified time (in milliseconds and nanoseconds) is exceeded.  The nanoseconds
+restriction may be ignored if such granularity is not available, and a
+@code{IllegalMonitorStateException} should be thrown if the current thread
+doesn't own the object.
+@end itemize
+
+@node java.lang.VMClassLoader, java.lang.VMSystem, java.lang.VMObject, java.lang
+@subsection @code{java.lang.VMClassLoader}
+@code{VMClassLoader} provides methods for defining and resolving core and
+primitive classes, as well as handling resources, packages and assertions.
+The class is a mixture of @code{native} methods and Java-based
+implementations, with some of the latter being @emph{stubs}.
+
+@itemize @bullet
+@item Native Methods
+@itemize @bullet
+@item @code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}
+-- The VM should create a @code{Class} instance from the supplied byte array.
+@item @code{resolveClass(Class)} -- Resolve references to other classes in the
+supplied class.
+@item @code{loadClass(name,boolean)} -- Load a class using the bootstrap
+loader.
+@item @code{getPrimitiveClass(char)} -- The VM should provide a @code{Class}
+implementation for one of the primitive classes.  The supplied character
+matches the JNI code for the primitive class e.g.@: `B' for byte and
+`Z' for boolean.
+@end itemize
+@item Java Methods
+@itemize @bullet
+@item @code{getResource(String)} -- The default implementation calls
+@code{getResources} and returns the first element in the returned enumeration,
+or @code{null} if there are no elements.
+@item @code{getResources(String)} -- By default, this compiles a list of
+URLs via the boot class path.  Any matching files within a zip file are added,
+and directories on the boot class path are automatically converted to file
+URLs that refer to join the directory with the resource name (whether or not
+it actually exists).
+@item @code{getPackage(String)} -- Always returns null, which may be suitable
+if the VM does not wish to return a @code{Package} implementation. Otherwise,
+it may be necessary to make this a @code{native} method.
+@item @code{getPackages()} -- As with the last, a default stub implementation
+exists (returning an empty array) which may be replaced if support is
+required. 
+@item @code{defaultAssertionStatus()} -- A stub which can be implemented
+by VMs providing assertion support.  At present, it always returns @code{true}.
+@item @code{packageAssertionStatus()} -- Much the same status as the above.
+The method should return a map converting package names to boolean status
+values.  The stub implementation provides an empty map.
+@item @code{classAssertionStatus()} -- Same as the last, but for classes.
+@item @code{getSystemClassLoader()} -- The default calls @code{ClassLoader}
+to create a new auxiliary class loader with a system and extension class
+loader.  The VM may wish to replace it if it wishes to supply its own custom
+system class loader.
+@end itemize
+@end itemize
+@node java.lang.VMSystem, java.lang.VMThrowable, java.lang.VMClassLoader, java.lang
+@subsection @code{java.lang.VMSystem}
+@code{VMSystem} handles the default I/O streams, provides access to the
+system clock and environment variables and provides methods for
+@code{System.arraycopy} and the @code{identityHashCode} of an
+@code{Object}.  It consists of @code{native} methods, but the default
+implementation also provides some helper methods to simplify stream
+creation.  
+
+@itemize @bullet
+@item Native Methods
+@itemize @bullet
+@item @code{arraycopy(Object,int,Object,int,int)} -- The VM should copy
+a specified number of array objects from one array to another, with 
+appropriate checks for compatible typing, available elements and space.
+The VM should be able to perform this more efficiently using native code
+and direct memory manipulation than would have been achieved by using Java.
+@item @code{identityHashCode(Object)} -- This is the hashcode for
+@code{Object}, which relates to the actual location of the object in memory.
+@item @code{setIn(InputStream)} -- Set the system input stream.
+@item @code{setOut(PrintStream)} -- Set the system output stream.
+@item @code{setErr(PrintStream)} -- Set the system error stream.
+@item @code{currentTimeMillis()} -- Gets the system time in milliseconds.
+@item @code{getenv(String)} -- Returns the value of the specified environment
+variable.
+@item @code{getenv()} -- Returns a list of `name=value' pairs which correspond
+to the environment variables.
+@end itemize
+@item Java Methods
+@itemize @bullet
+@item @code{makeStandardInputStream()} -- Helps provide the functionality of
+@code{System.in} by wrapping the appropriate file descriptor in a
+buffered file input stream.  VMs may choose to create the stream from
+the descriptor differently rather than using this method.
+@item @code{makeStandardOutputStream()} -- Helps provide the functionality of
+@code{System.out} by wrapping the appropriate file descriptor in a buffered
+file output stream.  VMs may choose to create the stream from the descriptor
+differently rather than using this method.
+@item @code{makeStandardErrorStream()} -- Helps provide the functionality of
+@code{System.err} by wrapping the appropriate file descriptor in a buffered
+file output stream.  VMs may choose to create the stream from the descriptor
+differently rather than using this method.
+@end itemize
+@end itemize
+
+Classpath also provides native implementations of
+
+@itemize @bullet
+@item @code{setIn(InputStream)} 
+@item @code{setOut(PrintStream)} 
+@item @code{setErr(PrintStream)} 
+@item @code{currentTimeMillis()} 
+@item @code{getenv(String)}
+@end itemize
+
+making a VM implementation optional.
+
+@node java.lang.VMThrowable, java.lang.VMCompiler, java.lang.VMSystem, java.lang
+@subsection @code{java.lang.VMThrowable}
+@code{VMThrowable} is used to hold the VM state of a throwable, created either
+when a @code{Throwable} is created or the @code{fillInStackTrace()} method is
+called (i.e., when the actual stack trace is needed, as a lot of exceptions are
+never actually used).  The actual class has two @code{native} methods,
+one (@code{fillInStackTrace()}) being a method of the class used to obtain
+instances, and the other an instance method, @code{getStackTrace()}.
+@itemize @bullet
+@item @code{fillInStackTrace(Throwable)} -- The VM should return the current
+execution state of the @code{Throwable} in the form of a @code{VMThrowable}
+instance.  The VM may also return @code{null} if it does not support this
+functionality.
+@item @code{getStackTrace()} -- This is used to create a real
+@code{StackTraceElement} array for the exception, using the state data
+stored during creation of the instance.
+@end itemize
+
+@node java.lang.VMCompiler, java.lang.VMDouble, java.lang.VMThrowable, java.lang
+@subsection @code{java.lang.VMCompiler}
+
+@code{VMCompiler} provides an interface for VMs which wish to provide
+JIT compilation support.  The default implementation is simply a series
+of stubs. The property, @code{java.compiler}, should point to a library
+containing the function @code{java_lang_Compiler_start()} if such support
+is to be provided.
+
+@itemize @bullet
+@item @code{compileClass(Class)} -- Invoke the compiler to compile the specific
+class, returning @code{true} if successful.
+@item @code{compileClasses(String)} -- The compiler should compile the classes
+matching the specified string, again returning @code{true} on success.
+@item @code{command(Object)} -- The object represents a command given to the
+compiler, and is specific to the compiler implementation.
+@item @code{enable} -- Enable the operation of the compiler.
+@item @code{disable} -- Disable compiler operation.
+@end itemize
+
+@node java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler, java.lang
+@subsection @code{java.lang.VMDouble}
+
+@code{VMDouble} provides native support for the conversion and parsing
+of doubles.
+
+@itemize @bullet
+@item @code{doubleToRawLongBits(double)} -- Converts the double to the IEEE 754
+bit layout, preserving NaNs.
+@item @code{longBitsToDouble(long)} -- This is the inverse of the last method,
+preserving NaNs so that the output of one can be fed into the other without
+data loss.
+@item @code{toString(double,boolean)} -- Converts the double to a string,
+giving a shorter value if the flag @code{isFloat} is @code{true}, indicating
+that the conversion was requested by @code{java.lang.Float} rather than
+@code{java.lang.Double}.
+@item @code{initIDs} -- Used by JNI-based solutions to initialize the cache
+of the static field IDs.  The default @code{VMDouble} implementation has a
+static initializer which loads the JNI library and calls this method.
+@item @code{parseDouble} -- Turn the string into a usable double value.
+@end itemize
+
+Classpath provides native implementations of all these, making VM
+implementation optional.
+
+@node java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble, java.lang
+@subsection @code{java.lang.VMFloat}
+
+@code{VMFloat} provides native support for the conversion of floats.
+
+@itemize @bullet
+@item @code{floatToRawIntBits(float)} -- Converts the float to the IEEE 754
+bit layout, preserving NaNs.
+@item @code{intBitsToFloat(int)} -- This is the inverse of the last method,
+preserving NaNs so that the output of one can be fed into the other without
+data loss.
+@end itemize
+
+Classpath provides native implementations of all these, making VM
+implementation optional.
+
+@node java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat, java.lang
+@subsection @code{java.lang.VMProcess}
+
+@code{VMProcess} handles the execution of external processes.  In the
+default implementation, threads are spawned and reaped by @code{ProcessThread}.
+A constructor creates a new @code{VMProcess}, which extends rather than
+complements @code{Process}, using an array of arguments, an array of
+environment variables and a working directory.  The instance maintains
+system input, output and error streams linked to the external process.
+Three @code{native} methods are used, and implementations are provided
+for all three by Classpath, making VM implementation optional.  These use
+the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.
+
+@itemize @bullet
+@item @code{nativeSpawn(String[],String[],File,boolean)} -- The VM should
+create a new process which uses the specified command-line arguments,
+environment variables and working directory.  Unlike the other two
+methods, this method is linked to an instance, and must call
+@code{setProcessInfo()} with the results before returning.  The
+boolean argument maps to the @code{redirectErrorStream} property of
+@code{java.lang.ProcessBuilder}.  When true, the output and error streams
+are merged.
+@item @code{nativeReap()} -- This is called to perform a reap of any
+zombie processes, and should not block, instead returning a boolean as to
+whether reaping actually took place.
+@item @code{nativeKill(long)} -- The VM should terminate the specified PID.
+@end itemize
+
+@node java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess, java.lang
+@subsection @code{java.lang.VMRuntime}
+
+The @code{VMRuntime} class provides a series of native methods
+which divulge information about the runtime or invoke certain
+operations.  This includes retrieving the amount of available memory,
+and scheduling the garbage collector.  There are two exceptions: the
+@code{enableShutdownHooks} method, which allows the VM to put in its own
+shutdown hooks when @code{Runtime.addShutdownHook()} is first invoked,
+and @code{exec(String[],String[],File)} which spawns an external process.
+These are Java-based static methods instead.  The first is simply a stub by
+default, while the second simply links to the functionality of
+@code{VMProcess} (and should be changed if a different @code{Process}
+implementation is used).
+
+@itemize @bullet
+@item @code{availableProcessors()} -- Returns the number of processors 
+available to the VM.
+@item @code{freeMemory()} -- Returns the amount of memory the VM has available
+on the heap for allocating.
+@item @code{totalMemory()} -- Returns the size of the heap.
+@item @code{maxMemory()} -- Returns the maximum memory block the VM will
+attempt to allocate.  May be simply @code{Long.MAX_VALUE} (8 exabytes!)
+@item @code{gc()} -- Allows users to explicitly invoke the garbage collector.
+This is a suggestion to the VM, rather than a command, and the garbage
+collector should run anyway @emph{without} it being invoked.
+@item @code{runFinalization()} -- Like the above, but related to the
+finalilzation of objects rather than the garbage collector.
+@item @code{runFinalizationForExit()} -- Called immediately prior to VM
+shutdown in order to finalize all objects (including `live' ones)
+@item @code{traceInstructions(boolean)} -- This turns on and off the optional
+VM functionality of printing a trace of executed bytecode instructions.
+@item @code{traceMethodCalls(boolean)} -- This turns on and off the optional
+VM functionality of printing a trace of methods called.
+@item @code{runFinalizersOnExit(boolean)} -- A toggleable setting for
+running the finalization process at exit.
+@item @code{exit(int)} -- The VM should shutdown with the specified exit code.
+@item @code{nativeLoad(String,ClassLoader)} -- Attempts to load a file,
+returning an integer which is non-zero for success.  Nothing happens if the
+file has already been loaded.
+@item @code{mapLibraryName(String)} -- The VM should map the system-independent
+library name supplied to the platform-dependent equivalent (e.g.@: a @code{.so}
+or @code{.dll} file)
+@end itemize
+
+@node java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime, java.lang
+@subsection @code{java.lang.VMString}
+@code{VMString} is responsible for handling interned strings.  If two strings
+are equal (using the @code{equals()} method), then the results of calling
+the @code{intern()} method on each of them makes them equal
+(using @code{==}).  Thus, the same string object is always returned by
+@code{intern} if the two strings are equal.  The default implementation
+is Java-based and implements @code{intern(String)} by maintaining a
+@code{WeakHashMap} which links the strings to their @code{WeakReference}.
+A new mapping is created for each new string being @code{intern}ed.  
+A VM may implement this differently by implementing this method,
+which is @code{static} and the only one in @code{VMString}.
+
+@node java.lang.VMThread, java.lang.VMMath, java.lang.VMString, java.lang
+@subsection @code{java.lang.VMThread}
+
+@code{VMThread} provides the link between Java's threads and the platform
+threading support.  A @code{VMThread} is created via a private constructor
+and linked to a @code{Thread} instance.  This occurs when the @code{Thread}
+instance is started by the static @code{create(Thread,long)} method (the second
+argument requests a certain stack size, usually zero).  The thread itself is
+executed via the @code{run()} method, which handles any problems with the
+running of the thread and its eventual death.
+
+@code{VMThread} provides the following accessors and mutators for accessing
+the thread state via @code{VMThread},
+
+@itemize @bullet
+@item @code{getName()}
+@item @code{setName(String)}
+@item @code{getPriority()}
+@item @code{setPriotity(int)}
+@item @code{isDaemon()}
+@end itemize
+
+all of which refer to the @code{Thread} instance. @code{setPriority(int)} also
+calls the appropriate native method.  @code{stop(Throwable)} similarly wraps
+a native method, merely adding in a check for the state of the thread.
+
+The default implementation also provides Java-based implementations of
+@code{join(long,int)}, @code{sleep(long,int)} and
+@code{holdsLock(Object)}.  @code{join} and @code{sleep} simply wait for
+the appropriate amount of time, with @code{join} additionally waiting
+for the thread instance to become @code{null}.  @code{holdsLock} simply
+checks if an object is locked by the current thread by trying to invoke
+the @code{notify} method, and catching the failing exception if this is
+not the case.
+
+The remainder of the class is a series of @code{native} methods, some of
+which are mandatory for VM implementation and others which provide optional
+or deprecated functionality.
+
+@itemize @bullet
+@item Mandatory Instance Methods
+@itemize @bullet
+@item @code{start(long)} -- The VM should create the native thread and start
+it running using the @code{run} method of the @code{VMThread} instance on
+which this method is called.
+@item @code{interrupt()} -- The VM should interrupt the running thread and
+throw an appropriate exception.
+@item @code{isInterrupted()} -- Checks the interrupted state of the thread.
+@item @code{suspend()} -- The thread should be suspended until resumed.
+@item @code{resume()} -- The thread should be resumed from its suspended state.
+This pair of methods are deprecated, due to the possibility of a deadlock
+occurring when a thread with locks is suspended.
+@item @code{nativeSetPriority(int)} -- Called by @code{setPriority}
+to allow the setting to flow down to the native thread.
+@item @code{nativeStop(Throwable)} -- The VM should stop the thread abnormally
+and throw the specified exception.  This is clearly deprecated, due to the
+ambiguous state an abruptly-stopped thread may leave.
+@item @code{getState()} -- Returns the VM's impression of the current state
+of the thread.  The applicable states are supplied by the @code{State}
+enumeration in @code{java.lang.Thread}.
+@end itemize
+@item Mandatory Class Methods
+@itemize @bullet
+@item @code{currentThread()} -- Return a reference to the thread currently
+being executed.
+@item @code{yield()} -- The VM should allow some other thread to run.
+The current thread maintains its locks even though it stops executing for
+the time being.
+@item @code{interrupted()} -- A shortcut to obtaining the interrupted state
+of the current thread.
+@end itemize
+@item Other Methods
+@itemize @bullet
+@item @code{countStackFrames()} -- Returns a count of the number of stack
+frames in the thread.  This depends on the deprecated method @code{suspend()}
+having returned true, and is thus deprecated as a result.
+@end itemize
+@end itemize
+
+@node java.lang.VMMath,, java.lang.VMThread, java.lang
+@subsection @code{java.lang.VMMath}
+
+The @code{VMMath} class provides a series of native methods
+for some of the mathematical functions present in @code{java.lang.Math}.
+Classpath provides a default implementation of these which maps the
+functions to those provided by @code{fdlibm}.  VM implementors are welcome
+to replace this with more efficient implementations, as long as the accuracy
+contract of these methods, specified in @code{java.lang.Math}, is maintained.
+
+@itemize @bullet
+@item 1.0
+@itemize @bullet
+@item @code{sin(double)} -- Returns the sine value for the given angle.
+@item @code{cos(double)} -- Returns the cosine value for the given angle.
+@item @code{tan(double)} -- Returns the tangent value for the given angle.
+@item @code{asin(double)} -- Returns the arc sine value for the given angle.
+@item @code{acos(double)} -- Returns the arc cosine value for the given angle.
+@item @code{atan(double)} -- Returns the arc tangent value for the given angle.
+@item @code{atan2(double,double)} -- Returns the arc tangent of the ratio of
+the two arguments.
+@item @code{exp(double)} -- Returns the exponent raised to the given power.
+@item @code{log(double)} -- Returns the natural logarithm for the given value.
+@item @code{sqrt(double)} -- Returns the square root of the value.
+@item @code{pow(double,double)} -- Returns x to the power of y.
+@item @code{IEEEremainder(double,double)} -- Returns the IEEE 754 remainder
+for the two values.
+@item @code{ceil(double)} -- Returns the nearest integer >= the value.
+@item @code{floor(double)} -- Returns the nearest integer <= the value.
+@item @code{rint(double)} -- Returns the nearest integer or the even one
+if the distance between the two is equal.
+@end itemize
+@item 1.5
+@itemize @bullet
+@item @code{cbrt(double)} -- Returns the cube root of the value.
+@item @code{cosh(double)} -- Returns the hyperbolic cosine value for the given
+angle.
+@item @code{expm1(double)} -- Returns the exponent of the value minus one.
+@item @code{hypot(double,double)} -- Returns the hypotenuse corresponding to
+x and y.
+@item @code{log10(double)} -- Returns the base 10 logarithm of the given value.
+@item @code{log1p(double)} -- Returns the natural logarithm of the value plus
+one.
+@item @code{sinh(double)} -- Returns the hyperbolic sine value for the given
+angle.
+@item @code{tanh(double)} -- Returns the hyperbolic tangent value for the given angle.
+@end itemize
+@end itemize
+
+@node gnu.classpath, java.util, java.lang, Classpath Hooks
+@section @code{gnu.classpath}
+
+The @code{gnu.classpath} package provides Classpath-specific functionality,
+primarily relating to the features in @code{java.lang}.  At present, this
+includes the context of a class (the stack) and the system properties.
+
+@menu
+* gnu.classpath.VMStackWalker::
+* gnu.classpath.VMSystemProperties::
+* gnu.classpath.Unsafe::
+@end menu
+
+@node gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
+@subsection @code{gnu.classpath.VMStackWalker}
+
+@code{VMStackWalker} provides access to the class context or stack.  The
+default implementation consists of a @code{native} @code{static} method,
+@code{getClassContext()}, which obtains the class context, and two helper
+methods which obtain the calling class (the 3rd element in the context array)
+and its class loader, respectively.
+
+@itemize @bullet
+@item @code{getClassContext()} -- The VM should return an array of
+@code{Class} objects, each of which relates to the method currently being
+executed at that point on the stack.  Thus, the first item (index 0) is the
+class that contains this method.
+@item @code{getCallingClass()} -- A Java-based helper method which returns
+the @code{Class} object which contains the method that called the method
+accessing @code{getCallingClass()}. 
+@item @code{getCallingClassLoader()} -- Like the last, but returning the class
+loader of the class.
+@end itemize
+
+@node gnu.classpath.VMSystemProperties,gnu.classpath.Unsafe,gnu.classpath.VMStackWalker,gnu.classpath
+@subsection @code{gnu.classpath.VMSystemProperties}
+
+@code{VMSystemProperties} allows the VM to hook into the property creation
+process, both before and after the system properties are added by GNU
+Classpath.  The default implementation assumes that the VM will add its
+properties first, by making the pre-initialisation method @code{native},
+and that the Classpath properties may then be altered by a Java-based
+post-initialisation method.
+
+As these methods are called as part of the bootstrap process, caution should
+be used as to what classes are used, and properties should only be set
+using @code{Properties.setProperty()}.  Specifically, I/O classes should be
+avoided at this early stage.
+
+@itemize @bullet
+@item @code{preInit(Properties)} -- Allows the VM to add properties
+@emph{before} the Classpath properties are added. The default implementation
+includes a full list of properties that @emph{must} be added by the VM, but
+additional VM-specific ones may also be added.  
+@item @code{postInit(Properties)} -- Same as the last, but called after the
+Classpath properties have been added.  The main purpose of this is to allow
+the VM to alter the properties added by GNU Classpath to suit it.
+@end itemize
+
+@node gnu.classpath.Unsafe,,gnu.classpath.VMSystemProperties,gnu.classpath
+@subsection @code{gnu.classpath.Unsafe}
+
+The @code{Unsafe} class provides access to some low-level unsafe operations
+as required by the addition of the java.util.concurrent classes.  These
+focus on direct memory access to the fields within the VM and providing
+atomic update methods.
+
+@itemize @bullet
+@item @code{objectFieldOffset(Field)} -- Provides the caller with the memory
+offset of a particular field.
+@item @code{compareAndSwap*(Object,long,*,*)} -- One of these methods is
+provided for each of int, long and Object (hence the *s).  The value of
+a field pointed to by the given Object and offset is compared with the
+first value and replaced with the second if they are the same.  The reason
+for this method is to make this change operation atomic.
+@item @code{put/get*(Object,long,*)} -- These are like the last set of
+methods, handling integers, longs and Objects, but the field is always
+changed on a put.  Different methods are provided for different semantics.
+Ordered variants perform a lazy put, in that the change does not
+immediately propogate to other threads, while the others provide
+volatile or 'normal' semantics.
+@item @code{arrayBaseOffset(Class)} and @code{arrayIndexScale(Class)} --
+These two methods allow an array class to be traversed by pointer
+arithmetic, by gaining the address of the first element and then
+scaling appropriately for the later ones.
+@item @code{park(boolean,long)} and @code{unpark(Thread)} -- These methods
+block and unblock threads respectively, with an optional timeout being
+provided for the blocking.  @code{unpark} is unsafe as the thread may have
+been destroyed by native code. 
+@end itemize
+
+@node java.util, java.io, gnu.classpath, Classpath Hooks
+@section java.util
+
+The @code{java.util} VM hooks provide links between the mix of functionality
+present in that package, which includes collections, date and time handling
+and parsing.  At present, there is only one hook, which connects GNU Classpath
+to the timezone information provided by the underlying platform.
+
+@menu
+* java.util.VMTimeZone::
+@end menu
+
+@node java.util.VMTimeZone,,java.util,java.util
+@subsection @code{java.util.VMTimeZone}
+
+@code{VMTimeZone} joins @code{TimeZone} to the platform timezone information
+via the static method, @code{getDefaultTimeZoneId()}.  The VM hook is
+expected to return a @code{TimeZone} instance that represents the current
+timezone in use by the platform.  The default implementation provides
+this functionality for POSIX or GNU-like systems, and VMs that want this
+functionality can keep this implementation and implement the native
+method, @code{getSystemTimeZoneId()}.  This method is only called when
+obtaining the timezone name from the @code{TZ} environment variable,
+@code{/etc/timezone} and @code{/etc/localtime} all fail.  This fallback
+mechanism also means that a system which doesn't provide the above three
+methods, but does provide a timezone in string form, can still use this
+implementation.
+
+@node java.io, java.security, java.util, Classpath Hooks
+@section java.io
+
+The @code{java.io} package is heavily reliant on access to the I/O facilities
+of the underlying platform.  As far as its VM hooks go, they provide two
+areas of functionality to GNU Classpath, these being
+
+@itemize @bullet
+@item File and directory queries and manipulation
+@item Serialization of objects
+@end itemize
+
+The first corresponds directly to most of the @code{File} class, while
+the latter underlies the functionality provided by the
+@code{ObjectInputStream} and @code{ObjectOutputStream}.  More low-level I/O
+is provided by @ref{java.nio}.
+
+@menu
+* java.io.VMFile::
+* java.io.VMObjectInputStream::
+* java.io.VMObjectStreamClass::
+@end menu
+
+@node java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
+@subsection @code{java.io.VMFile}
+
+@code{VMFile} allows GNU Classpath's @code{File} representations to
+probe and modify the file system using the native functions of the
+platform.  The default implementation (which consists of both a
+@code{VMFile} class and the native methods) is primarily UNIX-centric,
+working with POSIX functions and assuming case-sensitive filenames,
+without the restriction of the 8.3 format.  It consists mainly of
+@code{static} @code{native} methods, with a few Java helper methods.
+The native methods represent the file as a string containing its path,
+rather than using the object itself.
+
+@itemize @bullet
+@item Native Methods
+@itemize @bullet
+@item @code{lastModified(String)} -- The native method should return a
+@code{long} value that represents the last modified date of the file.
+@item @code{setReadOnly(String)} -- Sets the file's permissions to read only,
+in whichever way this is realised by the platform.
+@item @code{create(String)} -- Create the named file.
+@item @code{list(String)} -- The native method opens the named directory,
+reads the contents and returns them as a Java @code{String} array.
+@item @code{renameTo(String,String)} -- Renames the first file to the second.
+@item @code{length(String)} -- Returns a @code{long} value representing
+the file size.
+@item @code{exists(String)} -- Tests for the existence of the named file
+or directory.
+@item @code{delete(String)} -- Deletes the file or directory.
+@item @code{setLastModified(String,long)} -- Change the last modified time.
+@item @code{mkdir(String)} -- Creates the named directory.
+@item @code{isFile(String)} -- Tests that the named path references a file.
+@item @code{canWrite(String)} -- Tests that the file can be written to.
+This method is @code{synchronized}, so the object is locked during the check.
+@item @code{canRead(String)} -- Complement of the last method.
+@item @code{isDirectory(String)} -- Tests that the named path references
+a directory.
+@end itemize
+@item Java Helper Methods
+@itemize @bullet
+@item @code{canWriteDirectory(File)} -- Checks that the directory can be
+written to, by trying to create a temporary file in it.
+@item @code{listRoots()} -- Returns the root of a GNU filesystem, i.e.@: `/'
+in an array.
+@item @code{isHidden(String)} -- Checks whether the file starts with `.',
+which is how files are hidden on UNIX-style systems.
+@item @code{getName(String)} -- Pulls the actual filename from the end of
+the path, by breaking off the characters after the last occurrence of the
+platform's file separator.
+@item @code{getCanonicalForm(String)} -- This converts a UNIX path to
+its canonical form by removing the `.' and `..' sections that occur within.
+@end itemize
+@end itemize
+
+@node java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
+@subsection @code{java.io.VMObjectInputStream}
+
+This class consists of two methods which provide functionality used in
+deserializing an object.  @code{currentClassLoader()} provides the first
+user-defined class loader from the class context
+(@xref{gnu.classpath.VMStackWalker},) via a @code{PrivilegedAction}.
+@code{allocateObject(Class,Class,Constructor)} is a @code{native} method
+(a reference implementation is provided) which creates an object but
+calls the constructor of another class, which is a superclass of the
+object's class.
+
+@node java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
+@subsection @code{java.io.VMObjectStreamClass}
+
+@code{VMObjectStreamClass} is a series of @code{static} @code{native}
+methods that provide some of the groundwork for @code{ObjectStreamClass}
+and @code{ObjectStreamField}.  @code{hasClassInitializer(Class)} works
+with the former, and checks for the presence of a static initializer.
+The remaining methods are of the form @code{setXXXNative(Field,Object,XXX)}
+and support @code{ObjectStreamField}.  One exists for each of the main types
+(boolean, float, double, long, int, short, char, byte and object) and is used
+to set the specified field in the supplied instance to the given value.
+
+A default implementation is provided for all of them, so a VM implementation
+is optional.
+
+@node java.security, java.net, java.io, Classpath Hooks
+@section java.security
+
+The @code{java.security} package provides support for Java's security
+architecture.  
+
+@menu
+* java.security.VMAccessController::
+* java.security.VMSecureRandom::
+@end menu
+
+@node java.security.VMAccessController,java.security.VMSecureRandom,java.security,java.security
+@subsection @code{java.security.VMAccessController}
+
+The @code{AccessController} is used to perform privileged actions.  Its
+hook class, @code{VMAccessController}, maintains the
+@code{AccessControlContext} and the default implementation is purely
+Java-based.  The VM may choose to replace this with their own.
+The methods in the reference version are as follows:
+
+@itemize @bullet
+@item @code{pushContext(AccessControlContext)} -- Adds a new context to the
+stack for the current thread.  This is called before a privileged action
+takes place.
+@item @code{popContext()} -- Removes the top context from the stack.  This
+is performed after the privileged action takes place.
+@item @code{getContext()} -- Either derives a context based on the 
+@code{ProtectionDomain}s of the call stack (see the next method) or returns
+the top of the context stack.
+@item @code{getStack()} -- Provides access to the call stack as a pair of
+arrays of classes and method names.  The actual implementation returns
+an empty array, indicating that there are no permissions.
+@end itemize
+
+@node java.security.VMSecureRandom,,java.security.VMAccessController,java.security
+@subsection @code{java.security.VMSecureRandom}
+
+The @code{VMSecureRandom} class is used to provide access to
+cryptographically secure random numbers.  The default implementation
+of the class runs eight threads that increment counters in a tight
+loop, and XORs each counter to produce one byte of seed data. This is
+not very efficient, and is not guaranteed to be random (the thread
+scheduler is probably deterministic, after all). VM implementors
+should provide a version of this class, which implements the method
+@code{generateSeed(byte[],int,int)}, so that it fills the buffer using
+a random seed from a system facility, such as a system entropy
+gathering device or hardware random number generator.  The parameters
+are the usual set of buffer, offset and length and the method returns
+the number of bytes actually generated, which may be less than that
+requested.
+
+@node java.net, java.nio, java.security, Classpath Hooks
+@section java.net
+
+The @code{java.net} package is heavily reliant on access to the networking
+facilities of the underlying platform.  The VM hooks provide information
+about the available network interfaces, and access to lookup facilities
+for network addresses.
+
+@menu
+* java.net.VMInetAddress::
+* java.net.VMNetworkInterface::
+@end menu
+
+@node java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
+@subsection @code{java.net.VMInetAddress}
+
+@code{VMInetAddress} is a series of @code{static} @code{native} methods
+which provide access to the platform's lookup facilities.  All the methods
+are implemented by GNU Classpath, making VM implementation optional, and
+are as follows:
+
+@itemize @bullet
+@item @code{getLocalHostname()} -- Wraps the @code{gethostname} function, and
+falls back on `localhost'.
+@item @code{lookupInaddrAny()} -- Returns the value of @code{INADDR_ANY}.
+@item @code{getHostByAddr(byte[])} -- Looks up the hostname based on an IP
+address.
+@item @code{getHostByName(String)} -- The reverse of the last method, it
+returns the IP addresses which the given host name resolves to.
+@end itemize
+
+@node java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
+@subsection @code{java.net.VMNetworkInterface}
+
+@code{VMNetworkInterface} currently consists of a single @code{static}
+@code{native} method, @code{getInterfaces()}, which retrieves the
+network interfaces available on the underlying platform as a @code{Vector}.
+The current GNU Classpath implementation is a native stub.
+
+@node java.nio, java.nio.channels, java.net, Classpath Hooks
+@section java.nio
+
+The @code{java.nio} package is part of the New I/O framework added in
+Java 1.4.  This splits I/O into the concepts of @emph{buffers},
+@emph{charsets}, @emph{channels} and @emph{selectors}, and
+@code{java.nio} defines the buffer classes.  As far as native and VM
+code is concerned, the new package needs support for low-level efficient
+buffer operations.
+
+@menu
+* java.nio.VMDirectByteBuffer::
+@end menu
+
+@node java.nio.VMDirectByteBuffer,,java.nio,java.nio
+@subsection @code{java.nio.VMDirectByteBuffer}
+
+A @code{ByteBuffer} maintains a buffer of bytes, and allows it to be
+manipulated using primitive operations such as @code{get}, @code{put},
+@code{allocate} and @code{free}.  A direct buffer avoids intermediate
+copying, and uses native data which shouldn't be manipulated by a
+garbage collector.  The VM class consists of @code{static} @code{native}
+methods, all of which are given default implementations by GNU
+Classpath.
+
+@itemize @bullet
+@item @code{init()} -- Creates an instance of an appropriate
+@code{gnu.classpath.RawData} class.  This class is not garbage
+collected, is created natively and is used in the other methods to reference
+the buffered data.
+@item @code{allocate(int)} -- Allocates the memory for the buffer using
+@code{malloc} and returns a reference to the @code{RawData} class.
+@item @code{free(RawData)} -- Frees the memory used by the buffer.
+@item @code{get(RawData,int)}  -- Returns the data at the specified index.
+@item @code{get(RawData,int,byte[],int,int)} -- Copies a section of the
+data into a byte array using @code{memcpy}.
+@item @code{put(RawData,int,byte)} -- Puts the given data in the buffer
+at the specified index.
+@item @code{adjustAddress(RawData,int)} -- Adjusts the pointer into the buffer.
+@item @code{shiftDown(RawData,int,int,int)} -- Moves the content of the buffer
+at an offset down to a new offset using @code{memmove}.
+@end itemize
+ 
+@node java.nio.channels, gnu.java.nio, java.nio, Classpath Hooks
+@section java.nio.channels
+
+Channels provide the data for the buffers with the New I/O packages.
+For example, a channel may wrap a file or a socket.  The VM hooks,
+at the moment, simply allow the channels to be accessed by @code{java.io}
+streams.
+
+@menu
+* java.nio.channels.VMChannels::
+@end menu
+
+@node java.nio.channels.VMChannels,,java.nio.channels,java.nio.channels
+@subsection @code{java.nio.channels.VMChannels}
+
+@code{VMChannels} provides the methods that create the channels or
+streams.  The default implementation is in pure Java and simply wraps
+the channels in standard I/O classes from @code{java.io}.
+
+@itemize @bullet
+@item @code{createStream(Class,Channel)} -- Creates a @code{FileChannel}
+which wraps an instance of the specified stream class, created by reflection.
+This method is private, and is used by the other two.
+@item @code{newInputStream(ReadableByteChannel)} -- Wraps the channel
+in a @code{FileInputStream}.
+@item @code{newOutputStream(WritableByteChannel)} -- Wraps the channel
+in a @code{FileOutputStream}.
+@end itemize
+
+@node gnu.java.nio, java.lang.reflect, java.nio.channels, Classpath Hooks
+@section gnu.java.nio
+
+The @code{gnu.java.nio} class provides Classpath implementations of the
+interfaces provided by @code{java.nio}.  The VM classes provide the native
+support necessary to implement @emph{pipes} and @emph{selectors}.
+
+@menu
+* gnu.java.nio.VMPipe::
+* gnu.java.nio.VMSelector::
+@end menu
+
+@node gnu.java.nio.VMPipe,gnu.java.nio.VMSelector,gnu.java.nio,gnu.java.nio
+@subsection @code{gnu.java.nio.VMPipe}
+
+@code{VMPipe} provides the native functionality for a uni-directional pipe
+between a source and a destination (sink) channel.  It consists of one 
+@code{static} @code{native} method, @code{init(PipeImpl,SelectorProvider)},
+the reference implementation of which is currently a native stub.  Ideally,
+this should initialise the pipe at the native level.
+
+@node gnu.java.nio.VMSelector,,gnu.java.nio.VMPipe,gnu.java.nio
+@subsection @code{gnu.java.nio.VMSelector}
+
+A @code{Selector} selects between multiple @code{SelectableChannel}s based
+on their readiness and a key set.  The VM hook for the Classpath implementation
+of this is @code{VMSelector}, and this allows the actual @code{select()}
+operation to be performed.  This is represented by the @code{static}
+@code{native} method, @code{select(int[],int[],int[],long)}, and a default
+implementation of this is provided.
+
+@node java.lang.reflect, gnu.java.lang, gnu.java.nio, Classpath Hooks
+@section @code{java.lang.reflect}
+@code{java.lang.reflect} provides the interface to Java's reflection
+facilities.  Via reflection, programmers can obtain type information about
+a particular instance at runtime or dynamically create new instances.
+
+@menu
+* java.lang.reflect.VMArray::
+@end menu
+
+@node java.lang.reflect.VMArray,,,java.lang.reflect
+@subsection @code{java.lang.reflect.VMArray}
+
+The @code{VMArray} class provides a hook, @code{createObjectArray},
+which the VM uses to generate a new non-primitive array of a
+particular class and size.  The default implementation simply passes
+the job down to the standard JNI function, @code{NewObjectArray}.
+
+@node gnu.java.lang, gnu.java.lang.management, java.lang.reflect, Classpath Hooks
+@section @code{gnu.java.lang}
+
+@code{gnu.java.lang} provides VM interfaces for the GNU
+implementations of features in java.lang.  Currently, this includes the
+implementation of instrumentation.
+
+@menu
+* gnu.java.lang.VMInstrumentationImpl::
+@end menu
+
+@node gnu.java.lang.VMInstrumentationImpl,,,gnu.java.lang
+@subsection @code{gnu.java.lang.VMInstrumentationImpl}
+
+The @code{gnu.java.lang.VMInstrumentationImpl} and
+@code{gnu.java.lang.InstrumentationImpl} classes provide an implementation of the
+@code{java.lang.instrument.Instrument} interface. 
+A @code{InstrumentationImpl} object should be created by the VM when agents
+are given in the command line (see the @code{java.lang.instrument} package
+documentation). The VM has to set the static field
+@code{VMClassLoader.instrumenter} to this object. The VM should implement the
+static native methods of the @code{VMInstrumentationImpl} class.
+
+@itemize @bullet
+@item @code{isRedefineClassesSupported()} -- Returns true if the JVM supports
+class redefinition.
+@item @code{redefineClasses()} -- Gives a set of classes with new bytecodes.
+The VM must redefine the classes by reading the new bytecodes.
+@item @code{getAllLoadedClass()} -- Returns an array of all loaded classes.
+@item @code{getInitiatedClass()} -- Returns an array of all classes loaded
+by a specific class loader.
+@item @code{getObjectSize()} -- Gives the size of an object.
+@end itemize
+
+Instrumentation allows to modify the bytecode of a class before it gets read
+by the VM@. In GNU Classpath, the @code{ClassLoader.defineClass} method calls
+the @code{VMClassLoader.defineClassWithTransformers} method which first checks
+if @code{VMClassLoader.instrumenter} is @code{null}. If it's the case, it
+directly calls @code{VMClassLoader.defineClass}. If it's not the case, the
+method calls at first the @code{InstrumentationImpl.callTransformers} method,
+which calls each transformer registered to the @code{InstrumentationImpl}
+object and returns a new bytecode array. Then, it calls the
+@code{VMClassLoader.defineClass} method with this new bytecode array.
+
+The second use of instrumentation is to redefine a class after it has been
+loaded by the VM@. This is done in the Java application by calling the
+@code{Instrumentation.redefineClasses} method of the standard interface on
+a @code{Instrumentation} object. The @code{InstrumentationImpl.redefineClasses}
+method calls the @code{VMInstrumentationImpl.redefineClasses} native method
+which must be implemented by the VM@. The implementation should call the
+@code{InstrumentationImpl.callTransformers} method.
+
+@node gnu.java.lang.management, java.lang.management, gnu.java.lang, Classpath Hooks
+@section @code{gnu.java.lang.management}
+
+@code{gnu.java.lang.management} provides the VM interfaces for the GNU
+implementations of the management beans.  
+
+@menu
+* gnu.java.lang.management.VMRuntimeMXBeanImpl::
+* gnu.java.lang.management.VMClassLoadingMXBeanImpl::
+* gnu.java.lang.management.VMThreadMXBeanImpl::
+* gnu.java.lang.management.VMMemoryMXBeanImpl::
+* gnu.java.lang.management.VMCompilationMXBeanImpl::
+* gnu.java.lang.management.VMMemoryPoolMXBeanImpl::
+* gnu.java.lang.management.VMMemoryManagerMXBeanImpl::
+* gnu.java.lang.management.VMGarbageCollectorMXBeanImpl::
+@end menu
+
+@node gnu.java.lang.management.VMRuntimeMXBeanImpl,gnu.java.lang.management.VMClassLoadingMXBeanImpl,,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMRuntimeMXBeanImpl}
+
+The @code{gnu.java.lang.management.RuntimeMXBeanImpl} provides an
+implementation of the @code{java.lang.management.RuntimeMXBean} interface,
+and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMRuntimeMXBeanImpl}.  This provides a
+series of methods, which should be implemented by the virtual machine
+in order to provide the required information for the bean.  The VM
+methods are generally representative of information that is only
+available from the virtual machine, such as the command-line arguments
+it was given at startup.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(getInputArguments())} -- The VM should supply
+a @code{String} array containing each of the command-line
+arguments, excluding those that are directed at the
+@code{main()} method.  The reference implementation expects
+this to be a native method.
+@item @code{(getName())} -- The VM developer should choose
+an appropriate name for the virtual machine.  This name can
+be instance-specific e.g.@: it can include things like the
+process identifier or host name of the machine, which only
+apply to the current running instance.  Thus, the intention is
+that this name refers to the entity that the other information
+refers to, rather than the VM in general.  The reference
+implementation supplies a default concatenation of the VM
+name and version.
+@item @code{(getStartTime())} -- This should return the number
+of milliseconds at which the virtual machine was started.
+The uptime property of the bean is provided relative to this
+value.  Again, the reference implementation also expects
+this method to be native.
+@end itemize
+
+The virtual machine also needs to provide either the
+@code{sun.boot.class.path} or @code{java.boot.class.path}
+property in order to support the optional boot class path
+retrieval functionality.
+
+@node gnu.java.lang.management.VMClassLoadingMXBeanImpl,gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management.VMRuntimeMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMClassLoadingMXBeanImpl}
+
+The @code{gnu.java.lang.management.ClassLoadingMXBeanImpl} provides an
+implementation of the @code{java.lang.management.ClassLoadingMXBean} interface,
+and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMClassLoadingMXBeanImpl}.  This provides a
+series of methods, which should be implemented by the virtual machine
+in order to provide the required information for the bean.  Implementing
+this bean requires the VM to monitor when classes are loaded and unloaded,
+and provide the option of verbose class loading output.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(getLoadedClassCount())} -- This should return
+the number of classes that are currently loaded by the VM.
+@item @code{(getUnloadedClassCount())} -- This should return
+the number of classes that have been loaded by the VM, but
+have since been unloaded.
+@item @code{(isVerbose())} -- This should return @code{true}
+or @code{false}, depending on whether verbose class loading
+output is turned or not, respectively.
+@item @code{(setVerbose(boolean))} -- This should allow the
+verbose class loading output to be turned on and off.
+@end itemize
+
+@node gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management.VMClassLoadingMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMThreadMXBeanImpl}
+
+The @code{gnu.java.lang.management.ThreadMXBeanImpl} provides an
+implementation of the @code{java.lang.management.ThreadMXBean} interface,
+and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMThreadMXBeanImpl}.  This provides a
+series of methods, which should be implemented by the virtual machine
+in order to provide the required information for the bean.  Implementing
+this bean requires the VM to monitor thread-related statistics such as
+how often the blocked and waiting states have been entered, as well as
+additional optional support for time and contention monitoring.
+
+Optional support is determined by the following properties:
+
+@itemize @bullet
+@item @code{gnu.java.lang.management.CurrentThreadTimeSupport} --
+This property should be present if the VM supports monitoring the
+time used by the current thread.  If time monitoring for all threads
+is supported, this need not be provided.
+@item @code{gnu.java.lang.management.ThreadTimeSupport} --
+This property should be present if the VM supports monitoring the
+time used by all threads.
+@item @code{gnu.java.lang.management.ThreadContentionSupport} --
+This property should be present if the VM supports thread contention
+monitoring.
+@item @code{gnu.java.lang.management.MonitorUsageMonitoringSupport} --
+This property should be present if the VM supports the monitoring
+of object monitor usage.
+@item @code{gnu.java.lang.management.OwnableSynchronizerUsageMonitoringSupport} --
+This property should be present if the VM supports the monitoring
+of ownable synchronizer usage.
+@end itemize
+
+In addition, the property
+@code{gnu.java.lang.management.ThreadTimeInitallyEnabled} may be
+set to the @code{String} value, @code{"true"}, if time monitoring
+is enabled at startup.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(findDeadlockedThreads())} -- This should return
+an array of thread identifiers which match threads involved in
+deadlock cycles (where each thread is waiting to obtain a lock
+held by one of the others) on object monitors or ownable
+synchronizers.  This is specified as a native method in the
+reference implementation, and is optional.  It is only called
+when the VM supports ownable synchronizer monitoring.
+@item @code{(findMonitorDeadlockedThreads())} -- This should return
+an array of thread identifiers which match threads involved in
+deadlock cycles (where each thread is waiting to obtain a lock
+held by one of the others) on object monitors.  This is specified
+as a native method in the reference implementation.
+@item @code{(getAllThreads())} -- This should return an array of
+all live threads and set the @code{filled} variable to the number
+found.  A default implementation is provided.
+@item @code{(getAllThreadIds())} -- This should return an array of
+all live thread identifiers.  An implementation is provided against
+@code{getAllThreads()} by default.
+@item @code{(getCurrentThreadCpuTime())} -- This should return the
+approximate number of nanoseconds of CPU time the current thread
+has used.  This is an optional native method, which is used by VMs
+supporting time monitoring.
+@item @code{(getCurrentThreadUserTime())} -- This should return the
+approximate number of nanoseconds of user time the current thread
+has used.  This is an optional native method, which is used by VMs
+supporting time monitoring.
+@item @code{(getDaemonThreadCount())} -- This should return the number
+of live daemon threads.  A default implementation is provided, based
+on @code{getAllThreads()}.
+@item @code{(getLockInfo(ThreadInfo))} -- This is an optional native
+method called when the VM supports ownable synchronizer usage monitoring
+and the user has requested information for a particular thread.  The
+supplied @code{ThreadInfo} object should be filled out with an
+array of @code{LockInfo} objects, providing details on each lock. 
+@item @code{(getMonitorInfo(ThreadInfo))} -- This is an optional native
+method called when the VM supports object monitor usage monitoring
+and the user has requested information for a particular thread.  The
+supplied @code{ThreadInfo} object should be filled out with an
+array of @code{MonitorInfo} objects, providing details on each lock. 
+@item @code{(getPeakThreadCount())} -- The VM should maintain a record
+of the peak number of live threads, and return it when this method is
+called.  This is specified as a native method in the reference
+implementation.
+@item @code{(resetPeakThreadCount())} -- This should reset the record
+of the peak number of live threads to the current number of live
+threads.  This is specified as a native method in the reference
+implementation.
+@item @code{(getThreadCount())} -- This should return the number of
+live threads.  A default implementation is provided, based on
+@code{getAllThreads()}.
+@item @code{(getThreadCpuTime(long))} -- This should return the
+approximate number of nanoseconds of CPU time the specified thread
+has used.  This is an optional native method, which is used by VMs
+supporting time monitoring.
+@item @code{(getThreadUserTime(long))} -- This should return the
+approximate number of nanoseconds of CPU time the specified thread
+has used.  This is an optional native method, which is used by VMs
+supporting time monitoring.
+@item @code{(getThreadInfoForId(long, int))} -- This return an instance
+of @code{java.lang.management.ThreadInfo} for the specified thread.
+The class includes a private constructor which VMs should use to initialise
+it with the appropriate values for the thread.  The second argument
+given here specifies the depth of the stack trace supplied on construction
+of the instance.  Special values are 0 (return an empty array) and
+@code{Integer.MAX_VALUE} (return the maximum depth possible).  This
+is specified as a native method in the reference implementation.
+@item @code{(getTotalStartedThreadCount())} -- This should return the
+total number of threads that have been started by the VM, including ones
+that have died.  This is specified as a native method in the reference
+implementation.
+@end itemize
+
+@node gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMMemoryMXBeanImpl}
+
+The @code{gnu.java.lang.management.MemoryMXBeanImpl} provides an
+implementation of the @code{java.lang.management.MemoryMXBean} interface,
+and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMMemoryMXBeanImpl}.  This provides a
+series of methods, which should be implemented by the virtual machine
+in order to provide the required information for the bean.  Implementing
+this bean requires the VM to monitor the levels of heap and non-heap
+memory, and provide the number of objects which are eligible for garbage
+collection.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(getHeapMemoryUsage())} -- This should return
+an instance of @code{java.lang.management.MemoryUsage} with
+values pertaining to the heap.  A default implementation is
+provided, based on @code{java.lang.Runtime}'s methods.
+@item @code{(getNonHeapMemoryUsage())} -- This should return
+an instance of @code{java.lang.management.MemoryUsage} with
+values pertaining to non-heap memory.
+@item @code{(getObjectPendingFinalizationCount())} -- Returns
+the number of objects which are no longer referenced, and which
+will thus be garbage collected on the next run of the garbage
+collector.
+@item @code{(isVerbose())} -- This should return @code{true}
+or @code{false}, depending on whether verbose memory management
+output is turned or not, respectively.
+@item @code{(setVerbose(boolean))} -- This should allow the
+verbose memory management output to be turned on and off.
+@end itemize
+
+@node gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMCompilationMXBeanImpl}
+
+The @code{gnu.java.lang.management.CompilationMXBeanImpl} provides an
+implementation of the optional @code{java.lang.management.CompilationMXBean}
+interface, and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMCompilationMXBeanImpl}.  This provides a
+single method for returning the number of milliseconds the virtual
+machine's Just-In-Time (JIT) compiler has spent compiling.  Even if
+a JIT compiler is available and an instance of the bean supplied, this
+method is still optional.
+
+Optional support is determined by the following properties:
+
+@itemize @bullet
+@item @code{gnu.java.lang.compiler.name} -- This property should
+specify the name of the JIT compiler.  Classpath also uses this,
+within @code{java.lang.management.ManagementFactory}, to determine
+whether a bean should be created.  If this property is set to a
+non-null value, a bean will be created and its @code{getName()}
+method will return this value.
+@item @code{gnu.java.lang.management.CompilationTimeSupport} --
+This property should be present if the VM supports monitoring the
+time spent compiling.
+@end itemize
+
+Time support is implemented by the following method:
+
+@itemize @bullet
+@item @code{(getTotalCompilationTime())} -- This should return the
+number of milliseconds the JIT compiler has spent compiling.
+@end itemize
+
+@node gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMMemoryPoolMXBeanImpl}
+
+The @code{gnu.java.lang.management.MemoryPoolMXBeanImpl} provides an
+implementation of the optional @code{java.lang.management.MemoryPoolMXBean}
+interface, and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMMemoryPoolMXBeanImpl}.  Providing
+this interface requires implementing a number of methods for each supported
+pool.  These return statistics on memory usage, and, optionally, allows
+monitoring of when memory usage exceeds a preset threshold.
+
+Optional support is determined by the following properties:
+
+@itemize @bullet
+@item @code{gnu.java.lang.management.CollectionUsageThresholdSupport} --
+This property should be present if the VM supports setting a collection
+usage threshold and monitoring when it is matched or exceeded.  Collection
+usage thresholds are related to the remaining memory usage following a
+garbage collection cycle.
+@item @code{gnu.java.lang.management.UsageThresholdSupport} --
+This property should be present if the VM supports setting a 
+usage threshold and monitoring when it is matched or exceeded.  
+@end itemize
+
+The methods are as follows (all take a pool name as their
+first parameter):
+
+@itemize @bullet
+@item @code{(getCollectionUsage(String))} -- Returns a
+@code{java.lang.management.MemoryUsage} object, containing the
+memory usage statistics following a garbage collection cycle
+for the specified pool.  This may also return @code{null} if
+the pool isn't an appropriate pool for this particular task.
+@item @code{(getCollectionUsageThreshold(String))} -- Returns
+the pool's collection usage threshold, if supported.
+@item @code{(getCollectionUsageThresholdCount(String))} -- Returns
+the number of times the specified pool has matched or exceeded
+its collection usage threshold, if supported.
+@item @code{(getMemoryManagerNames(String))} -- Returns a list
+of names of memory managers which manage the specified pool.
+@item @code{(getPeakUsage(String))} -- Returns a
+@code{java.lang.management.MemoryUsage} object for the peak
+usage level of the specified pool.
+@item @code{(getType(String))} -- Returns a string containing
+either @code{"HEAP"} or @code{"NON_HEAP"} which indicates the type of
+memory used by the specified pool.
+@item @code{(getUsage(String))} -- Returns a
+@code{java.lang.management.MemoryUsage} object for the current
+usage level of the specified pool.
+@item @code{(getUsageThreshold(String))} -- Returns
+the pool's usage threshold, if supported.
+@item @code{(getUsageThresholdCount(String))} -- Returns
+the number of times the specified pool has matched or exceeded
+its usage threshold, if supported.
+@item @code{(isValid(String))} -- Returns true if the pool
+is still in use by the virtual machine.
+@item @code{(resetPeakUsage(String))} -- Resets the peak usage
+levels to the current usage levels for the specified pool.
+@item @code{(setCollectionUsageThreshold(String, long))} -- Sets
+the pool's collection usage threshold, if supported.
+@item @code{(setUsageThreshold(String, long))} -- Sets
+the pool's usage threshold, if supported.
+@end itemize
+
+@node gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management.VMGarbageCollectorMXBeanImpl,gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}
+
+The @code{gnu.java.lang.management.MemoryManagerMXBeanImpl} provides an
+implementation of the optional @code{java.lang.management.MemoryManagerMXBean}
+interface, and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}.  Providing
+this interface requires implementing two methods (each takes the name
+of the manager as the first argument):
+
+@itemize @bullet
+@item @code{(getMemoryPoolNames(String))} -- Returns a list of the
+memory pools that the manager maintains.  A default implementation
+which scans the results of @code{getMemoryManagerNames()} for each
+pool is provided.
+@item @code{(isValid(String))} -- Returns true if the specified
+manager is still valid, i.e., it is still in use by the virtual machine.
+@end itemize
+
+@node gnu.java.lang.management.VMGarbageCollectorMXBeanImpl,,gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMGarbageCollectorMXBeanImpl}
+
+The @code{gnu.java.lang.management.GarbageCollectorMXBeanImpl} provides an
+implementation of the optional @code{java.lang.management.GarbageCollectorMXBean}
+interface, and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMGarbageCollectorMXBeanImpl}.  Providing
+this interface requires implementing two methods (each takes the name
+of the garbage collector as the first argument):
+
+@itemize @bullet
+@item @code{(getCollectionCount(String))} -- Returns the number of
+times the specified garbage collector has run.
+@item @code{(getCollectionTime(String))} -- Returns the accumulated
+number of milliseconds for which the garbage collector has run.
+@end itemize
+
+Note that each garbage collector is also a memory manager, and so an
+implementation of the @code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}
+methods for its name should also be provided.
+
+@node java.lang.management, Classpath Callbacks, gnu.java.lang.management, Classpath Hooks
+@section @code{java.lang.management}
+
+@code{gnu.java.lang.management} provides the VM interfaces for the GNU
+implementations of the management beans.  
+
+@menu
+* java.lang.management.VMManagementFactory::
+@end menu
+
+@node java.lang.management.VMManagementFactory,,,java.lang.management
+@subsection @code{java.lang.management.VMManagementFactory}
+
+This VM interface provides the names of the memory pools, memory managers
+and garbage collectors for use by the @code{java.lang.management.ManagementFactory}
+in creating lists of appropriate beans for these types of managed object.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(getMemoryPoolNames())} -- Returns a list of the names
+of the current memory pools in use by the virtual machine.
+@item @code{(getMemoryManagerNames())} -- Returns a list of the names
+of the current memory managers in use by the virtual machine.  This
+should not include those that are also garbage collectors.
+@item @code{(getGarbageCollectorNames())} -- Returns a list of the names
+of the current garbage collectors in use by the virtual machine.
+@end itemize
+
+@node Classpath Callbacks, , java.lang.management, Classpath Hooks
+Some of the classes you implement for the VM will need to call back to
+package-private methods in Classpath:
+
+@itemize @bullet
+@item @code{java.lang.ThreadGroup.addThread(Thread)}
+Call this method from @code{Thread} when a new @code{Thread} is created, to add it to
+the group.
+
+@item @code{java.lang.ThreadGroup.removeThread(Thread)}
+Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.
+
+@item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireThresholdExceededNotification(String, long, long, long, long)}
+If the monitoring of memory usage thresholds is supported, this method
+should be called when the normal usage of a memory pool crosses the
+threshold, in order to emit a notification.  Another notification
+should not be emitted until there is an intermittent period where the
+usage is again below the threshold.  The parameters are the memory
+pool name, the usage levels (init, used, committed and max) and the
+number of times the threshold has been crossed.
+
+@item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireCollectionThresholdExceededNotification(String, long, long, long, long)}
+If the monitoring of memory usage thresholds is supported, this method
+should be called when the usage of a memory pool after a garbage
+collection cycle crosses the threshold, in order to emit a
+notification.  Another notification should not be emitted until there
+is an intermittent period where the usage is again below the
+threshold.  The parameters are the memory pool name, the usage levels
+(init, used, committed and max) and the number of times the threshold
+has been crossed.
+
+@end itemize
+
+@node VM Hooks, JNI Implementation, 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.
+
+Some of the core classes, while being implemented by GNU Classpath,
+provide space for state (in the form of a @code{vmdata} object) to be
+stored by the VM, and can not be constructed normally.
+
+@itemize @bullet
+@item java.lang.Class
+@item java.lang.ClassLoader
+@end itemize
+
+The default implementations of some VM classes also follow this methodology,
+when it is intended that most VMs will keep the default.
+
+@itemize @bullet
+@item java.lang.VMThread
+@item java.lang.VMThrowable
+@end itemize
+
+Several core classes must be completely implemented by the VM for Classpath to
+work, although reference implementations are provided.  These classes are:
+
+@itemize @bullet
+@item java.lang.reflect.Constructor
+@item java.lang.reflect.Method
+@item java.lang.reflect.Field
+@end itemize
+
+The following issues are of note;
+
+@itemize @bullet
+@item @code{java.lang.Class} @*
+The GNU Classpath implementation of @code{java.lang.Class} provides an
+object for storing the internal state of the class maintained by the VM.
+This is the only known place where this matters.  The class is
+constructed with this data by the VM@.  Some VMs do not create the
+@code{Class} object at the point where the class is defined; instead,
+they wait until a @code{Class} object is actually used.
+
+@item Array Classes @*
+When you are creating an array class, you should set the
+@code{ClassLoader} of the array class to the @code{ClassLoader} of its
+component type.  Whenever you add a class to a @code{ClassLoader}, you
+need to notify the @code{ClassLoader} and add the new @code{Class} to
+its internal cache of classes.  To do this, call
+@code{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
+@code{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 @code{Throwable.printStackTrace()}.
+
+@item Security and Traces @*
+There will eventually be a feature in the 1.2 security that keeps the
+@code{AccessController} from having to evaluate @emph{all} of the
+@code{ProtectionDomain}s 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 @code{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 @code{AccessController}
+will remember what the accumulated protection status was at every stack
+level (an @code{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 @code{ThreadGroup}, but that class is almost entirely
+VM-independent.  The root @code{ThreadGroup}, a static field called
+@code{ThreadGroup.root}, should be initialized by Classpath, but if you wish to
+reinitialize it yourself, there should be no harm.
+
+@end itemize
+
+@node JNI Implementation, JVMTI Implementation, VM Hooks, Top
+@comment  node-name,  next,  previous,  up
+@chapter JNI Implementation
+
+Classpath comes with its own implementation of @file{jni.h}.  This
+file can be customized by the VM in a few ways, by defining macros
+that affect the interpretation of the file.  These macros are all
+intended for use by a VM which uses GNU Classpath and which wants to
+use a single copy of @file{jni.h} for both internal and external use.
+
+@itemize @bullet
+@item _CLASSPATH_VM_JNI_TYPES_DEFINED
+Some VMs like to define JNI ``object'' types in a special way.  If
+this macro is defined, the Classpath @file{jni.h} will avoid defining
+these types.  By default, these types are defined in @file{jni.h}.
+The full list of types and macros treated this way is: @samp{jobject},
+@samp{jclass}, @samp{jstring}, @samp{jthrowable}, @samp{jweak},
+@samp{jarray}, @samp{jobjectArray}, @samp{jbyteArray},
+@samp{jshortArray}, @samp{jintArray}, @samp{jlongArray},
+@samp{jbooleanArray}, @samp{jcharArray}, @samp{jfloatArray},
+@samp{jdoubleArray}, @samp{JNIEnv}, @samp{JavaVM}, @samp{JNI_TRUE}
+(macro), @samp{JNI_FALSE} (macro).
+
+@item _CLASSPATH_VM_INTERNAL_TYPES_DEFINED
+If the VM has its own definitions for @samp{jfieldID} and
+@samp{jmethodID}, then it should define this macro.  Otherwise,
+@file{jni.h} will provide definitions for these types.
+
+@item _CLASSPATH_JNIIMPEXP
+Three functions -- @samp{JNI_GetDefaultJavaVMInitArgs},
+@samp{JNI_CreateJavaVM}, and @samp{JNI_GetCreatedJavaVMs} -- must be
+marked as @samp{JNIIMPORT} when seen by user code, but most likely
+should be marked as @samp{JNIEXPORT} when defined in the VM
+implementation.  This macro can be defined to one or the other by the
+VM as appropriate.  If this macro is not defined, it defaults to
+@samp{JNIIMPORT}.
+
+@item _CLASSPATH_JNIENV_CONTENTS
+A VM can add fields to the @samp{JNIEnv} structure by defining this to
+be a sequence of field declarations.
+
+@end itemize
+
+@node JVMTI Implementation, Miscellaneous VM Requirements, JNI Implementation, Top
+@comment node-name, next, previous, up
+@chapter JVMTI Implementation
+
+Classpath comes with its own implementation of @file{jvmti.h}.  This
+file can be customized by the VM in a few ways by defining macros that
+affect the interpretation of the file.  These macros are all intended
+for use for use by a VM which uses GNU Classpath and which wants to
+use a single copy of @file{jvmti.h} for both internal and external use.
+
+@itemize @bullet
+@item _CLASSPATH_VM_JVMTI_TYPES_DEFINED
+Some VMs like to define JVMTI ``object'' types in a special way.  If
+this macro is defined, the Classpath @file{jvmti.h} will avoid defining
+these types.  By default these types are defined in @file{jvmti.h}.  
+The full list of types and macros treated this way is: @samp{jthread},
+@samp{jthreadGroup}, @samp{jlocation}, and @samp{jrawMonitorID}.  By
+default @samp{jrawMonitorID} is defined as an opaque pointer which
+must be defined by the VM.
+
+@item _CLASSPATH_JVMTIENV_CONTENTS
+A VM can add fields to the @samp{jvmtiEnv} structure by defining this
+to be a sequence of field declarations.
+
+@end itemize
+
+@node Miscellaneous VM Requirements,  , JVMTI Implementation, Top
+@comment  node-name,  next,  previous,  up
+@chapter Miscellaneous VM Requirements
+
+Classpath places a few requirements on the VM that uses it.
+
+@menu
+* JNI Version::                 
+* VM Threading Model::          
+* Boot Library Path Property::
+@end menu
+
+@node JNI Version, VM Threading Model, Miscellaneous VM Requirements, Miscellaneous VM Requirements
+@comment  node-name,  next,  previous,  up
+@section JNI Version
+
+Classpath currently uses only JNI 1.1, except for one JNI 1.2 function
+in the JNI Invocation API: GetEnv().  And GetEnv() is only used in the
+now deprecated ``portable native sync'' code.
+
+A future direction will probably be to require that all VMs provide
+JNI 1.2.  If this poses problems, please raise them on the classpath
+mailing list. 
+
+@node VM Threading Model, Boot Library Path Property, JNI Version, Miscellaneous VM Requirements
+@comment  node-name,  next,  previous,  up
+@section VM Threading Model
+
+VM authors can implement a number of different threading models. When
+native code is also threaded there is the potential for one threading
+model to deadlock the other. The
+@uref{http://java.sun.com/docs/books/jni/html/other.html#29406,Java
+Native Interface Programmer's Guide and Specification} suggests
+consulting VM documentation in such situations. Classpath uses
+existing libraries, for example the AWT peers can use the GTK+
+graphics library. As these libraries assume a different threading
+model, there is the potential for the native code to deadlock a VM.
+
+The different threading models available to a VM author are:
+@enumerate
+@item
+@i{Native threads}: Map a Java thread to an underlying operating system
+thread (normally a POSIX compatible pthread). This approach reduces
+the potential for deadlock as there is only one thread scheduling
+mechanism.
+@item
+@i{Green threads 1}: Green threads are threads scheduled by the VM,
+typically by switching swapping registers. In early VMs green threads
+were seen as advantageous as they didn't require the operating system
+to reschedule, save and swap all of a threads registers. The green
+thread 1 model switches thread on an externally created event, such as
+a timer interrupt. An example of a VM using this approach is Kaffe
+configured with its jthreads model.
+@item
+@i{Green threads 2}: The essential difference with this model is to
+not switch threads on an event, but at fixed points in the code being
+executed by the VM@. Points chosen could be backward branches (loops)
+or method calls. This approach can be advantageous to nonconservative
+garbage collectors, as non-running threads would be at known points
+and can have fixed register maps. It can also reduce the number of
+registers it is necessary to swap when switching threads.
+@item
+@i{M:N threading}: a flaw to green threading is that it is unable to
+use multiple processors. @i{M}:@i{N} threading fixes this problem by
+running groups of green threads on multiple underlying native
+threads. An example of a VM using this approach is the Jikes RVM,
+which uses @i{M}:@i{N} threading combined with the green thread 2
+model.
+@end enumerate
+
+An example of the problem of mixing threading models is:
+@itemize @bullet
+@item
+A Java thread calls a native method. The native method acquires a lock.
+@item
+The native method calls back into the VM.
+@item
+An event triggers the VM to reschedule the currently running thread.
+@item
+A new VM thread, executing on the same underlying native thread, calls
+a native method.
+@item
+The native method tries to acquire the lock already acquired earlier. As
+the lock is busy the thread waits and allows the operating system to
+reschedule native threads.
+@item
+The operating system reschedules the VM thread again, but the lock is
+still busy and in some threading models will remain busy forever
+(the VM is deadlocked).
+@end itemize
+
+VMs that don't use the underlying operating system thread scheduling
+mechanism need to avoid deadlock. One now deprecated approach was to
+build Classpath and VMs on top of a wrapper thread library (aka
+portable native sync). The wrapper thread library used was GLIB's
+@dfn{gthreads}. This approach has been deprecated because:
+@enumerate
+@item
+The wrapper library is only in use by some native libraries. For
+example, GTK+ uses the gthread library but QT does not.
+@item
+The wrapper library can't be in use prior to the VM starting as the VM
+must replace the wrapper libraries functions with its own. This
+prevents the VM from running as a plugin in an application that
+already uses the wrapper library.
+@end enumerate
+
+An alternative approach is for the VM to detect deadlocked native code
+and swap Java threads off of that native thread. The VM can't,
+however, swap two blocked native threads that are potentially
+deadlocking each other on a lock. The lock will be associated with the
+native thread. To prevent this from happening the VM must hijack
+functions that operate on locks. This is done by redefining the lock
+functions inside the VM and configuring the linker so that it uses the
+VMs symbol in preference to that of the external thread support
+library. The VM's lock function can then reschedule Java threads if it
+must wait for the lock.
+
+@node Boot Library Path Property,  , VM Threading Model, Miscellaneous VM Requirements
+@comment  node-name,  next,  previous,  up
+@section Boot Library Path Property
+
+As of GNU Classpath 0.15 a system property named @code{gnu.classpath.boot.library.path}
+can be set by the VM to specify the directories which contain GNU Classpath's native
+libraries. Usually this value is given at configuration time and is then hardcoded
+in the VM@. However for development purposes it is handy to switch to another installation
+by overriding the properties' value on the command line.
+
+A VM that does not support this feature can simply ignore the property.
+
+For compatibility reasons we suggest to set the default value of @code{java.library.path}
+to the value of the @code{LD_LIBRARY_PATH} environment if it exists on your platform.
+
+@bye
+
+
+