index.html revision 0
77N/A<html>
77N/A<head> <title>JVM TI Demonstration Code</title> </head>
77N/A
77N/A<h1>JVM TI Demonstration Code</h1>
77N/A
77N/A<p>
77N/AThe
77N/AJava<sup><font size=-2>TM</font></sup> Virtual Machine Tools Interface (JVM TI)
77N/Ais a native tool interface provided in JDK 5.0 and newer.
77N/ANative libraries that use JVM TI and are loaded into the
77N/AJava Virtual Machine
77N/Avia the -agentlib, -agentpath, or -Xrun (deprecated) interfaces, are
77N/Acalled Agents.
77N/A<p>
77N/A<A HREF="http://java.sun.com/j2se/latest/docs/guide/jvmti">JVM TI</A>
77N/Awas designed to work with the
77N/AJava Native Interface
77N/A(<A HREF="http://java.sun.com/j2se/latest/docs/guide/jni">JNI</A>),
77N/Aand eventually displace the
77N/AJava Virtual Machine Debugging Interface
1226N/A(<A HREF="http://java.sun.com/j2se/1.5.0/docs/guide/jpda/jvmdi-spec.html">JVMDI</A>)
77N/Aand the
77N/AJava Virtual Machine Profiling Interface
77N/A(<A HREF="http://java.sun.com/j2se/1.5.0/docs/guide/jvmpi/index.html">JVMPI</A>).
77N/A
77N/A<p>
457N/AWe have created a set of demonstration agents that should
77N/Ahelp show many of the features and abilities of the
77N/Ainterface. This list of demonstration agents will change over time.
77N/AThey are provided as educational tools and as starting
77N/Apoints for Java tool development.
77N/A
77N/A<p>
77N/AThese agents are built with every JDK build and some basic testing is performed
77N/Aon a regular basis, but no extensive testbases currently
77N/Aexist for these agents.
1251N/AEvery JDK installation should include all the pre-built binaries and sources for
77N/Aall these agents, just look in the demo/jvmti directory of your JDK.
77N/A
1181N/A
1190N/A<h2>Using or Running These Agents</h2>
457N/A
77N/A<p>
77N/AUsing these agents will require the VM to locate the shared library file
457N/Abefore any actual Java code is run.
457N/AThe JDK installation should contain all the agent libraries in
1190N/Athe ${JAVA_HOME}/demo/jvmti/<i>agent-name</i>/lib directories.
77N/AThe Solaris 64bit version would be contained in the sparcv9 or amd64
77N/Asubdirectory.
77N/AIf 'java' complains that it can't find the library,
77N/Ayou may need to add the directory containing the library into the
77N/ALD_LIBRARY_PATH environment variable (Unix), or the PATH environment
77N/Avariable (Windows).
77N/AThis is system and platform specific.
77N/AIf you are using 64bit Solaris (e.g. 'java -d64'),
77N/Ayou should use LD_LIBRARY_PATH64.
1269N/ASome agents such as hprof (heap/cpu profiler) and jdwp (debugger backend)
77N/Aare located inside the primary JDK directories and will always be found
77N/Ain those locations.
1190N/A
77N/A<p>
1251N/AThe agents that instrument classfiles
77N/A(i.e. BCI, usually through the java_crw_demo library)
77N/Asuch as hprof, heapTracker, mtrace, and minst,
77N/Aalso need to have the Java classes they use available in the bootclasspath.
1190N/AThe one used by hprof is already in the bootclasspath, and the
77N/Aother agents will make attempts at automatically adding their jar file
77N/A(e.g. heapTracker.jar, mtrace.jar, or minst.jar) to the bootclasspath
77N/Awith AddToBootstrapClassLoaderSearch from JVM TI at startup
1226N/A(see the agent_util code).
1226N/AThis is done by locating this jar file at
1226N/A${JAVA_HOME}/demo/jvmti/<i>agent-name</i>
1226N/Awhere JAVA_HOME is obtained by calling GetSystemProperty from JVM TI
1226N/Awith "java.home".
1226N/AWe recognize that this is not ideal, but felt that as just demonstration
1190N/Acode it was acceptable.
1226N/AIdeally the agent could find out the actual directory it came from and
1226N/Alocate the jar file relative to that location.
1226N/AOur demonstration agents currently do not do this.
1226N/A
77N/A<p>
1190N/AIf you choose to modify or change these agents, the above information
1226N/Ais important in making everything is found.
1226N/AIt is recommended that you change the name of the agent when you
1226N/Amodify it to avoid conflicts with the existing demo agents.
1226N/AOr better yet, go to http://jdk.dev.java.net and submit your
1226N/Achanges to the agent as an RFE to the JDK.
1226N/A
1226N/A
1226N/A<h2> Demonstration Agents Available </h2>
1226N/A
1226N/A<ul>
77N/A
1226N/A<li>
1226N/A<A HREF="versionCheck">versionCheck</A>
1226N/A<br>
1226N/AThis is a extremely small agent that does nothing but check the
1226N/Aversion string supplied in the jvmti.h file, with the version
1226N/Anumber supplied by the VM at runtime.
77N/A</li>
77N/A
77N/A<li>
1226N/A<A HREF="mtrace">mtrace</A>
1226N/A<br>
1226N/AThis is a small agent that does method tracing.
1226N/AIt uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
1226N/A</li>
77N/A
77N/A<li>
77N/A<A HREF="minst">minst</A>
1190N/A<br>
77N/AThis is an even smaller agent that does just method entry tracing.
77N/AIt also uses Bytecode Instrumentation (BCI) via the java_crw_demo library,
77N/Abut the instrumentation code is pure Java (no Java native methods used).
77N/ANOTE: Be sure to check out java.lang.instrument for a way to avoid
77N/Anative code agents completely.
77N/A</li>
1190N/A
77N/A<li>
77N/A<A HREF="gctest">gctest</A>
77N/A<br>
77N/AThis is a small agent that does garbage collection counting.
1190N/A</li>
77N/A
77N/A<li>
1190N/A<A HREF="heapViewer">heapViewer</A>
77N/A<br>
111N/AThis is a small agent that does some basic heap inspections.
111N/A</li>
111N/A
111N/A<li>
111N/A<A HREF="heapTracker">heapTracker</A>
1190N/A<br>
111N/AThis is a small agent that does BCI to capture object creation
77N/Aand track them.
77N/AIt uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
77N/A</li>
77N/A
77N/A<li>
1190N/A<A HREF="waiters">waiters</A>
77N/A<br>
77N/AThis is a small agent that gets information about threads
77N/Awaiting on monitors.
77N/A</li>
77N/A
1190N/A<li>
77N/A<A HREF="hprof">hprof</A>
77N/A<br>
77N/AThis is a large agent that does heap and cpu profiling.
77N/AThis demo agent is actually built into the
77N/A
77N/AJava Runtime Environment (JRE).
77N/AIt uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
77N/A<br>
<b>Note:</b> hprof is NOT a small or simple agent, the other smaller demos
should be looked at first.
</li>
</ul>
<h2>Agent Support</h2>
<ul>
<li>
<A HREF="java_crw_demo">java_crw_demo</A>
<br>
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.
</li>
</ul>
<h2>Native Library Build Hints</h2>
<p>
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.
<p>
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.
<p>
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:
<ul>
<h3> Solaris </h3>
<li>
On Solaris, using the Sun Studio 11 C compiler,
the typical compile and link command lines might look something like:
<br>
For 32bit SPARC:
<br>
<code><ul>
cc -xO2 -mt -xregs=no%appl -xmemalign=4s -xarch=v8 -KPIC -c <i>*.c</i>
<br>
cc -mt -xarch=v8 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
</code></ul>
<br>
For 64bit SPARC:
<br>
<code><ul>
cc -xO2 -mt -xregs=no%appl -xarch=v9 -KPIC -c <i>*.c</i>
<br>
cc -mt -xarch=v9 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
</code></ul>
<br>
For X86:
<br>
<code><ul>
cc -xO2 -mt -xregs=no%frameptr -KPIC -c <i>*.c</i>
<br>
cc -mt -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
</code></ul>
<br>
For AMD64:
<br>
<code><ul>
cc -xO2 -mt -xregs=no%frameptr -xarch=amd64 -KPIC -c <i>*.c</i>
<br>
cc -mt -xarch=amd64 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
</code></ul>
<br>
</li>
<li>
Architecture/File Format:
For SPARC 32bit use <code>-xarch=v8</code>,
for SPARC 64bit use <code>-xarch=v9</code>,
for X86 (32-bit)
<i>
leave the option off or use <code>-xarch=generic</code>
</i>,
and for AMD64 (64bit) use <code>-xarch=amd64</code>
with both C and C++.
<br>
This is to be specific as to the architecture and the file format
of the .o files (and ultimately of the .so).
</li>
<li>
MT-Safe, Position Independent: Use <code>-KPIC -mt</code>
with both C and C++.
</li>
<li>
Register usage: For SPARC (both 32bit and 64bit) use
<code>-xregs=no%appl</code> and for X86 and AMD64 use <code>-xregs=no%frameptr</code>
with both C and C++.
</li>
<li>
Alignment: For SPARC 32bit use -xmemalign=4s and for SPARC 64bit do NOT use <code>-xmemalign=4</code>
with both C and C++.
</li>
<li>
Dependencies: Use <code>ldd -r <i>LibraryName</i></code>.
<br>
After the shared library has been built, the utility
<code>ldd</code> can be used to verify that all dependent libraries
have been satisfied, and all externs can be found.
If <code>ldd</code> 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 <code>-l<i>name</i></code>
options when building the library, or perhaps forgot a <code>-R path</code>
option that tells the library where to look for libraries at runtime.
</li>
<h3> Linux </h3>
<li>
On Linux, using the gcc version 3.2,
the typical compile and link command lines might look something like:
<br>
For X86:
<br>
<code><ul>
gcc -O2 -fPIC -pthread -DLINUX -c <i>*.c</i>
<br>
gcc -z defs -static-libgcc -shared -mimpure-text -o <i>libXXX.so *.o</i> -lc
</code></ul>
<br>
For AMD64:
<br>
<code><ul>
gcc -O2 -fPIC -pthread -DLINUX -D_LP64=1 -c <i>*.c</i>
<br>
gcc -z defs -static-libgcc -shared -mimpure-text -o <i>libXXX.so *.o</i> -lc
</code></ul>
<br>
</li>
<li>
MT-Safe, Position Independent:
Use <code>-fPIC -pthread</code>.
</li>
<li>
Agent Demo Code: Needs -DLINUX
</li>
<li>
Register Usage: Use <code>-fno-omit-frame-pointer</code>.
<br>
It is important that these libraries have frame pointer register usage, see the above comments on the Solaris
<code>-xregs=no%frameptr</code>
option.
</li>
<li>
Library: Use -static-libgcc -mimpure-text.
<br>
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.
</li>
<li>
Dependencies: Use <code>ldd -r <i>LibraryName</i></code>.
<br>
Provides the same checking as Solaris (see above).
</li>
<h3> Windows </h3>
<li>
On Windows and using the Microsoft C++ Compiler Visual Studio .NET 2003,
the typical compile and link command lines might look something like:
<br>
For X86:
<br>
<code><ul>
cl /O1 /MD /D _STATIC_CPPLIB /c <i>*.c</i>
<br>
link /dll /opt:REF /out:<i>XXX.dll *.obj</i>
</code></ul>
<br>
For AMD64:
<br>
<code><ul>
cl /O1 /MD /D _STATIC_CPPLIB /c <i>*.c</i>
<br>
link /dll /opt:REF /out:<i>XXX.dll *.obj</i>
</code></ul>
<br>
</li>
<li>
Library: Use <code>/opt:REF </code> when building the dll.
</li>
<li>
MS DLL Runtime: Use the <code>/MD /D _STATIC_CPPLIB</code> option.
<br>
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.
</li>
<li>
Dependencies: Use VC++ <code>dumpbin /exports</code> and the VC++ "Dependency Walker".
<br>
Provides dependency information similar to <code>ldd</code>.
</li>
</ul>
<h2>For More Information</h2>
<p>
Remember, the complete source to all these agents is contained in the JDK
installations at demo/jvmti.
<p>
For more detailed information on JVM TI, refer to
<A HREF="http://java.sun.com/j2se/latest/docs/guide/jvmti">
http://java.sun.com/j2se/latest/docs/guide/jvmti.</A>
<p>
More information on using JNI and building native libraries refer to:
<A HREF="http://java.sun.com/j2se/latest/docs/guide/jni">
http://java.sun.com/j2se/latest/docs/guide/jni</A>.
<p>
Additional information can also be found by doing a search on "jvmti" at
<A HREF="http://java.sun.com/j2se">http://java.sun.com/j2se</A>.
Various technical articles are also available through this website.
And don't forget the
Java Tutorials at
<A HREF="http://java.sun.com/docs/books/tutorial">http://java.sun.com/docs/books/tutorial</A>
for getting a quick start on all the various interfaces.
<h2>Comments and Feedback</h2>
<p>
Comments regarding JVM TI or on any of these demonstrations should be
sent through
<A HREF="http://java.sun.com/mail">http://java.sun.com/mail/</A>
</html>