JVM TI Demonstration Code

The Java^TM Virtual Machine Tools Interface (JVM TI) is a native tool interface provided in JDK 5.0 and newer. Native libraries that use JVM TI and are loaded into the Java Virtual Machine via the -agentlib, -agentpath, or -Xrun (deprecated) interfaces, are called Agents.

JVM TI was designed to work with the Java Native Interface (JNI), and eventually displace the Java Virtual Machine Debugging Interface (JVMDI) and the Java Virtual Machine Profiling Interface (JVMPI).

We have created a set of demonstration agents that should help show many of the features and abilities of the interface. This list of demonstration agents will change over time. They are provided as educational tools and as starting points for Java tool development.

These agents are built with every JDK build and some basic testing is performed on a regular basis, but no extensive testbases currently exist for these agents. Every JDK installation should include all the pre-built binaries and sources for all these agents, just look in the demo/jvmti directory of your JDK.

Using or Running These Agents

Using these agents will require the VM to locate the shared library file before any actual Java code is run. The JDK installation should contain all the agent libraries in the ${JAVA_HOME}/demo/jvmti/agent-name/lib directories. The Solaris 64bit version would be contained in the sparcv9 or amd64 subdirectory. If 'java' complains that it can't find the library, you may need to add the directory containing the library into the LD_LIBRARY_PATH environment variable (Unix), or the PATH environment variable (Windows). This is system and platform specific. If you are using 64bit Solaris (e.g. 'java -d64'), you should use LD_LIBRARY_PATH64. Some agents such as hprof (heap/cpu profiler) and jdwp (debugger backend) are located inside the primary JDK directories and will always be found in those locations.

The agents that instrument classfiles (i.e. BCI, usually through the java_crw_demo library) such as hprof, heapTracker, mtrace, and minst, also need to have the Java classes they use available in the bootclasspath. The one used by hprof is already in the bootclasspath, and the other agents will make attempts at automatically adding their jar file (e.g. heapTracker.jar, mtrace.jar, or minst.jar) to the bootclasspath with AddToBootstrapClassLoaderSearch from JVM TI at startup (see the agent_util code). This is done by locating this jar file at ${JAVA_HOME}/demo/jvmti/agent-name where JAVA_HOME is obtained by calling GetSystemProperty from JVM TI with "java.home". We recognize that this is not ideal, but felt that as just demonstration code it was acceptable. Ideally the agent could find out the actual directory it came from and locate the jar file relative to that location. Our demonstration agents currently do not do this.

If you choose to modify or change these agents, the above information is important in making everything is found. It is recommended that you change the name of the agent when you modify it to avoid conflicts with the existing demo agents. Or better yet, go to http://jdk.dev.java.net and submit your changes to the agent as an RFE to the JDK.

Demonstration Agents Available

• versionCheck
  This is a extremely small agent that does nothing but check the version string supplied in the jvmti.h file, with the version number supplied by the VM at runtime.
• mtrace
  This is a small agent that does method tracing. It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
• minst
  This is an even smaller agent that does just method entry tracing. It also uses Bytecode Instrumentation (BCI) via the java_crw_demo library, but the instrumentation code is pure Java (no Java native methods used). NOTE: Be sure to check out java.lang.instrument for a way to avoid native code agents completely.
• gctest
  This is a small agent that does garbage collection counting.
• heapViewer
  This is a small agent that does some basic heap inspections.
• heapTracker
  This is a small agent that does BCI to capture object creation and track them. It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
• waiters
  This is a small agent that gets information about threads waiting on monitors.
• hprof
  This is a large agent that does heap and cpu profiling. This demo agent is actually built into the Java Runtime Environment (JRE). It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
  Note: hprof is NOT a small or simple agent, the other smaller demos should be looked at first.

Agent Support

• java_crw_demo
  This is a demo C library that does class file to class file transformations or BCI (Bytecode Instrumentation). It is used by several of the above agents.

Native Library Build Hints

All libraries loaded into java are assumed to be MT-safe (Multi-thread safe). This means that multiple threads could be executing the code at the same time, and static or global data may need to be placed in critical sections. See the Raw Monitor interfaces for more information.

All native libraries loaded into the Java Virtual Machine, including Agent libraries, need to be compiled and built in a compatible way. Certain native compilation options or optimizations should be avoided, and some are required. More information on this options is available in the man pages for the various compilers.

Some native compiler and linker options can create fatal or erroneous behavior when native agent libraries are operating inside the Java Virtual Machine. It would take too many words to describe all the possible issues with all the native compiler options, optimizations, and settings. Here are some recommendations on the basic compiler and linker options we recommend:

Solaris

• On Solaris, using the Sun Studio 11 C compiler, the typical compile and link command lines might look something like:
  For 32bit SPARC:
  
  cc -xO2 -mt -xregs=no%appl -xmemalign=4s -xarch=v8 -KPIC -c *.c
cc -mt -xarch=v8 -z defs -ztext -G -o libXXX.so *.o -lc
  
  For 64bit SPARC:
  
  cc -xO2 -mt -xregs=no%appl -xarch=v9 -KPIC -c *.c
cc -mt -xarch=v9 -z defs -ztext -G -o libXXX.so *.o -lc
  
  For X86:
  
  cc -xO2 -mt -xregs=no%frameptr -KPIC -c *.c
cc -mt -z defs -ztext -G -o libXXX.so *.o -lc
  
  For AMD64:
  
  cc -xO2 -mt -xregs=no%frameptr -xarch=amd64 -KPIC -c *.c
cc -mt -xarch=amd64 -z defs -ztext -G -o libXXX.so *.o -lc
  
  
• Architecture/File Format: For SPARC 32bit use -xarch=v8, for SPARC 64bit use -xarch=v9, for X86 (32-bit) leave the option off or use -xarch=generic , and for AMD64 (64bit) use -xarch=amd64 with both C and C++.
  This is to be specific as to the architecture and the file format of the .o files (and ultimately of the .so).
• MT-Safe, Position Independent: Use -KPIC -mt with both C and C++.
• Register usage: For SPARC (both 32bit and 64bit) use -xregs=no%appl and for X86 and AMD64 use -xregs=no%frameptr with both C and C++.
• Alignment: For SPARC 32bit use -xmemalign=4s and for SPARC 64bit do NOT use -xmemalign=4 with both C and C++.
• Dependencies: Use ldd -r LibraryName.
  After the shared library has been built, the utility ldd can be used to verify that all dependent libraries have been satisfied, and all externs can be found. If ldd says anything is missing, it is very likely that the JVM will also be unable to load this library. This usually means that you missed some -lname options when building the library, or perhaps forgot a -R path option that tells the library where to look for libraries at runtime.

Linux

• On Linux, using the gcc version 3.2, the typical compile and link command lines might look something like:
  For X86:
  
  gcc -O2 -fPIC -pthread -DLINUX -c *.c
gcc -z defs -static-libgcc -shared -mimpure-text -o libXXX.so *.o -lc
  
  For AMD64:
  
  gcc -O2 -fPIC -pthread -DLINUX -D_LP64=1 -c *.c
gcc -z defs -static-libgcc -shared -mimpure-text -o libXXX.so *.o -lc
  
  
• MT-Safe, Position Independent: Use -fPIC -pthread.
• Agent Demo Code: Needs -DLINUX
• Register Usage: Use -fno-omit-frame-pointer.
  It is important that these libraries have frame pointer register usage, see the above comments on the Solaris -xregs=no%frameptr option.
• Library: Use -static-libgcc -mimpure-text.
  When building the shared library (-shared option), this option allows for maximum portability of the library between different flavors of Linux. The problem we have seen with Linux is that we cannot depend on a compatible shared gcc library existing on all the versions of Linux we can run on. By doing this static link, the version script becomes more important, making sure you don't expose any extern symbols you didn't intend to.
• Dependencies: Use ldd -r LibraryName.
  Provides the same checking as Solaris (see above).

Windows

• On Windows and using the Microsoft C++ Compiler Visual Studio .NET 2003, the typical compile and link command lines might look something like:
  For X86:
  
  cl /O1 /MD /D _STATIC_CPPLIB /c *.c
link /dll /opt:REF /out:XXX.dll *.obj
  
  For AMD64:
  
  cl /O1 /MD /D _STATIC_CPPLIB /c *.c
link /dll /opt:REF /out:XXX.dll *.obj
  
  
• Library: Use /opt:REF when building the dll.
• MS DLL Runtime: Use the /MD /D _STATIC_CPPLIB option.
  This causes your dll to become dependent on MSVCRT.DLL and/or the newer C++ runtime MSVCR71.DLL. The option /D _STATIC_CPPLIB prevents you from becoming dependent on the C++ library MSVCP71.DLL. This is what we use in the JDK, but there are probably many combinations that you could safely use, unfortunately there are many combinations of runtimes that will not work. Check the Microsoft site on proper use of runtimes.
• Dependencies: Use VC++ dumpbin /exports and the VC++ "Dependency Walker".
  Provides dependency information similar to ldd.

For More Information

Remember, the complete source to all these agents is contained in the JDK installations at demo/jvmti.

For more detailed information on JVM TI, refer to http://java.sun.com/j2se/latest/docs/guide/jvmti.

More information on using JNI and building native libraries refer to: http://java.sun.com/j2se/latest/docs/guide/jni.

Additional information can also be found by doing a search on "jvmti" at http://java.sun.com/j2se. Various technical articles are also available through this website. And don't forget the Java Tutorials at http://java.sun.com/docs/books/tutorial for getting a quick start on all the various interfaces.

Comments and Feedback

Comments regarding JVM TI or on any of these demonstrations should be sent through http://java.sun.com/mail/