This implementation of the Java Virtual Machine corresponds roughly to these various source files for the overall structure. Details not found in them are located throughout the body of the source code. The following table shows this overall code structure. It is based upon the table of contents to the above JVM specification document. Where a .h C header file name is listed, the corresponding .c C source file is of less interest to this structure than the header that publishes it to the major subsystems, which are listed by their .c C source file names. Across the top of each page of documentation in most formats is is a line containing links to key indices across the documentation. Other formats may not have the links, but will have the same pages available. These categories are:

• Main Page: This starting point for all documentation.

• Namespace List: Not really used since this is not a C++ code base. However, it does contain Java package name levels for test classes and core JDK classes.

• Alphabetical List: Index of data structures, with name and definition reference only.

• Data Structures: Index of data structures, with name, description, and definition reference.

• Directories: Index of file system directories which contain source files for this project.

• File List: Index of source files, by directory, containing names, descriptions, and references to source code.

• Data Fields: Index of member fields and methods in Java classes, 'C' structs, and 'C' unions, by member name.

• Globals: Global name space functions, variables, type definitions, enumerations, and pre-processor definitions, by category and by name. (The term "global" does not apply to symbol scope. Both global scope and file scope symbols are listed here. The global name space is an OO concept typically used by Doxygen to document C++ symbols. It is meaningful here only in terms of Java classes.) The categories are:
  • Functions: Function definitions, by name.
  • Variables: Variable definitions, by name.
  • Typedefs: Type definitions, by name. (N.B. It is here that the convention of using letter j and letter r for Java and real machine domain data types is most obvious.)
  • Enumerations: Enumerations, by name.
  • Enumerators: Enumeration components, by name.
  • Defines: C pre-processor definitions, by name.

• Data Fields: Member fields and methods in Java classes, 'C' structs, and 'C' unions, by member name.

The following table shows the JVM specification section number in that document and a general location at which to start when looking for its functionality. Any sections not listed below are likely to not have yet been implemented here or are more applicable to the class library and/or compiler.

• 1.2 The Java Virtual Machine: The main entry point to to this JVM implementation is found in jvm.c. It sets up an rjvm structure using a pervasive global variable named pjvm to refer to a JVM structure. It stands for, "pointer to JVM." Variable names beginning with p stand for "pointer to...." Data structure names beginning with r stand for "real machine data type," while data structure names beginning with j stand for "Java virtual machine data type."
• 2.1 Unicode: Utilities found in unicode.c
• 2.3 Literals: Definitions found in jrtypes.c
• 2.4.1 Primative Types and Values: Initialized in class.c
• 2.4.7 The class 'Object': Implemented in jlObject.c
• 2.4.8 The class 'String': Implemented in jlString.c
• 2.5 Variables: Implemented by jvalue members of class.h and class.h.
• 2.6 Conversions and Promotions: All actions on variables are performed in the JVM inner loop in opcode.c
• 2.6.6 Value Set Conversion: NOT IMPLEMENTED. It is assumed that the platform's native floating point hardware implements the IEEE floating point used by the JVM and with the same constraints, which is not likely to be a completely valid presupposition. FP-strict expressions from section 2.18 are likewise NOT IMPLEMENTED.
• 2.6.7 Assignment Conversion: All actions on variables are performed in the JVM inner loop in opcode.c
• 2.8 Classes: Implemented in class.c
• 2.9 Fields: Implemented in class.c and field.c
• 2.10 Methods: Implemented in class.c and method.c
• 2.11 Static Initializers: Implemented in opcode.c
• 2.12 Constructors: Implemented in opcode.c
• 2.13 Interfaces: Implemented in class.c and method.c
• 2.15 Arrays: Implemented in class.c and object.c
• 2.16 Exceptions: Implemented in exit.c and thread.c and opcode.c and jvmclass.h and all source code referencing the classes defined in this header. Most code that calls setjmp(3) or longjmp(3) is processing an exception of some type, with the single exclusion of the while() loop of the inner JVM execution in opcode.c .
• 2.17 Execution: Implemented in jvm.c and opcode.c .
• 2.17.1 Virtual Machine Start-up: Implemented in jvm.c .
• 2.17.2 Loading: Implemented in classfile.c and cfattrib.c and class.c. The occurrence of a newly loaded Java class is called a "class static instance" in this implementation. This is over and against the term for an instance of an object of this class type, which is known as an "object instance".
• 2.17.3 Linking: Implemented in linkage.c
• 2.17.4,5 Initialization: Implemented in opcode.c
• 2.17.6 Creation of New Class Instances: Implemented in object.c . The occurrence of a newly created Java object is called an "object instance" in this implementation. This is over and against the term for the loading and definition of a Java class itself, which is known as a "class static instance", of which type this object is one specific instanceof among many.
• 2.17.7 Finalization of Class Instances: Implemented in unicode.c
• 2.17.8 Unloading of Classes and Interfaces: Implemented in class.c
• 2.17.9 Virtural Machine Exit: Implemented in jvm.c as a consequence of an exception in exit.c or of completion of execution in jvm.c as a
• 2.18 FP-strict Expressions: NOT IMPLEMENTED. Value set conversions expressions from section 2.6.6 are likewise NOT IMPLEMENTED.
• 2.19 Threads: Implemented in threadstate.c, as driven by jvm.c and the infrastructure of thread.c
• 3.2 Data types: Implemented in class.c
• 3.3 Primative Types and Values: Implemented in opcode.c
• 3.4 Reference Types and Values: Implemented in opcode.c as supported by the infrastructure of class.c
• 3.5.1 The PC Register: Implemented in jvmreg.h
• 3.5.2 Java Virtual Machine stacks: Implemented in jvmreg.h
• 3.5.3 Heap: Interface defined in heap.h and implemented twice in heap_simple.c and in heap_bimodal.c . The choice of implementation is done at configuration time using config.sh . A generic "roll your own" option is available for those who are implementing heap modules. Three heap regions are defined, one for class file and method storage, one for JVM stack areas, and one for general-purpose data areas.
• 3.5.4 Method Area: One of the heap storage areas defined in heap.h, where all class file related structures are stored.
• 3.5.5 Runtime Constant Pool: Implemented as a part of the method area storage (section 3.5.4) in the heap (section 3.5.3).
• 3.5.6 Native Method Stacks: Since all JVM activities except the millisecond time slice (see timeslice.c) operate on the same POSIX thread, native methods use the same real machine stack as the main JVM code's POSIX thread. See also native method invocation in native.c
• 3.6 Frames: Implemented in jvmreg.h
• 3.6.1 Local Variables: Implemented inside the JVM stack frame (per section 3.6), found in jvmreg.h
• 3.6.2 Operand Stacks: Implemented on the top of the JVM stack frame (per section 3.6), found in jvmreg.h
• 3.6.3 Dynamic Linking: Implemented in opcode.c and linkage.c
• 3.6.4 Normal Method Invocation Completion: Implemented in opcode.c
• 3.6.5 Abrupt Method Invocation Completion: Implemented in opcode.c
• 3.7 Representation of Objects: Implemented in object.c and object.h and jlObject.c
• 3.8 Floating-Point Arithmetic: See comments above on section 2.6.6 about how floating point arithmetic is implemented.
• 3.9 Specially Named Initialization Methods: Implemented in opcode.c
• 2.16 Exceptions: See comments above on section 2.16.
• 3.11 Instruction Set Summary: The JVM outer loop is implemented in jvm.c , while the inner look is implemented in opcode.c . All of the section 3.11.x headings fall under the category of the inner loop.
• 3.12 Class Libraries: Only minimal support is provied for class libraries, and that only enough to start the machine. See especially support for the environment variable BOOTCLASSPATH and its command line override equivalent as implemented in classpath.c
• 4 The ClassFile Structure: Implemented in classfile.c and cfattrib.c and extensively referenced throughout the code in classfile.h . A pervasive local variable named pcfs (or prefixed this way) is found all over the code and refers to a ClassFile data structure. It stands for, "pointer to ClassFile structure."
• 5 Linking, Loading, and Initializing: Implemented in structures of classfile.h by the late binding logic of linkage.c that is typically initiated by opcode.c . Classes are dynamically loaded by class.c objects are dynamically created by object.c
• 5.3.1 Loading Using the Bootstrap Class Loader: Implemented in class.c
• 5.3.3 Creating Array Classes: are part and parcel of all other class creations, with support built in to its implementation in class.c
• 5.6 Binding Native Method Implementations: Implemented in native.c
• 6 The Java Virtual Machine Instruction Set: Implemented in opcode.c with opcode definitions (per section 9) in opcode.h
• 8 Threads and Locks: See comments above on section 2.19. See also the native implementation of a part of java.lang.Thread in jlThread.c
• 9 Opcode Mnemonics By Opcode: Implemented in opcode.h

The garbage collection system is designed to be configurable like the heap is (see comments above on section 3.5.3). Its interface is defined in gc.h and a sample stub implementation is found in gc_stub.c . The choice of implementation is done at configuration time using config.sh . A generic "roll your own" option is available for those who are implementing garbage collection modules.

(The following description of source code directories is also found in README for display as a simple text file.)

Several directories are provided within the source tree:

• jvm: Source code for JVM, including a main() wrapper. Builds binary file jvm/bin/bootjvm .

• libjvm: For building jvm as a statically linked library archive, less main() wrapper. Builds library archive libjvm/lib/libjvm.a . Source code comes from the jvm directory.

• main: A simple main() wrapper that links libjvm/lib/libjvm.a and builds binary file main/bin/bootjvm . Source code comes from the jvm directory.

• jni: Source code for a sample JNI shared library jni/harmony/generic/0.0/lib/bootjni.so for linking with JNI code, but needs the build directives to be functional, as it currently links statically with a main() into a binary just like jvm . This directory contains a tree for JNI implementations from any supplier that wants to support the Harmony project. Currently, there is one JNI implementation here, found in jni/src/harmony/generic/0.0 .

• test: Builds numerous Java test classes in test/bin for driving development work.

With the exception of the Java test classes in test/src all source code is found in jvm/src and in the directory tree jni/src/vendor/product/version . The purpose of libjvm and main is for demonstrating various possible organizations for the source code, namely for building a static library archive and for linking it.

There are a few references to JNI (Java Native Interface) in the outline above. The following subset of java.lang classes are directly implemented in the interior of this JVM:

• java.lang.Object
• java.lang.Class
• java.lang.String
• java.lang.Thread

This JNI subset is implemented here in the following groups of source files:

• Java source code for the four classes:
  • jni/src/harmony/generic/0.0/src/java/lang/Object.java
  • jni/src/harmony/generic/0.0/src/java/lang/Class.java
  • jni/src/harmony/generic/0.0/src/java/lang/String.java
  • jni/src/harmony/generic/0.0/src/java/lang/Thread.java

• JNI headers derived from Java source code (typically via javah):
  • jni/src/harmony/generic/0.0/include/java_lang_Object.h
  • jni/src/harmony/generic/0.0/include/java_lang_Class.h
  • jni/src/harmony/generic/0.0/include/java_lang_String.h
  • jni/src/harmony/generic/0.0/include/java_lang_Thread.h

• C source implementation of native methods defined by JNI headers:
  • jni/src/harmony/generic/0.0/src/java_lang_Object.c
  • jni/src/harmony/generic/0.0/src/java_lang_Class.c
  • jni/src/harmony/generic/0.0/src/java_lang_String.c
  • jni/src/harmony/generic/0.0/src/java_lang_Thread.c

• JVM core implementation of native methods "local native methods" of these classes:
  • jvm/src/jlObject.c
  • jvm/src/jlClass.c
  • jvm/src/jlString.c
  • jvm/src/jlThread.c

• Headers for JVM core implementation code of "local native methods", including native method ordinals used by tables in native.c:
  • jvm/include/jlObject.h
  • jvm/include/jlClass.h
  • jvm/include/jlString.h
  • jvm/include/jlThread.h

• JVM connection to JNI and implementation and coordination of support for "local native methods":
  • jvm/src/native.c
  • jvm/src/native.h

The JVM specification is available from Sun Microsystems' web site at http://java.sun.com/docs/books/vmspec/index.html and may be read online at http://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html

The Java 5 class file format is available as a PDF file separately at http://java.sun.com/docs/books/vmspec/2nd-edition/ClassFileFormat-final-draft.pdf and was the basis for the ClassFile structure of this implementation.

Attention:

For those who want to get started immediately and without benefit of seeing the overall structure of the system, please at least take a look at the INSTALL file at the top of the installation tree. Between this file and the README file, a quick startup is possible.

Todo:

An enhanced startup narrative on the main page might be useful.

Attention:

There are many to-do items in the README file at the top of the installation tree. These items has been specifically reserved for the project team to work on in order to gain experience with this code and provide a forum for JVM architectural discussions as well as to implement in their own right as a part of a working JVM.

Todo:

Section 2.6.6, value set conversions of floating point numbers are not implemented. See note in table in this section. Likewise for section 2.18, FP-strict expressions, and section 3.8, floating point arithmetic.

Attention:

The virtual execution engine is still under development as this initial contribution is being made. While the project team is working on learning what is inside the code, this final module will be completed. The relevant code is found in opcode_run in source file opcode.c

Todo:

The virtual execution engine is still under development as this initial contribution is being made. While the project team is working on learning what is inside the code, this final module will be completed. The relevant code is found in opcode_run in source file opcode.c

Bug:

The virtual execution engine is still under development as this initial contribution is being made. While the project team is working on learning what is inside the code, this final module will be completed. The relevant code is found in opcode_run in source file opcode.c

---