1 <html>
   2 <head> <title>JVM TI Demonstration Code</title> </head>
   4 <h1>JVM TI Demonstration Code</h1>
   6 <p>
   7 The 
   8 Java&trade; Virtual Machine Tools Interface (JVM TI)
   9 is a native tool interface provided in JDK 5.0 and newer.
  10 Native libraries that use JVM TI and are loaded into the 
  11 Java Virtual Machine
  12 via the -agentlib, -agentpath, or -Xrun (deprecated) interfaces, are
  13 called Agents.
  14 <p>
  15 <A HREF="http://java.sun.com/j2se/latest/docs/guide/jvmti">JVM TI</A>
  16 was designed to work with the
  17 Java Native Interface 
  18 (<A HREF="http://java.sun.com/j2se/latest/docs/guide/jni">JNI</A>),
  19 and eventually displace the 
  20 Java Virtual Machine Debugging Interface 
  21 (<A HREF="http://java.sun.com/j2se/1.5.0/docs/guide/jpda/jvmdi-spec.html">JVMDI</A>)
  22 and the 
  23 Java Virtual Machine Profiling Interface 
  24 (<A HREF="http://java.sun.com/j2se/1.5.0/docs/guide/jvmpi/index.html">JVMPI</A>).
  26 <p>
  27 We have created a set of demonstration agents that should
  28 help show many of the features and abilities of the
  29 interface. This list of demonstration agents will change over time.
  30 They are provided as educational tools and as starting
  31 points for Java tool development.
  33 <p>
  34 These agents are built with every JDK build and some basic testing is performed
  35 on a regular basis, but no extensive testbases currently
  36 exist for these agents.
  37 Every JDK installation should include all the pre-built binaries and sources for
  38 all these agents, just look in the demo/jvmti directory of your JDK.
  41 <h2>Using or Running These Agents</h2>
  43 <p>
  44 Using these agents will require the VM to locate the shared library file
  45 before any actual Java code is run.
  46 The JDK installation should contain all the agent libraries in 
  47 the ${JAVA_HOME}/demo/jvmti/<i>agent-name</i>/lib directories.
  48 The Solaris 64bit version would be contained in the sparcv9 or amd64
  49 subdirectory.
  50 If 'java' complains that it can't find the library,
  51 you may need to add the directory containing the library into the
  52 LD_LIBRARY_PATH environment variable (Unix), or the PATH environment
  53 variable (Windows).
  54 This is system and platform specific.
  55 If you are using 64bit Solaris (e.g. 'java -d64'), 
  56 you should use LD_LIBRARY_PATH64.
  57 Some agents such as the jdwp (debugger backend)
  58 are located inside the primary JDK directories and will always be found
  59 in those locations.
  61 <p>
  62 The agents that instrument classfiles 
  63 (i.e. BCI, usually through the java_crw_demo library) 
  64 such as heapTracker, mtrace, and minst, 
  65 also need to have the Java classes they use available in the bootclasspath.
  66 The agents will make attempts at automatically adding their jar file
  67 (e.g. heapTracker.jar, mtrace.jar, or minst.jar) to the bootclasspath
  68 with AddToBootstrapClassLoaderSearch from JVM TI at startup
  69 (see the agent_util code).
  70 This is done by locating this jar file at 
  71 ${JAVA_HOME}/demo/jvmti/<i>agent-name</i>
  72 where JAVA_HOME is obtained by calling GetSystemProperty from JVM TI
  73 with "java.home".
  74 We recognize that this is not ideal, but felt that as just demonstration
  75 code it was acceptable.
  76 Ideally the agent could find out the actual directory it came from and
  77 locate the jar file relative to that location. 
  78 Our demonstration agents currently do not do this.
  80 <p>
  81 If you choose to modify or change these agents, the above information
  82 is important in making everything is found.
  83 It is recommended that you change the name of the agent when you
  84 modify it to avoid conflicts with the existing demo agents.
  85 Or better yet, go to http://jdk.dev.java.net and submit your
  86 changes to the agent as an RFE to the JDK.
  89 <h2> Demonstration Agents Available </h2>
  91 <ul>
  93 <li>
  94 <A HREF="versionCheck">versionCheck</A>
  95 <br>
  96 This is a extremely small agent that does nothing but check the
  97 version string supplied in the jvmti.h file, with the version
  98 number supplied by the VM at runtime.
  99 </li>
 101 <li>
 102 <A HREF="compiledMethodLoad">compiledMethodLoad</A>
 103 <br>
 104 This is a small agent that traces CompiledMethodLoad events along
 105 with the HotSpot specific compile_info parameter.
 106 </li>
 108 <li>
 109 <A HREF="mtrace">mtrace</A>
 110 <br>
 111 This is a small agent that does method tracing.
 112 It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
 113 </li>
 115 <li>
 116 <A HREF="minst">minst</A>
 117 <br>
 118 This is an even smaller agent that does just method entry tracing.
 119 It also uses Bytecode Instrumentation (BCI) via the java_crw_demo library,
 120 but the instrumentation code is pure Java (no Java native methods used).
 121 NOTE: Be sure to check out java.lang.instrument for a way to avoid
 122 native code agents completely.
 123 </li>
 125 <li>
 126 <A HREF="gctest">gctest</A>
 127 <br>
 128 This is a small agent that does garbage collection counting.
 129 </li>
 131 <li>
 132 <A HREF="heapViewer">heapViewer</A>
 133 <br>
 134 This is a small agent that does some basic heap inspections.
 135 </li>
 137 <li>
 138 <A HREF="heapTracker">heapTracker</A>
 139 <br>
 140 This is a small agent that does BCI to capture object creation
 141 and track them.
 142 It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
 143 </li>
 145 <li>
 146 <A HREF="waiters">waiters</A>
 147 <br>
 148 This is a small agent that gets information about threads
 149 waiting on monitors.
 150 </li>
 152 </ul>
 156 <h2>Agent Support</h2>
 158 <ul>
 160 <li>
 161 <A HREF="java_crw_demo">java_crw_demo</A>
 162 <br>
 163 This is a demo C library that does class file to class file
 164 transformations or BCI (Bytecode Instrumentation).
 165 It is used by several of the above agents.
 166 </li>
 169 </ul>
 173 <h2>Native Library Build Hints</h2>
 175 <p>
 176 All libraries loaded into java are assumed to be MT-safe (Multi-thread safe).
 177 This means that multiple threads could be executing the code at the same
 178 time, and static or global data may need to be placed in critical
 179 sections. See the Raw Monitor interfaces for more information.
 181 <p>
 182 All native libraries loaded into the 
 183 Java Virtual Machine,
 184 including Agent libraries,
 185 need to be compiled and built in a compatible way.
 186 Certain native compilation options or optimizations should be avoided,
 187 and some are required.
 188 More information on this options is available in the man pages for
 189 the various compilers.
 191 <p>
 192 Some native compiler and linker options can create fatal or 
 193 erroneous behavior when native agent libraries are operating
 194 inside the Java Virtual Machine.
 195 It would take too many words to describe all the possible issues with all
 196 the native compiler options, optimizations, and settings.
 197 Here are some recommendations on the basic compiler and linker options
 198 we recommend:
 200 <ul>
 202 <h3> Solaris </h3>
 204 <li>
 205 On Solaris, using the Sun Studio 11 C compiler,
 206 the typical compile and link command lines might look something like:
 207 <br>
 208 For 32bit SPARC:
 209 <br>
 210 <code><ul>
 211 cc -xO2 -mt -xregs=no%appl -xmemalign=4s -xarch=v8 -KPIC -c <i>*.c</i>
 212 <br>
 213 cc -mt -xarch=v8 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
 214 </code></ul>
 215 <br>
 216 For 64bit SPARC:
 217 <br>
 218 <code><ul>
 219 cc -xO2 -mt -xregs=no%appl -xarch=v9 -KPIC -c <i>*.c</i>
 220 <br>
 221 cc -mt -xarch=v9 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
 222 </code></ul>
 223 <br>
 224 For X86:
 225 <br>
 226 <code><ul>
 227 cc -xO2 -mt -xregs=no%frameptr -KPIC -c <i>*.c</i>
 228 <br>
 229 cc -mt -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
 230 </code></ul>
 231 <br>
 232 For AMD64:
 233 <br>
 234 <code><ul>
 235 cc -xO2 -mt -xregs=no%frameptr -xarch=amd64 -KPIC -c <i>*.c</i>
 236 <br>
 237 cc -mt -xarch=amd64 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
 238 </code></ul>
 239 <br>
 240 </li>
 242 <li>
 243 Architecture/File Format: 
 244 For SPARC 32bit use <code>-xarch=v8</code>, 
 245 for SPARC 64bit use <code>-xarch=v9</code>, 
 246 for X86 (32-bit) 
 247 <i>
 248 leave the option off or use <code>-xarch=generic</code>
 249 </i>,
 250 and for AMD64 (64bit) use <code>-xarch=amd64</code>
 251 with both C and C++.
 252 <br>
 253 This is to be specific as to the architecture and the file format
 254 of the .o files (and ultimately of the .so). 
 255 </li>
 257 <li>
 258 MT-Safe, Position Independent: Use <code>-KPIC -mt</code> 
 259 with both C and C++.
 260 </li>
 262 <li>
 263 Register usage: For SPARC (both 32bit and 64bit) use 
 264 <code>-xregs=no%appl</code> and for X86 and AMD64 use <code>-xregs=no%frameptr</code>
 265 with both C and C++.
 266 </li>
 268 <li>
 269 Alignment: For SPARC 32bit use -xmemalign=4s and for SPARC 64bit do NOT use <code>-xmemalign=4</code>
 270 with both C and C++.
 271 </li>
 273 <li>
 274 Dependencies: Use <code>ldd -r <i>LibraryName</i></code>.
 275 <br>
 276 After the shared library has been built, the utility
 277 <code>ldd</code> can be used to verify that all dependent libraries 
 278 have been satisfied, and all externs can be found.
 279 If <code>ldd</code> says anything is missing, it is very likely that the JVM will also
 280 be unable to load this library.
 281 This usually means that you missed some <code>-l<i>name</i></code>
 282 options when building the library, or perhaps forgot a <code>-R path</code>
 283 option that tells the library where to look for libraries at runtime.
 284 </li>
 286 <h3> Linux </h3>
 288 <li>
 289 On Linux, using the gcc version 3.2, 
 290 the typical compile and link command lines might look something like:
 291 <br>
 292 For X86:
 293 <br>
 294 <code><ul>
 295 gcc -O2 -fPIC -pthread -DLINUX -c <i>*.c</i>
 296 <br>
 297 gcc -z defs -static-libgcc -shared -o <i>libXXX.so *.o</i> -lc
 298 </code></ul>
 299 <br>
 300 For AMD64:
 301 <br>
 302 <code><ul>
 303 gcc -O2 -fPIC -pthread -DLINUX -D_LP64=1 -c <i>*.c</i>
 304 <br>
 305 gcc -z defs -static-libgcc -shared -o <i>libXXX.so *.o</i> -lc
 306 </code></ul>
 307 <br>
 308 </li>
 310 <li>
 311 MT-Safe, Position Independent: 
 312 Use <code>-fPIC -pthread</code>.
 313 </li>
 315 <li>
 316 Agent Demo Code: Needs -DLINUX
 317 </li>
 319 <li>
 320 Register Usage: Use <code>-fno-omit-frame-pointer</code>.
 321 <br>
 322 It is important that these libraries have frame pointer register usage, see the above comments on the Solaris 
 323 <code>-xregs=no%frameptr</code>
 324 option.
 325 </li>
 327 <li>
 328 Library: Use -static-libgcc.
 329 <br>
 330 When building the shared library (-shared option), this option
 331 allows for maximum portability of the library between different
 332 flavors of Linux.
 333 The problem we have seen with Linux is that we cannot depend
 334 on a compatible shared gcc library existing on all the versions of
 335 Linux we can run on.
 336 By doing this static link, the version script becomes more
 337 important, making sure you don't expose any extern symbols
 338 you didn't intend to.
 339 </li>
 341 <li>
 342 Dependencies: Use <code>ldd -r <i>LibraryName</i></code>.
 343 <br>
 344 Provides the same checking as Solaris (see above).
 345 </li>
 347 <h3> Windows </h3>
 349 <li>
 350 On Windows and using the Microsoft C++ Compiler Visual Studio .NET 2003,
 351 the typical compile and link command lines might look something like:
 352 <br>
 353 For X86:
 354 <br>
 355 <code><ul>
 356 cl /O1 /MD /D _STATIC_CPPLIB /c <i>*.c</i>
 357 <br>
 358 link /dll /opt:REF /out:<i>XXX.dll *.obj</i>
 359 </code></ul>
 360 <br>
 361 For AMD64:
 362 <br>
 363 <code><ul>
 364 cl /O1 /MD /D _STATIC_CPPLIB /c <i>*.c</i>
 365 <br>
 366 link /dll /opt:REF /out:<i>XXX.dll *.obj</i>
 367 </code></ul>
 368 <br>
 369 </li>
 371 <li>
 372 Library: Use <code>/opt:REF </code> when building the dll.
 373 </li>
 375 <li>
 376 MS DLL Runtime: Use the <code>/MD /D _STATIC_CPPLIB</code> option.
 377 <br>
 378 This causes your dll to become dependent on just MSVCR*.DLL.
 379 The option /D _STATIC_CPPLIB prevents you from becoming dependent on the
 380 C++ library MSVCP*.DLL.
 381 This is what we use in the JDK, but there are probably many combinations
 382 that you could safely use, unfortunately there are many combinations
 383 of runtimes that will not work. 
 384 Check the Microsoft site on proper use of runtimes.
 385 </li>
 387 <li>
 388 Dependencies: Use VC++ <code>dumpbin /exports</code> and the VC++ "Dependency Walker".
 389 <br>
 390 Provides dependency information similar to <code>ldd</code>.
 391 </li>
 393 </ul>
 396 <h2>For More Information</h2>
 398 <p>
 399 Remember, the complete source to all these agents is contained in the JDK
 400 installations at demo/jvmti.
 402 <p>
 403 For more detailed information on JVM TI, refer to 
 404 <A HREF="http://java.sun.com/j2se/latest/docs/guide/jvmti">
 405 http://java.sun.com/j2se/latest/docs/guide/jvmti.</A>
 407 <p>
 408 More information on using JNI and building native libraries refer to:
 409 <A HREF="http://java.sun.com/j2se/latest/docs/guide/jni">
 410 http://java.sun.com/j2se/latest/docs/guide/jni</A>.
 412 <p>
 413 Additional information can also be found by doing a search on "jvmti" at
 414 <A HREF="http://java.sun.com/j2se">http://java.sun.com/j2se</A>.
 415 Various technical articles are also available through this website.
 416 And don't forget the 
 417 Java Tutorials at 
 418 <A HREF="http://java.sun.com/docs/books/tutorial">http://java.sun.com/docs/books/tutorial</A>
 419 for getting a quick start on all the various interfaces.
 421 <h2>Comments and Feedback</h2>
 423 <p>
 424 Comments regarding JVM TI or on any of these demonstrations should be
 425 sent through 
 426 <A HREF="http://java.sun.com/mail">http://java.sun.com/mail/</A>
 430 </html>