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 the 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 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. 79 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. 87 88 89 <h2> Demonstration Agents Available </h2> 90 91 <ul> 92 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> 100 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> 107 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> 114 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> 124 125 <li> 126 <A HREF="gctest">gctest</A> 127 <br> 128 This is a small agent that does garbage collection counting. 129 </li> 130 131 <li> 132 <A HREF="heapViewer">heapViewer</A> 133 <br> 134 This is a small agent that does some basic heap inspections. 135 </li> 136 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> 144 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> 151 152 </ul> 153 154 155 156 <h2>Agent Support</h2> 157 158 <ul> 159 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> 167 168 169 </ul> 170 171 172 173 <h2>Native Library Build Hints</h2> 174 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. 180 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. 190 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: 199 200 <ul> 201 202 <h3> Solaris </h3> 203 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> 241 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> 256 257 <li> 258 MT-Safe, Position Independent: Use <code>-KPIC -mt</code> 259 with both C and C++. 260 </li> 261 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> 267 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> 272 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> 285 286 <h3> Linux </h3> 287 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> 309 310 <li> 311 MT-Safe, Position Independent: 312 Use <code>-fPIC -pthread</code>. 313 </li> 314 315 <li> 316 Agent Demo Code: Needs -DLINUX 317 </li> 318 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> 326 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> 340 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> 346 347 <h3> Windows </h3> 348 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> 370 371 <li> 372 Library: Use <code>/opt:REF </code> when building the dll. 373 </li> 374 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> 386 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> 392 393 </ul> 394 395 396 <h2>For More Information</h2> 397 398 <p> 399 Remember, the complete source to all these agents is contained in the JDK 400 installations at demo/jvmti. 401 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> 406 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>. 411 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. 420 421 <h2>Comments and Feedback</h2> 422 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> 427 428 429 430 </html>