| author | ohair |
| Fri, 14 Jan 2011 14:04:54 -0800 | |
| changeset 8018 | 79ce40b4ab5e |
| parent 4808 | 37f605425f74 |
| child 12056 | 1f93da3840f7 |
| permissions | -rw-r--r-- |
| 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> |
|
|
4808
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
103 |
<A HREF="compiledMethodLoad">compiledMethodLoad</A> |
|
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
104 |
<br> |
|
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
105 |
This is a small agent that traces CompiledMethodLoad events along |
|
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
106 |
with the HotSpot specific compile_info parameter. |
|
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
107 |
</li> |
|
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
108 |
|
|
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
109 |
<li> |
| 2 | 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 -mimpure-text -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 -mimpure-text -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 -mimpure-text. |
|
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> |
|
|
8018
79ce40b4ab5e
6950375: Remove msvcrt.dll from the Windows JRE bundles
ohair
parents:
4808
diff
changeset
|
392 |
This causes your dll to become dependent on just MSVCR*.DLL. |
| 2 | 393 |
The option /D _STATIC_CPPLIB prevents you from becoming dependent on the |
|
8018
79ce40b4ab5e
6950375: Remove msvcrt.dll from the Windows JRE bundles
ohair
parents:
4808
diff
changeset
|
394 |
C++ library MSVCP*.DLL. |
| 2 | 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> |