Documenting the interfaces to the VM

[Christian Wimmer]

I like the idea of a well-documented and well-specified VM interface. 
For the Maxine VM project [1], we implement a meta-circular VM (Java VM 
written completely in Java) that drops into an unmodified JDK.

For that, we have to replace all VM-specific methods of the JDK (which 
are mostly native methods). We use method substitution to achieve this, 
i.e., we have a mechanism to replace JDK methods with our own 
(Java-based) implementation.  The source code is freely available [2]. 
If you are interested in all the points we identified, look at the 
project "com.oracle.max.vm", in the package "com.sun.max.vm.jdk".  It 
contains a class for every JDK class that needs replacements, using an 
intuitive naming scheme. The substitution methods are annotated with 
@SUBSTITUTE

The class com.sun.max.vm.jni.JmmFunctions contains our implementation of 
the native interface, i.e., entry points into the VM called from JDK 
native code.

I hope that is a helpful initial list of VM-JDK connection points. If 
you have any questions or need more details about the Maxine code base, 
I am happy to assist you.

-Christian

[1] https://wikis.oracle.com/display/MaxineVM/Home
[2] http://kenai.com/projects/maxine


On 05/10/2012 04:08 AM, Neil Richards wrote:
> Hi all,
> As previously trailed [1], I'm looking to work on improving the
> (sometimes scarce) documentation of the interfaces to the VM.
>
> In doing this, I hope to produce a clear definition that any alternative
> (or subsequent) VM implementation can follow.
>
> Also, it will hopefully expose any "rough edges" - places where the user
> or application developer is unnecessarily exposed to VM implementation
> details - and suitable resolutions considered.
>
> I'm looking to do this work primarily in the CVMI project, and on the
> 'cvmi-dev' mailing list. As the documentation gets fleshed out, I expect
> that other potentially-interested parties (Hotspot, Zero, porting
> projects, Jigsaw?) will consider consuming the resulting changes.
>
> In particular, I expect there will be a healthy interchange between this
> work and that of the newly-proposed PPC/AIX porting project [2], given
> their stated interest in this area.
>
> Obviously, any assistance (particularly in review, to make sure I'm not
> writing complete fiction!) will be warmly welcomed :)
>
> For native interfaces, I'm proposing the use of 'doxygen' [3] as a means
> to produce the formatted documentation. This allows the documentation
> source to be held in a Javadoc-like style alongside the code in the
> header files themselves - a familiar and, I hope, fairly uncontroversial
> approach.
>
> Please let me know any suggestions or questions you have about this.
> Thanks,
> Neil
>
> [1] http://mail.openjdk.java.net/pipermail/discuss/2012-May/002622.html
> [2] http://mail.openjdk.java.net/pipermail/discuss/2012-May/002618.html
> [3] http://www.doxygen.org
>