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