Review request: White box testing API for HotSpot

[Mikael Gerdin]

On 2011-12-02 06:32, David Holmes wrote:
> 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?

Yes.

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

It won't work. They need to put it in the boot class path in order to 
get it to work. Additinally they'll need to add 
"-XX:+UnlockDiagnosticVMOptions -XX:+EnableWhiteboxAPI" to their command 
line.
But yes, it is not impossible to use from a "non-developer" build.

>
>> 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:

There are a couple of issues in these make files.
>
> 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:

For example, look in jsig.make. It has a target that copies libjsig to 
JDK_LIBDIR. JDK_LIBDIR is set up in vm.make to point to 
JAVA_HOME/jre/lib/[arch]. I was only trying to mimic existing behavior 
with the "install"-targets in the make files.

>
> $(JAVA_HOME)/lib/$(GENERATED)/wb.jar
>
> which doesn't seem right either.

Agreed, that's incorrect.

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

$ find . -name wb.jar
./build/linux-amd64/hotspot/import/jre/lib/endorsed/wb.jar
./build/linux-amd64/hotspot/outputdir/linux_amd64_compiler2/generated/wb.jar

The JDK makefiles that build the j2{sdk,re}-image directories do not 
pick up the wb.jar file.

>
> 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/

Because of security requirements and implementation details the Whitebox 
class must be available on the boot class path.
Putting the wb.jar file in the endorsed directory is a quick and easy 
way to achieve that.

Does this clarify your concerns?

/Mikael Gerdin

>
> ???
>
> 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