Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / libcore / 319a3b994703aac84df7bcde272adfcb3cdbbbf0 / . / jdk / src / share / demo / jvmti / index.html
blob: 87da6cc1171b25b1fecd49e1dc2c528cf40e2433 [file] [log] [blame]
J. Duke319a3b92007-12-01 00:00:00 +0000[diff] [blame^]1<html>
2<head> <title>JVM TI Demonstration Code</title> </head>
3
4<h1>JVM TI Demonstration Code</h1>
5
6<p>
7The
8Java<sup><font size=-2>TM</font></sup> Virtual Machine Tools Interface (JVM TI)
9is a native tool interface provided in JDK 5.0 and newer.
10Native libraries that use JVM TI and are loaded into the
11Java Virtual Machine
12via the -agentlib, -agentpath, or -Xrun (deprecated) interfaces, are
13called Agents.
14<p>
15<A HREF="http://java.sun.com/j2se/latest/docs/guide/jvmti">JVM TI</A>
16was designed to work with the
17Java Native Interface
18(<A HREF="http://java.sun.com/j2se/latest/docs/guide/jni">JNI</A>),
19and eventually displace the
20Java Virtual Machine Debugging Interface
21(<A HREF="http://java.sun.com/j2se/1.5.0/docs/guide/jpda/jvmdi-spec.html">JVMDI</A>)
22and the
23Java 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>
27We have created a set of demonstration agents that should
28help show many of the features and abilities of the
29interface. This list of demonstration agents will change over time.
30They are provided as educational tools and as starting
31points for Java tool development.
32
33<p>
34These agents are built with every JDK build and some basic testing is performed
35on a regular basis, but no extensive testbases currently
36exist for these agents.
37Every JDK installation should include all the pre-built binaries and sources for
38all 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>
44Using these agents will require the VM to locate the shared library file
45before any actual Java code is run.
46The JDK installation should contain all the agent libraries in
47the ${JAVA_HOME}/demo/jvmti/<i>agent-name</i>/lib directories.
48The Solaris 64bit version would be contained in the sparcv9 or amd64
49subdirectory.
50If 'java' complains that it can't find the library,
51you may need to add the directory containing the library into the
52LD_LIBRARY_PATH environment variable (Unix), or the PATH environment
53variable (Windows).
54This is system and platform specific.
55If you are using 64bit Solaris (e.g. 'java -d64'),
56you should use LD_LIBRARY_PATH64.
57Some agents such as hprof (heap/cpu profiler) and jdwp (debugger backend)
58are located inside the primary JDK directories and will always be found
59in those locations.
60
61<p>
62The agents that instrument classfiles
63(i.e. BCI, usually through the java_crw_demo library)
64such as hprof, heapTracker, mtrace, and minst,
65also need to have the Java classes they use available in the bootclasspath.
66The one used by hprof is already in the bootclasspath, and the
67other agents will make attempts at automatically adding their jar file
68(e.g. heapTracker.jar, mtrace.jar, or minst.jar) to the bootclasspath
69with AddToBootstrapClassLoaderSearch from JVM TI at startup
70(see the agent_util code).
71This is done by locating this jar file at
72${JAVA_HOME}/demo/jvmti/<i>agent-name</i>
73where JAVA_HOME is obtained by calling GetSystemProperty from JVM TI
74with "java.home".
75We recognize that this is not ideal, but felt that as just demonstration
76code it was acceptable.
77Ideally the agent could find out the actual directory it came from and
78locate the jar file relative to that location.
79Our demonstration agents currently do not do this.
80
81<p>
82If you choose to modify or change these agents, the above information
83is important in making everything is found.
84It is recommended that you change the name of the agent when you
85modify it to avoid conflicts with the existing demo agents.
86Or better yet, go to http://jdk.dev.java.net and submit your
87changes 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>
97This is a extremely small agent that does nothing but check the
98version string supplied in the jvmti.h file, with the version
99number supplied by the VM at runtime.
100</li>
101
102<li>
103<A HREF="mtrace">mtrace</A>
104<br>
105This is a small agent that does method tracing.
106It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
107</li>
108
109<li>
110<A HREF="minst">minst</A>
111<br>
112This is an even smaller agent that does just method entry tracing.
113It also uses Bytecode Instrumentation (BCI) via the java_crw_demo library,
114but the instrumentation code is pure Java (no Java native methods used).
115NOTE: Be sure to check out java.lang.instrument for a way to avoid
116native code agents completely.
117</li>
118
119<li>
120<A HREF="gctest">gctest</A>
121<br>
122This is a small agent that does garbage collection counting.
123</li>
124
125<li>
126<A HREF="heapViewer">heapViewer</A>
127<br>
128This is a small agent that does some basic heap inspections.
129</li>
130
131<li>
132<A HREF="heapTracker">heapTracker</A>
133<br>
134This is a small agent that does BCI to capture object creation
135and track them.
136It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
137</li>
138
139<li>
140<A HREF="waiters">waiters</A>
141<br>
142This is a small agent that gets information about threads
143waiting on monitors.
144</li>
145
146<li>
147<A HREF="hprof">hprof</A>
148<br>
149This is a large agent that does heap and cpu profiling.
150This demo agent is actually built into the
151
152Java Runtime Environment (JRE).
153It 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
156should 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>
170This is a demo C library that does class file to class file
171transformations or BCI (Bytecode Instrumentation).
172It 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>
183All libraries loaded into java are assumed to be MT-safe (Multi-thread safe).
184This means that multiple threads could be executing the code at the same
185time, and static or global data may need to be placed in critical
186sections. See the Raw Monitor interfaces for more information.
187
188<p>
189All native libraries loaded into the
190Java Virtual Machine,
191including Agent libraries,
192need to be compiled and built in a compatible way.
193Certain native compilation options or optimizations should be avoided,
194and some are required.
195More information on this options is available in the man pages for
196the various compilers.
197
198<p>
199Some native compiler and linker options can create fatal or
200erroneous behavior when native agent libraries are operating
201inside the Java Virtual Machine.
202It would take too many words to describe all the possible issues with all
203the native compiler options, optimizations, and settings.
204Here are some recommendations on the basic compiler and linker options
205we recommend:
206
207<ul>
208
209<h3> Solaris </h3>
210
211<li>
212On Solaris, using the Sun Studio 11 C compiler,
213the typical compile and link command lines might look something like:
214<br>
215For 32bit SPARC:
216<br>
217<code><ul>
218cc -xO2 -mt -xregs=no%appl -xmemalign=4s -xarch=v8 -KPIC -c <i>*.c</i>
219<br>
220cc -mt -xarch=v8 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
221</code></ul>
222<br>
223For 64bit SPARC:
224<br>
225<code><ul>
226cc -xO2 -mt -xregs=no%appl -xarch=v9 -KPIC -c <i>*.c</i>
227<br>
228cc -mt -xarch=v9 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
229</code></ul>
230<br>
231For X86:
232<br>
233<code><ul>
234cc -xO2 -mt -xregs=no%frameptr -KPIC -c <i>*.c</i>
235<br>
236cc -mt -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
237</code></ul>
238<br>
239For AMD64:
240<br>
241<code><ul>
242cc -xO2 -mt -xregs=no%frameptr -xarch=amd64 -KPIC -c <i>*.c</i>
243<br>
244cc -mt -xarch=amd64 -z defs -ztext -G -o <i>libXXX.so *.o</i> -lc
245</code></ul>
246<br>
247</li>
248
249<li>
250Architecture/File Format:
251For SPARC 32bit use <code>-xarch=v8</code>,
252for SPARC 64bit use <code>-xarch=v9</code>,
253for X86 (32-bit)
254<i>
255leave the option off or use <code>-xarch=generic</code>
256</i>,
257and for AMD64 (64bit) use <code>-xarch=amd64</code>
258with both C and C++.
259<br>
260This is to be specific as to the architecture and the file format
261of the .o files (and ultimately of the .so).
262</li>
263
264<li>
265MT-Safe, Position Independent: Use <code>-KPIC -mt</code>
266with both C and C++.
267</li>
268
269<li>
270Register 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>
272with both C and C++.
273</li>
274
275<li>
276Alignment: For SPARC 32bit use -xmemalign=4s and for SPARC 64bit do NOT use <code>-xmemalign=4</code>
277with both C and C++.
278</li>
279
280<li>
281Dependencies: Use <code>ldd -r <i>LibraryName</i></code>.
282<br>
283After the shared library has been built, the utility
284<code>ldd</code> can be used to verify that all dependent libraries
285have been satisfied, and all externs can be found.
286If <code>ldd</code> says anything is missing, it is very likely that the JVM will also
287be unable to load this library.
288This usually means that you missed some <code>-l<i>name</i></code>
289options when building the library, or perhaps forgot a <code>-R path</code>
290option that tells the library where to look for libraries at runtime.
291</li>
292
293<h3> Linux </h3>
294
295<li>
296On Linux, using the gcc version 3.2,
297the typical compile and link command lines might look something like:
298<br>
299For X86:
300<br>
301<code><ul>
302gcc -O2 -fPIC -pthread -DLINUX -c <i>*.c</i>
303<br>
304gcc -z defs -static-libgcc -shared -mimpure-text -o <i>libXXX.so *.o</i> -lc
305</code></ul>
306<br>
307For AMD64:
308<br>
309<code><ul>
310gcc -O2 -fPIC -pthread -DLINUX -D_LP64=1 -c <i>*.c</i>
311<br>
312gcc -z defs -static-libgcc -shared -mimpure-text -o <i>libXXX.so *.o</i> -lc
313</code></ul>
314<br>
315</li>
316
317<li>
318MT-Safe, Position Independent:
319Use <code>-fPIC -pthread</code>.
320</li>
321
322<li>
323Agent Demo Code: Needs -DLINUX
324</li>
325
326<li>
327Register Usage: Use <code>-fno-omit-frame-pointer</code>.
328<br>
329It is important that these libraries have frame pointer register usage, see the above comments on the Solaris
330<code>-xregs=no%frameptr</code>
331option.
332</li>
333
334<li>
335Library: Use -static-libgcc -mimpure-text.
336<br>
337When building the shared library (-shared option), this option
338allows for maximum portability of the library between different
339flavors of Linux.
340The problem we have seen with Linux is that we cannot depend
341on a compatible shared gcc library existing on all the versions of
342Linux we can run on.
343By doing this static link, the version script becomes more
344important, making sure you don't expose any extern symbols
345you didn't intend to.
346</li>
347
348<li>
349Dependencies: Use <code>ldd -r <i>LibraryName</i></code>.
350<br>
351Provides the same checking as Solaris (see above).
352</li>
353
354<h3> Windows </h3>
355
356<li>
357On Windows and using the Microsoft C++ Compiler Visual Studio .NET 2003,
358the typical compile and link command lines might look something like:
359<br>
360For X86:
361<br>
362<code><ul>
363cl /O1 /MD /D _STATIC_CPPLIB /c <i>*.c</i>
364<br>
365link /dll /opt:REF /out:<i>XXX.dll *.obj</i>
366</code></ul>
367<br>
368For AMD64:
369<br>
370<code><ul>
371cl /O1 /MD /D _STATIC_CPPLIB /c <i>*.c</i>
372<br>
373link /dll /opt:REF /out:<i>XXX.dll *.obj</i>
374</code></ul>
375<br>
376</li>
377
378<li>
379Library: Use <code>/opt:REF </code> when building the dll.
380</li>
381
382<li>
383MS DLL Runtime: Use the <code>/MD /D _STATIC_CPPLIB</code> option.
384<br>
385This causes your dll to become dependent on MSVCRT.DLL and/or
386the newer C++ runtime MSVCR71.DLL.
387The option /D _STATIC_CPPLIB prevents you from becoming dependent on the
388C++ library MSVCP71.DLL.
389This is what we use in the JDK, but there are probably many combinations
390that you could safely use, unfortunately there are many combinations
391of runtimes that will not work.
392Check the Microsoft site on proper use of runtimes.
393</li>
394
395<li>
396Dependencies: Use VC++ <code>dumpbin /exports</code> and the VC++ "Dependency Walker".
397<br>
398Provides dependency information similar to <code>ldd</code>.
399</li>
400
401</ul>
402
403
404<h2>For More Information</h2>
405
406<p>
407Remember, the complete source to all these agents is contained in the JDK
408installations at demo/jvmti.
409
410<p>
411For more detailed information on JVM TI, refer to
412<A HREF="http://java.sun.com/j2se/latest/docs/guide/jvmti">
413http://java.sun.com/j2se/latest/docs/guide/jvmti.</A>
414
415<p>
416More information on using JNI and building native libraries refer to:
417<A HREF="http://java.sun.com/j2se/latest/docs/guide/jni">
418http://java.sun.com/j2se/latest/docs/guide/jni</A>.
419
420<p>
421Additional 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>.
423Various technical articles are also available through this website.
424And don't forget the
425Java Tutorials at
426<A HREF="http://java.sun.com/docs/books/tutorial">http://java.sun.com/docs/books/tutorial</A>
427for getting a quick start on all the various interfaces.
428
429<h2>Comments and Feedback</h2>
430
431<p>
432Comments regarding JVM TI or on any of these demonstrations should be
433sent through
434<A HREF="http://java.sun.com/mail">http://java.sun.com/mail/</A>
435
436
437
438</html>