Review request: White box testing API for HotSpot

[David Holmes]

Hi Mikael,

On 30/11/2011 2:04 AM, Mikael Gerdin wrote:
> I've been working on a white box testing API for HotSpot in order to
> allow for improved precision in vm testing.
>
> The basic idea is to open up the possibility for tests written in Java
> to call native methods which query or poke the vm in some way.
>
> The API is accessible by using the class sun/hotspot/WhiteBox which is
> not intended to be available in public builds.

Where "public" means non-developer builds - right?

But what if someone simply puts wb.jar in their classpath?

> In order to allow the WhiteBox class access to the VM the
> registerNatives function is linked to JVM_RegisterWhiteBoxMethods. That
> function then links all the implementation functions using normal JNI
> RegisterNatives.
>
> The API is not meant to be used by end users for any intent or purpose
> and as such it is both guarded by "-XX:+UnlockDiagnosticVMOptions
> -XX:+EnableWhiteboxAPI" and the fact that the class files will not be
> present in an end user build of a JDK.

I'm a little confused as to where wb.jar ends up when I build hotspot. I 
see this in a makefile:

   26 WB = wb
   27
   28 WBSRCDIR = $(GAMMADIR)/src/share/tools/whitebox/src
   29
   30 WB_JAR = $(GENERATED)/$(WB).jar
   31
   32 DEST_WB_JAR = $(JAVA_HOME)/lib/$(WB_JAR)

Why JAVA_HOME? That's normally a binary installation of a JDK used for 
building, not somewhere I expect my build to try and put something. Plus 
the above will expand to:

   $(JAVA_HOME)/lib/$(GENERATED)/wb.jar

which doesn't seem right either.

And if I build a full JDK, where does wb.jar end up then?

I also see in make/Makefile:

  370 $(EXPORT_JRE_LIB_DIR)/endorsed/%.jar: $(GEN_DIR)/%.jar
  371         $(install-file)

Why the endorsed subdirectory? This is nothing to do with an "endorsed 
standard":

http://docs.oracle.com/javase/6/docs/technotes/guides/standards/

???

Thanks,
David
-----

> If the VM crashes after this API has been accessed a note will be
> written in the hs_err file to signal that the API has been used.
>
> Webrev:
> http://cr.openjdk.java.net/~stefank/mgerdin/wbapi.0/webrev/
> (thanks to stefank for hosting my webrev :)
>
> CR:
> I'll file a CR tomorrow.
>
> Change comments:
>
> make/jprt.properties
>
> Add a test target to make sure that the API is available on all
> supported platforms
>
> make/**
>
> Makefile changes to build the class sun/hotspot/WhiteBox, put it in a
> JAR file and copy it to the jre/lib/endorsed directory in the export
> targets.
> The BSD makefile changes are not tested since I don't have access to any
> BSD/OSX machine to test them on.
>
> src/share/vm/prims/nativeLookup.cpp
>
> Special-case the method sun/hotspot/WhiteBox/registerNatives and link it
> to JVM_RegisterWhiteBoxMethods
>
> src/share/vm/prims/whitebox.*
>
> The implementation of the white box API. The actual API functions are
> only examples of what we want to be able to do using the API.
>
> src/share/vm/runtime/globals.hpp
>
> Add the command line flag
>
> src/share/vm/utilities/vmError.cpp
>
> Print a message in hs_err files when white box API has been used.
>
> test/Makefile
>
> Add a makefile test target for the white box API test
>
> test/sanity/wbapi.java
>
> JTreg test to ensure that the API works.
>
>
> Thanks
> /Mikael Gerdin