1 <html> 2 <head> <title>JVM TI Demonstration Code</title> </head> 3 4 <h1>JVM TI Demonstration Code</h1> 5 6 <p> 7 The 8 Java<sup><font size=-2>TM</font></sup> 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>). 25 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. 32 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. 39 40 41 <h2>Using or Running These Agents</h2> 42 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 hprof (heap/cpu profiler) and jdwp (debugger backend) 58 are located inside the primary JDK directories and will always be found 59 in those locations. 60 61 <p> 62 The agents that instrument classfiles 63 (i.e. BCI, usually through the java_crw_demo library) 64 such as hprof, heapTracker, mtrace, and minst, 65 also need to have the Java classes they use available in the bootclasspath. 66 The one used by hprof is already in the bootclasspath, and the 67 other agents will make attempts at automatically adding their jar file 68 (e.g. heapTracker.jar, mtrace.jar, or minst.jar) to the bootclasspath 69 with AddToBootstrapClassLoaderSearch from JVM TI at startup 70 (see the agent_util code). 71 This is done by locating this jar file at 72 ${JAVA_HOME}/demo/jvmti/<i>agent-name</i> 73 where JAVA_HOME is obtained by calling GetSystemProperty from JVM TI 74 with "java.home". 75 We recognize that this is not ideal, but felt that as just demonstration 76 code it was acceptable. 77 Ideally the agent could find out the actual directory it came from and 78 locate the jar file relative to that location. 79 Our demonstration agents currently do not do this. 80 81 <p> 82 If you choose to modify or change these agents, the above information 83 is important in making everything is found. 84 It is recommended that you change the name of the agent when you 85 modify it to avoid conflicts with the existing demo agents. 86 Or better yet, go to http://jdk.dev.java.net and submit your 87 changes to the agent as an RFE to the JDK. 88 89 90 <h2> Demonstration Agents Available </h2> 91 92 <ul> 93 94 <li> 95 <A HREF="versionCheck">versionCheck</A> 96 <br> 97 This is a extremely small agent that does nothing but check the 98 version string supplied in the jvmti.h file, with the version 99 number supplied by the VM at runtime. 100 </li> 101 102 <li> 103 <A HREF="mtrace">mtrace</A> 104 <br> 105 This is a small agent that does method tracing. 106 It uses Bytecode Instrumentation (BCI) via the java_crw_demo library. 107 </li> 108 109 <li> 110 <A HREF="minst">minst</A> 111 <br> 112 This is an even smaller agent that does just method entry tracing. 113 It also uses Bytecode Instrumentation (BCI) via the java_crw_demo library, 114 but the instrumentation code is pure Java (no Java native methods used). 115 NOTE: Be sure to check out java.lang.instrument for a way to avoid 116 native code agents completely. 117 </li> 118 119 <li> 120 <A HREF="gctest">gctest</A> 121 <br> 122 This is a small agent that does garbage collection counting. 123 </li> 124 125 <li> 126 <A HREF="heapViewer">heapViewer</A> 127 <br> 128 This is a small agent that does some basic heap inspections. 129 </li> 130 131 <li> 132 <A HREF="heapTracker">heapTracker</A> 133 <br> 134 This is a small agent that does BCI to capture object creation 135 and track them. 136 It uses Bytecode Instrumentation (BCI) via the java_crw_demo library. 137 </li> 138 139 <li> 140 <A HREF="waiters">waiters</A> 141 <br> 142 This is a small agent that gets information about threads 143 waiting on monitors. 144 </li> 145 146 <li> 147 <A HREF="hprof">hprof</A> 148 <br> 149 This is a large agent that does heap and cpu profiling. 150 This demo agent is actually built into the 151 152 Java Runtime Environment (JRE). 153 It uses Bytecode Instrumentation (BCI) via the java_crw_demo library. 154 <br> 155 <b>Note:</b> hprof is NOT a small or simple agent, the other smaller demos 156 should be looked at first. 157 </li> 158 159 </ul> 160 161 162 163 <h2>Agent Support</h2> 164 165 <ul> 166 167 <li> 168 <A HREF="java_crw_demo">java_crw_demo</A> 169 <br> 170 This is a demo C library that does class file to class file 171 transformations or BCI (Bytecode Instrumentation). 172 It is used by several of the above agents. 173 </li> 174 175 176 </ul> 177 178 179 180 <h2>Native Library Build Hints</h2> 181 182 <p> 183 All libraries loaded into java are assumed to be MT-safe (Multi-thread safe). 184 This means that multiple threads could be executing the code at the same 185 time, and static or global data may need to be placed in critical 186 sections. See the Raw Monitor interfaces for more information. 187 188 <p> 189 All native libraries loaded into the 190 Java Virtual Machine, 191 including Agent libraries, 192 need to be compiled and built in a compatible way. 193 Certain native compilation options or optimizations should be avoided, 194 and some are required. 195 More information on this options is available in the man pages for 196 the various compilers. 197 198 <p> 199 Some native compiler and linker options can create fatal or 200 erroneous behavior when native agent libraries are operating 201 inside the Java Virtual Machine. 202 It would take too many words to describe all the possible issues with all 203 the native compiler options, optimizations, and settings. 204 Here are some recommendations on the basic compiler and linker options 205 we recommend: 206 207 <ul> 208 209 <h3> Solaris </h3> 210 211 <li> 212 On Solaris, using the Sun Studio 11 C compiler, 213 the typical compile and link command lines might look something like: 214 <br> 215 For 32bit SPARC: 216 <br> 217 <code><ul> 218 cc -xO2 -mt -xregs=no%appl -xmemalign=4s -xarch=v8 -KPIC -c <i>*.c</i> 219 <br> 220 cc -mt -xarch=v8 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc 221 </code></ul> 222 <br> 223 For 64bit SPARC: 224 <br> 225 <code><ul> 226 cc -xO2 -mt -xregs=no%appl -xarch=v9 -KPIC -c <i>*.c</i> 227 <br> 228 cc -mt -xarch=v9 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc 229 </code></ul> 230 <br> 231 For X86: 232 <br> 233 <code><ul> 234 cc -xO2 -mt -xregs=no%frameptr -KPIC -c <i>*.c</i> 235 <br> 236 cc -mt -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc 237 </code></ul> 238 <br> 239 For AMD64: 240 <br> 241 <code><ul> 242 cc -xO2 -mt -xregs=no%frameptr -xarch=amd64 -KPIC -c <i>*.c</i> 243 <br> 244 cc -mt -xarch=amd64 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc 245 </code></ul> 246 <br> 247 </li> 248 249 <li> 250 Architecture/File Format: 251 For SPARC 32bit use <code>-xarch=v8</code>, 252 for SPARC 64bit use <code>-xarch=v9</code>, 253 for X86 (32-bit) 254 <i> 255 leave the option off or use <code>-xarch=generic</code> 256 </i>, 257 and for AMD64 (64bit) use <code>-xarch=amd64</code> 258 with both C and C++. 259 <br> 260 This is to be specific as to the architecture and the file format 261 of the .o files (and ultimately of the .so). 262 </li> 263 264 <li> 265 MT-Safe, Position Independent: Use <code>-KPIC -mt</code> 266 with both C and C++. 267 </li> 268 269 <li> 270 Register usage: For SPARC (both 32bit and 64bit) use 271 <code>-xregs=no%appl</code> and for X86 and AMD64 use <code>-xregs=no%frameptr</code> 272 with both C and C++. 273 </li> 274 275 <li> 276 Alignment: For SPARC 32bit use -xmemalign=4s and for SPARC 64bit do NOT use <code>-xmemalign=4</code> 277 with both C and C++. 278 </li> 279 280 <li> 281 Dependencies: Use <code>ldd -r <i>LibraryName</i></code>. 282 <br> 283 After the shared library has been built, the utility 284 <code>ldd</code> can be used to verify that all dependent libraries 285 have been satisfied, and all externs can be found. 286 If <code>ldd</code> says anything is missing, it is very likely that the JVM will also 287 be unable to load this library. 288 This usually means that you missed some <code>-l<i>name</i></code> 289 options when building the library, or perhaps forgot a <code>-R path</code> 290 option that tells the library where to look for libraries at runtime. 291 </li> 292 293 <h3> Linux </h3> 294 295 <li> 296 On Linux, using the gcc version 3.2, 297 the typical compile and link command lines might look something like: 298 <br> 299 For X86: 300 <br> 301 <code><ul> 302 gcc -O2 -fPIC -pthread -DLINUX -c <i>*.c</i> 303 <br> 304 gcc -z defs -static-libgcc -shared -mimpure-text -o <i>libXXX.so *.o</i> -lc 305 </code></ul> 306 <br> 307 For AMD64: 308 <br> 309 <code><ul> 310 gcc -O2 -fPIC -pthread -DLINUX -D_LP64=1 -c <i>*.c</i> 311 <br> 312 gcc -z defs -static-libgcc -shared -mimpure-text -o <i>libXXX.so *.o</i> -lc 313 </code></ul> 314 <br> 315 </li> 316 317 <li> 318 MT-Safe, Position Independent: 319 Use <code>-fPIC -pthread</code>. 320 </li> 321 322 <li> 323 Agent Demo Code: Needs -DLINUX 324 </li> 325 326 <li> 327 Register Usage: Use <code>-fno-omit-frame-pointer</code>. 328 <br> 329 It is important that these libraries have frame pointer register usage, see the above comments on the Solaris 330 <code>-xregs=no%frameptr</code> 331 option. 332 </li> 333 334 <li> 335 Library: Use -static-libgcc -mimpure-text. 336 <br> 337 When building the shared library (-shared option), this option 338 allows for maximum portability of the library between different 339 flavors of Linux. 340 The problem we have seen with Linux is that we cannot depend 341 on a compatible shared gcc library existing on all the versions of 342 Linux we can run on. 343 By doing this static link, the version script becomes more 344 important, making sure you don't expose any extern symbols 345 you didn't intend to. 346 </li> 347 348 <li> 349 Dependencies: Use <code>ldd -r <i>LibraryName</i></code>. 350 <br> 351 Provides the same checking as Solaris (see above). 352 </li> 353 354 <h3> Windows </h3> 355 356 <li> 357 On Windows and using the Microsoft C++ Compiler Visual Studio .NET 2003, 358 the typical compile and link command lines might look something like: 359 <br> 360 For X86: 361 <br> 362 <code><ul> 363 cl /O1 /MD /D _STATIC_CPPLIB /c <i>*.c</i> 364 <br> 365 link /dll /opt:REF /out:<i>XXX.dll *.obj</i> 366 </code></ul> 367 <br> 368 For AMD64: 369 <br> 370 <code><ul> 371 cl /O1 /MD /D _STATIC_CPPLIB /c <i>*.c</i> 372 <br> 373 link /dll /opt:REF /out:<i>XXX.dll *.obj</i> 374 </code></ul> 375 <br> 376 </li> 377 378 <li> 379 Library: Use <code>/opt:REF </code> when building the dll. 380 </li> 381 382 <li> 383 MS DLL Runtime: Use the <code>/MD /D _STATIC_CPPLIB</code> option. 384 <br> 385 This causes your dll to become dependent on MSVCRT.DLL and/or 386 the newer C++ runtime MSVCR71.DLL. 387 The option /D _STATIC_CPPLIB prevents you from becoming dependent on the 388 C++ library MSVCP71.DLL. 389 This is what we use in the JDK, but there are probably many combinations 390 that you could safely use, unfortunately there are many combinations 391 of runtimes that will not work. 392 Check the Microsoft site on proper use of runtimes. 393 </li> 394 395 <li> 396 Dependencies: Use VC++ <code>dumpbin /exports</code> and the VC++ "Dependency Walker". 397 <br> 398 Provides dependency information similar to <code>ldd</code>. 399 </li> 400 401 </ul> 402 403 404 <h2>For More Information</h2> 405 406 <p> 407 Remember, the complete source to all these agents is contained in the JDK 408 installations at demo/jvmti. 409 410 <p> 411 For more detailed information on JVM TI, refer to 412 <A HREF="http://java.sun.com/j2se/latest/docs/guide/jvmti"> 413 http://java.sun.com/j2se/latest/docs/guide/jvmti.</A> 414 415 <p> 416 More information on using JNI and building native libraries refer to: 417 <A HREF="http://java.sun.com/j2se/latest/docs/guide/jni"> 418 http://java.sun.com/j2se/latest/docs/guide/jni</A>. 419 420 <p> 421 Additional information can also be found by doing a search on "jvmti" at 422 <A HREF="http://java.sun.com/j2se">http://java.sun.com/j2se</A>. 423 Various technical articles are also available through this website. 424 And don't forget the 425 Java Tutorials at 426 <A HREF="http://java.sun.com/docs/books/tutorial">http://java.sun.com/docs/books/tutorial</A> 427 for getting a quick start on all the various interfaces. 428 429 <h2>Comments and Feedback</h2> 430 431 <p> 432 Comments regarding JVM TI or on any of these demonstrations should be 433 sent through 434 <A HREF="http://java.sun.com/mail">http://java.sun.com/mail/</A> 435 436 437 438 </html>