Review request: White box testing API for HotSpot

David Holmes david.holmes at
Thu Dec 1 21:32:17 PST 2011

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
   28 WBSRCDIR = $(GAMMADIR)/src/share/tools/whitebox/src
   30 WB_JAR = $(GENERATED)/$(WB).jar
   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:


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 



> 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:
> (thanks to stefank for hosting my webrev :)
> CR:
> I'll file a CR tomorrow.
> Change comments:
> make/
> 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/
> JTreg test to ensure that the API works.
> Thanks
> /Mikael Gerdin

More information about the hotspot-dev mailing list