mark3982 / rhino-java-virtual-machine Goto Github PK

Rhino

This is a project that I started to help me learn more about the 
internal workings of a Java virtual machine, and also to produce
a usable virtual machine for a embedded platform.

== COMPILATION ==
To compile the virtual machine you need to execute 'make' in the working
directory of the souce which should be the base directory. This will
create a executable [rhino] which can be executed.

== READCLASS Sub-Directory ==
This contains a java program using my custom standard library of 
functions to load a class like it's self and parse it. This is just
a simple demonstration of doing something.

== MALLOCTESTPROXY ==
The malloc test proxy is named because a stub is generated that acts
like a proxy to the internal malloc routines. The proxy is an executable
which can be generated by invoking 'make malloctestproxy' which produces
an executacle named [malloctestproxy]. The front-end to this proxy is a 
Python script called [malloctestproxy.py]. The Python script will 
execute the proxy generated and perform a bunch of random allocations,
deallocations, writes, and reads. It verifies that written data matches
when it is read many operations later. It essentially tries to cause the
malloc implementation to fail and corrupt it's self.

Also, the conf.h file should have the INTERNALMALLOC directive uncommented,
or otherwise you will end up testing the standard library malloc/free
implementation. 

This provides a good standard for testing any changes to the malloc
implementation. Since any bugs present when this is used will simply
manifest as other problems and become highly difficult to track.

== QUICK DEMO ==
To perform a quick demo and provide a starting point execute these
commands while in the root project directory.

make test1
./rhino ./ert/java/lang/Object.class 
        ./ert/java/lang/ExceptionStackItem.class 
        ./ert/java/lang/Exception.class 
        ./ert/java/lang/String.class 
        ./ert/java/lang/Array.class 
        ./tests/test1/Main.class :Main

You should place everything for the './rhino' command on a single line. 
Also take note how all classes must be specified. The 'rhino' binary
will not perform a disk search to find missing classes and expects
you to specify all needed classes. This may seem non-standard and it is,
but if you wished you could implement automatic loading and searching
quick easily I just have not had the time to do so yet. And, if you do
you need an option to specify the class path. 

Th ERT directory stands for embedded run-time and is seperate from the
standard such as openJDK. I wish to one day be able to support the 
openJDK, but for now I am opted to work on a much smaller and specialed
subset just for small embedded platforms.

== SOUCE AND HEADER FILES OVERVIEW ==

=== SRC AND INC DIRECTORY ===
	ms.c & ms.h
		The memory stream implementation simply provides a ease of use
		to take a chunk of memory and treat it like a stream of primitive
		types. This is very similar to the [stack.c] and [stack.h] 
		implementation.

	port.h
		This contains all the primitive type defines. They are stored in
		one file to make cross-platform changes easier to make.

	conf.h
		This simply stores any pre-processor directives that need to be
		global. Or, end up being global.

	rjvm.h & rjvm.c
		All the utility functions (or almost all) are kept in these two
		files. Also, most of the primary data structures for the VM are
		defined in the header. These are the heart of the VM, except for
		the actual interpretor which is stored in [exec.c] and [exec.h].

	exec.c & exec.h
		This is the interpretor core. It holds the primary routine for
		the interpretor. It makes use of various other sources and headers.

	stack.c & stack.h
		Both these files hold a implementation of a basic stack which 
		supports the push, pop, discardTop, and a debug routine.

	std.c & std.h
		These two files hold all the function call that would normally
		land in the standard runtime or library. This provides an easy
		way for the embedded developer to hook, emulate, or replace this
		functions. A minimal of standard calls are used in the JVM, but
		the ones that are used are placed in these files.

	rmalloc.c & rmalloc.h
		These hold the internal implementation of a malloc/free. They are
		called by the [std.c] implementation based on if a pre-processor
		directive has been set known as 'INTERNALMALLOC'. Only the [std.c]
		source file need be compiled with this directive. Although, from
		the time of this writting all source files are compiled with the
		directive which is set in [conf.h].
		
	conf.h
		Currently, only home to the pre-processor directive INTERNALMALLOC
=== SRCHEAD DIRECTORY ===
As implied this is the directory for heads to the JVM. A head is essentially
a frontend. It brings everything together and provides initialization and 
configuration. For example 'rhino.c' provides a command line head, while
'malloctestproxy.c' provides a command line proxy to the malloc and free
implementation. While, another head might provide a ARM bootstrap or 
something for an embedded system.

	rhino.c
		This holds the entry function. It prepares to interpret a Java
		class file. It also handles parsing command line arguments, and
		loading of class files into a bundle. 
		
		If you are going to embed or use the rhino project then this file
		is the one you will either edit the most or simply replace. It 
		currently provides testing from the command line.

	malloctestproxy.c
		Provides a command line interface through stdout and stdin pipes
		to test the malloc and free implemention. See 'malloctestproxy.py'.