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