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