| author | serb |
| Fri, 29 Apr 2016 15:44:04 +0300 (2016-04-29) | |
| changeset 38388 | 84ab1f133f16 |
| parent 30678 | a8b7fd8ede97 |
| 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 |
|
| 30678 | 8 |
Java™ Virtual Machine Tools Interface (JVM TI) |
| 2 | 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. |
|
|
26201
40a873d21081
8043936: Drop HPROF as demo, keep as HPROF agent shipped with JDK
sla
parents:
25859
diff
changeset
|
57 |
Some agents such as the jdwp (debugger backend) |
| 2 | 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) |
|
|
26201
40a873d21081
8043936: Drop HPROF as demo, keep as HPROF agent shipped with JDK
sla
parents:
25859
diff
changeset
|
64 |
such as heapTracker, mtrace, and minst, |
| 2 | 65 |
also need to have the Java classes they use available in the bootclasspath. |
|
26201
40a873d21081
8043936: Drop HPROF as demo, keep as HPROF agent shipped with JDK
sla
parents:
25859
diff
changeset
|
66 |
The agents will make attempts at automatically adding their jar file |
| 2 | 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> |
|
|
4808
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
102 |
<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
|
103 |
<br> |
|
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
104 |
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
|
105 |
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
|
106 |
</li> |
|
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
107 |
|
|
37f605425f74
6580131: 3/4 CompiledMethodLoad events don't produce the expected extra notifications to describe inlining
dcubed
parents:
2
diff
changeset
|
108 |
<li> |
| 2 | 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> |
|
|
12056
1f93da3840f7
7150392: Linux build breaks with GCC 4.7 due to unrecognized option
andrew
parents:
8018
diff
changeset
|
297 |
gcc -z defs -static-libgcc -shared -o <i>libXXX.so *.o</i> -lc |
| 2 | 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> |
|
|
12056
1f93da3840f7
7150392: Linux build breaks with GCC 4.7 due to unrecognized option
andrew
parents:
8018
diff
changeset
|
305 |
gcc -z defs -static-libgcc -shared -o <i>libXXX.so *.o</i> -lc |
| 2 | 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> |
|
|
12056
1f93da3840f7
7150392: Linux build breaks with GCC 4.7 due to unrecognized option
andrew
parents:
8018
diff
changeset
|
328 |
Library: Use -static-libgcc. |
| 2 | 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> |
|
|
8018
79ce40b4ab5e
6950375: Remove msvcrt.dll from the Windows JRE bundles
ohair
parents:
4808
diff
changeset
|
378 |
This causes your dll to become dependent on just MSVCR*.DLL. |
| 2 | 379 |
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
|
380 |
C++ library MSVCP*.DLL. |
| 2 | 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 |
|
| 38388 | 418 |
<A HREF="http://docs.oracle.com/javase/tutorial">http://docs.oracle.com/javase/tutorial</A> |
| 2 | 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> |