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™ 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>