Improving the documention of the JVM implementation interface

[Steve Poole]

On Fri, 2011-12-02 at 14:59 +0100, Mikael Vidstedt wrote:
> As Steve says, improving and clarifying the the dependencies and 
> interaction points between the JVM and the libraries is something I'm 
> happy to support. The JVM_* functions already have some documentation, 
> but even there I'm sure there are things that can be clarified, and I 
> fully agree that things like Attach functionality could use some 
> documentation work.

> One thing I'd like to stress is that the goal of this project should not 
> be to lock down the interface between the JVM and the JDK. Even though 
> we should for a number of different reasons try to keep the interfaces 
> changes to a minimum, we need to preserve the right to change them 
> without having to go through lengthy standardization processes etc. I 
> don't think that contradicts the goal of this project though.
> 
> I'm sure there are people who have been involved in projects where 
> documentation like this would have been very helpful. If at all possible 
> I'd like to encourage you to share your thoughts on this and if possible 
> help us out going forward.

Thanks Mikael. The JVM_* functions would be a great place to start
improving the doc since it's already a known, shared, interface. 

I'd also like to use a doc tool to create nice readable doc - what do
people think about  updating  jvm.h with doxygen style comments and then
using doxygen to create the docs?


> 
> Thanks,
> Mikael
> 
> 
> 
> On 2011-11-29 15:30, Steve Poole wrote:
> > 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
> >>
> >>
> >>
> >>
> >
>