diff -r fd16c54261b3 -r 90ce3da70b43 jdk/src/share/demo/jvmti/index.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/jdk/src/share/demo/jvmti/index.html Sat Dec 01 00:00:00 2007 +0000 @@ -0,0 +1,438 @@ + + JVM TI Demonstration Code + +

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: +
+
+
+For 64bit SPARC: +
+
+
+For X86: +
+
+
+For AMD64: +
+
+
+
+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: +
+
+
+For AMD64: +
+
+
+
+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: +
+
+
+For AMD64: +
+
+
+
+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/ + + + +