0N/A<
head> <
title>JVM TI Demonstration Code</
title> </
head>
0N/A<
h1>JVM TI Demonstration Code</
h1>
0N/AJava<
sup><
font size=-
2>TM</
font></
sup> Virtual Machine Tools Interface (JVM TI)
0N/Ais a native tool interface provided in JDK 5.0 and newer.
0N/ANative libraries that use JVM TI and are loaded into the
0N/Avia the -agentlib, -agentpath, or -Xrun (deprecated) interfaces, are
0N/Awas designed to work with the
0N/AJava Native Interface
0N/Aand eventually displace the
0N/AJava Virtual Machine Debugging Interface
0N/AJava Virtual Machine Profiling Interface
0N/AWe have created a set of demonstration agents that should
0N/Ahelp show many of the features and abilities of the
0N/Ainterface. This list of demonstration agents will change over time.
0N/AThey are provided as educational tools and as starting
0N/Apoints for Java tool development.
0N/AThese agents are built with every JDK build and some basic testing is performed
0N/Aon a regular basis, but no extensive testbases currently
0N/Aexist for these agents.
0N/AEvery JDK installation should include all the pre-built binaries and sources for
0N/Aall these agents, just look in the
demo/
jvmti directory of your JDK.
0N/A<
h2>Using or Running These Agents</
h2>
0N/AUsing these agents will require the VM to locate the shared library file
0N/Abefore any actual Java code is run.
0N/AThe JDK installation should contain all the agent libraries in
0N/Athe ${JAVA_HOME}/
demo/
jvmti/<
i>agent-name</
i>/lib directories.
0N/AThe Solaris 64bit version would be contained in the sparcv9 or amd64
0N/AIf 'java' complains that it can't find the library,
0N/Ayou may need to add the directory containing the library into the
0N/ALD_LIBRARY_PATH environment variable (Unix), or the PATH environment
0N/AThis is system and platform specific.
0N/AIf you are using 64bit Solaris (
e.g. 'java -d64'),
0N/Ayou should use LD_LIBRARY_PATH64.
0N/ASome agents such as hprof (
heap/
cpu profiler) and jdwp (debugger backend)
0N/Aare located inside the primary JDK directories and will always be found
0N/AThe agents that instrument classfiles
0N/A(
i.e. BCI, usually through the java_crw_demo library)
0N/Asuch as hprof, heapTracker, mtrace, and minst,
0N/Aalso need to have the Java classes they use available in the bootclasspath.
0N/AThe one used by hprof is already in the bootclasspath, and the
0N/Aother agents will make attempts at automatically adding their jar file
0N/Awith AddToBootstrapClassLoaderSearch from JVM TI at startup
0N/A(see the agent_util code).
0N/AThis is done by locating this jar file at
0N/Awhere JAVA_HOME is obtained by calling GetSystemProperty from JVM TI
0N/AWe recognize that this is not ideal, but felt that as just demonstration
0N/Acode it was acceptable.
0N/AIdeally the agent could find out the actual directory it came from and
0N/Alocate the jar file relative to that location.
0N/AOur demonstration agents currently do not do this.
0N/AIf you choose to modify or change these agents, the above information
0N/Ais important in making everything is found.
0N/AIt is recommended that you change the name of the agent when you
0N/Amodify it to avoid conflicts with the existing demo agents.
0N/Achanges to the agent as an RFE to the JDK.
0N/A<
h2> Demonstration Agents Available </
h2>
0N/A<
A HREF="versionCheck">versionCheck</
A>
0N/AThis is a extremely small agent that does nothing but check the
0N/Aversion string supplied in the
jvmti.h file, with the version
0N/Anumber supplied by the VM at runtime.
2106N/A<
A HREF="compiledMethodLoad">compiledMethodLoad</
A>
2106N/AThis is a small agent that traces CompiledMethodLoad events along
2106N/Awith the HotSpot specific compile_info parameter.
0N/A<
A HREF="mtrace">mtrace</
A>
0N/AThis is a small agent that does method tracing.
0N/AIt uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
0N/A<
A HREF="minst">minst</
A>
0N/AThis is an even smaller agent that does just method entry tracing.
0N/AIt also uses Bytecode Instrumentation (BCI) via the java_crw_demo library,
0N/Abut the instrumentation code is pure Java (no Java native methods used).
0N/Anative code agents completely.
0N/A<
A HREF="gctest">gctest</
A>
0N/AThis is a small agent that does garbage collection counting.
0N/A<
A HREF="heapViewer">heapViewer</
A>
0N/AThis is a small agent that does some basic heap inspections.
0N/A<
A HREF="heapTracker">heapTracker</
A>
0N/AThis is a small agent that does BCI to capture object creation
0N/AIt uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
0N/A<
A HREF="waiters">waiters</
A>
0N/AThis is a small agent that gets information about threads
0N/A<
A HREF="hprof">hprof</
A>
0N/AThis is a large agent that does heap and cpu profiling.
0N/AThis demo agent is actually built into the
0N/AJava Runtime Environment (JRE).
0N/AIt uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
0N/A<
b>Note:</
b> hprof is NOT a small or simple agent, the other smaller demos
0N/Ashould be looked at first.
0N/A<
h2>Agent Support</
h2>
0N/A<
A HREF="java_crw_demo">java_crw_demo</
A>
0N/AThis is a demo C library that does class file to class file
0N/Atransformations or BCI (Bytecode Instrumentation).
0N/AIt is used by several of the above agents.
0N/A<
h2>Native Library Build Hints</
h2>
0N/AAll libraries loaded into java are assumed to be MT-safe (Multi-thread safe).
0N/AThis means that multiple threads could be executing the code at the same
0N/Atime, and static or global data may need to be placed in critical
0N/Asections. See the Raw Monitor interfaces for more information.
0N/AAll native libraries loaded into the
0N/AJava Virtual Machine,
0N/Aincluding Agent libraries,
0N/Aneed to be compiled and built in a compatible way.
0N/ACertain native compilation options or optimizations should be avoided,
0N/Aand some are required.
0N/AMore information on this options is available in the man pages for
0N/Athe various compilers.
0N/ASome native compiler and linker options can create fatal or
0N/Aerroneous behavior when native agent libraries are operating
0N/Ainside the Java Virtual Machine.
0N/AIt would take too many words to describe all the possible issues with all
0N/Athe native compiler options, optimizations, and settings.
0N/AHere are some recommendations on the basic compiler and linker options
0N/AOn Solaris, using the Sun Studio 11 C compiler,
0N/Athe typical compile and link command lines might look something like:
0N/Acc -xO2 -mt -xregs=no%appl -xmemalign=4s -xarch=v8 -KPIC -c <
i>*.c</
i>
0N/Acc -mt -xarch=v8 -z defs -ztext -G -o <
i>
libXXX.so *.o</
i> -lc
0N/Acc -xO2 -mt -xregs=no%appl -xarch=v9 -KPIC -c <
i>*.c</
i>
0N/Acc -mt -xarch=v9 -z defs -ztext -G -o <
i>
libXXX.so *.o</
i> -lc
0N/Acc -xO2 -mt -xregs=no%frameptr -KPIC -c <
i>*.c</
i>
0N/Acc -xO2 -mt -xregs=no%frameptr -xarch=amd64 -KPIC -c <
i>*.c</
i>
0N/Acc -mt -xarch=amd64 -z defs -ztext -G -o <
i>
libXXX.so *.o</
i> -lc
0N/AFor SPARC 32bit use <
code>-xarch=v8</
code>,
0N/Afor SPARC 64bit use <
code>-xarch=v9</
code>,
0N/Aleave the option off or use <
code>-xarch=generic</
code>
0N/Aand for AMD64 (64bit) use <
code>-xarch=amd64</
code>
0N/AThis is to be specific as to the architecture and the file format
0N/Aof the .o files (and ultimately of the .so).
0N/AMT-Safe, Position Independent: Use <
code>-KPIC -mt</
code>
0N/ARegister usage: For SPARC (both 32bit and 64bit) use
0N/A<
code>-xregs=no%appl</
code> and for X86 and AMD64 use <
code>-xregs=no%frameptr</
code>
0N/AAlignment: For SPARC 32bit use -xmemalign=4s and for SPARC 64bit do NOT use <
code>-xmemalign=4</
code>
0N/ADependencies: Use <
code>ldd -r <
i>LibraryName</
i></
code>.
0N/AAfter the shared library has been built, the utility
0N/A<
code>ldd</
code> can be used to verify that all dependent libraries
0N/Ahave been satisfied, and all externs can be found.
0N/AIf <
code>ldd</
code> says anything is missing, it is very likely that the JVM will also
0N/Abe unable to load this library.
0N/AThis usually means that you missed some <
code>-l<
i>name</
i></
code>
0N/Aoptions when building the library, or perhaps forgot a <
code>-R path</
code>
0N/Aoption that tells the library where to look for libraries at runtime.
0N/AOn Linux, using the gcc version 3.2,
0N/Athe typical compile and link command lines might look something like:
0N/Agcc -O2 -fPIC -pthread -DLINUX -c <
i>*.c</
i>
0N/Agcc -O2 -fPIC -pthread -DLINUX -D_LP64=1 -c <
i>*.c</
i>
0N/AMT-Safe, Position Independent:
0N/AUse <
code>-fPIC -pthread</
code>.
0N/AAgent Demo Code: Needs -DLINUX
0N/ARegister Usage: Use <
code>-fno-omit-frame-pointer</
code>.
0N/AIt is important that these libraries have frame pointer register usage, see the above comments on the Solaris
0N/A<
code>-xregs=no%frameptr</
code>
5029N/ALibrary: Use -static-libgcc.
0N/AWhen building the shared library (-shared option), this option
0N/Aallows for maximum portability of the library between different
0N/AThe problem we have seen with Linux is that we cannot depend
0N/Aon a compatible shared gcc library existing on all the versions of
0N/ABy doing this static link, the version script becomes more
0N/Aimportant, making sure you don't expose any extern symbols
0N/Ayou didn't intend to.
0N/ADependencies: Use <
code>ldd -r <
i>LibraryName</
i></
code>.
0N/AProvides the same checking as Solaris (see above).
0N/AOn Windows and using the Microsoft C++ Compiler Visual Studio .NET 2003,
0N/Athe typical compile and link command lines might look something like:
0N/Acl /O1 /MD /D _STATIC_CPPLIB /c <
i>*.c</
i>
0N/Acl /O1 /MD /D _STATIC_CPPLIB /c <
i>*.c</
i>
0N/ALibrary: Use <
code>/opt:REF </
code> when building the dll.
0N/AMS DLL Runtime: Use the <
code>/MD /D _STATIC_CPPLIB</
code> option.
3429N/AThis causes your dll to become dependent on just MSVCR*.DLL.
0N/AThe option /D _STATIC_CPPLIB prevents you from becoming dependent on the
0N/AThis is what we use in the JDK, but there are probably many combinations
0N/Athat you could safely use, unfortunately there are many combinations
0N/Aof runtimes that will not work.
0N/ACheck the Microsoft site on proper use of runtimes.
0N/ADependencies: Use VC++ <
code>dumpbin /exports</
code> and the VC++ "Dependency Walker".
0N/AProvides dependency information similar to <
code>ldd</
code>.
0N/A<
h2>For More Information</
h2>
0N/ARemember, the complete source to all these agents is contained in the JDK
0N/AFor more detailed information on JVM TI, refer to
0N/AMore information on using JNI and building native libraries refer to:
0N/AAdditional information can also be found by doing a search on "jvmti" at
0N/AVarious technical articles are also available through this website.
0N/Afor getting a quick start on all the various interfaces.
0N/A<
h2>Comments and Feedback</
h2>
0N/AComments regarding JVM TI or on any of these demonstrations should be