Improving the documention of the JVM implementation interface

[Steve Poole]

On Thu, 2011-11-24 at 11:26 +0800, Krystal Mok wrote:
> Hi Steve,
> 
> 
> There's been some efforts in this area before. There's an OpenJDK
> project called "Common VM Interface" [1], ran by Dr Andrew John
> Hughes. One of the earlier notes can be found at [2]. The aims of this
> project seems to be in the same direction as what you're looking for.

Hi Krystal - sorry for the delay in responding: been somewhat email
server challenged.    Its possible the cmvi project could be used to do
this work but it seems very quiet at the moment.  Besides, this proposal
is about documenting what exists today,  so I'd rather have the
conversation on a mailing list that the people who know frequent :-)
> 
> 
> Xi Yang has been working on integrating OpenJDK class libraries into
> Jikes RVM this year. This work also needed a definition of the VM
> interface in OpenJDK. He's made quite a lot of progress already, so he
> might be able to help out with this documentation proposal. I'm cc'ing
> this mail to him.
> 
> 
> - Kris
> 
> 
> [1]: http://openjdk.java.net/projects/cvmi/
> [2]: http://mail.openjdk.java.net/pipermail/cvmi-dev/2008-July/000006.html
> 
> On Wed, Nov 23, 2011 at 10:29 PM, Steve Poole
> <spoole at linux.vnet.ibm.com> wrote:
>         Hi all,  I've been talking to Mikael Vidstedt and a few other
>         Oracle
>         luminaries about improving the documentation of the  interface
>         between
>         the JVM and the rest of the SDK.
>         
>         We wanted to make that discussion public hence this post.
>          I'll start
>         and Mikael can jump in.
>         
>         What I'm trying to do is simply gain some agreement on what
>         code is JVM
>         implementation specific and what isn't.  Then, where this JVM
>         implementation specific code interacts with the SDK, improve
>         the
>         documentation.
>         
>         A few examples to consider...
>         
>         JVM_* entry points in the VM that are there for the class
>         library code
>         to call: these are not part of the public JNI spec - I'd like
>         to get
>         them documented in more detail.
>         
>         These extra entry points can blur the line between the JVM and
>         the class
>         libraries: sometimes making  it's difficult to work out if the
>         "real"
>         API is the C entry point or the calling Java class. To put it
>         another
>         way  - there is Java code that is intentionally JVM
>         implementation
>         specific.   I'd like to get that status documented.
>         
>         Another similar example is where Hotspot code leaks out of the
>         JVM into
>         the class libs and tools.   The Late Attach API is a good (or
>         is that
>         bad) example. Sometimes it's difficult to work out if that
>         leakage is
>         intentional or inadvertent.  I'd like to get that status
>         documented too.
>         
>         So to recap:  what I'd like to do is discover and document the
>         API
>         between the JVM implementation specific code and everything
>         else.
>         Hopefully in the process improving everyone's awareness and
>         getting some
>         common agreement over actual behaviour or design versus
>         intention.  This
>         work might discover areas that could benefit from improved
>         interface
>         design and some form of  refactoring but that would be for
>         later.
>         
>         
>         Thanks
>         
>         Steve
>         
>         
> 
>