Mercurial > hg > graal-compiler
comparison agent/make/index.html @ 0:a61af66fc99e jdk7-b24
Initial load
author | duke |
---|---|
date | Sat, 01 Dec 2007 00:00:00 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:a61af66fc99e |
---|---|
1 <HTML> | |
2 | |
3 | |
4 <HEAD> | |
5 <TITLE> | |
6 Using The HotSpot Serviceability Agent | |
7 </TITLE> | |
8 </HEAD> | |
9 | |
10 <BODY TEXT="#000000" BGCOLOR="#FFFFFF"> | |
11 <H1> | |
12 Using The HotSpot Serviceability Agent | |
13 </H1> | |
14 | |
15 <P> | |
16 <H2> | |
17 Contents | |
18 </H2> | |
19 </P> | |
20 | |
21 <UL> | |
22 <LI> <A HREF = "#INTRODUCTION">Introduction</A> | |
23 <LI> <A HREF = "#SOURCES">Organization of the sources</A> | |
24 <LI> <A HREF = "#RUNNING">Running HSDB</A> | |
25 <LI> <A HREF = "#NOTES">Notes</A> | |
26 </UL> | |
27 | |
28 <H2> | |
29 <A NAME="INTRODUCTION"> | |
30 Introduction | |
31 </A> | |
32 </H2> | |
33 | |
34 <P> | |
35 The HotSpot Serviceability Agent (SA) is a set of Java APIs which | |
36 mirror the internal APIs of the HotSpot VM and which can be used to | |
37 examine the state of a HotSpot VM. | |
38 </P> | |
39 | |
40 <P> | |
41 The system understands the layout of certain VM data structures and is | |
42 able to traverse these structures in an examination-only fashion; that | |
43 is, it does not rely on being able to run code in the target VM. For | |
44 this reason it transparently works with either a running VM or a core | |
45 file. | |
46 </P> | |
47 | |
48 <P> | |
49 The system can reconstruct information about Java frames on the stack | |
50 and objects in the heap. Many of the important data structures in the | |
51 VM like the CodeCache, Universe, StubQueue, Frames, and VFrames have | |
52 been exposed and have relatively complete (or at least useful) | |
53 implementations. | |
54 </P> | |
55 | |
56 <P> | |
57 A small graphical debugger called HSDB (the "HotSpot Debugger") has | |
58 been written using these APIs. It provides stack memory dumps | |
59 annotated with method invocations, compiled-code inlining (if | |
60 present), interpreted vs. compiled code, interpreter codelets (if | |
61 interpreted), and live oops from oop-map information. It also provides | |
62 a tree-based oop inspector. More information will be added as | |
63 necessary; please <A HREF = "mailto:kenneth.russell@eng">send | |
64 email</A> with suggestions on what would be useful. | |
65 </P> | |
66 | |
67 <P> | |
68 The SA currently only works on Solaris. It uses dbx to connect to the | |
69 remote process or core file and communicates with a small piece of | |
70 code (an "import module") loaded into the debugger. | |
71 </P> | |
72 | |
73 <H2> | |
74 <A NAME="SOURCES"> | |
75 Organization of the sources | |
76 </A> | |
77 </H2> | |
78 | |
79 <P> | |
80 The Java-side source code, which is the bulk of the SA, is in | |
81 src/share/vm/agent. The organization of the sun.jvm.hotspot package | |
82 hierarchy mirrors the organization in the VM. This should allow | |
83 engineers familiar with the HotSpot sources to quickly understand how | |
84 the SA works and to make modifications if necessary. To build these | |
85 sources, cd to src/share/vm/agent and type "make". | |
86 </P> | |
87 | |
88 <P> | |
89 | |
90 The SA on Solaris works by communicating with a small piece of code | |
91 (an "import module") loaded into dbx. The source code for this import | |
92 module is in src/os/solaris/agent. To build this library, cd to | |
93 src/os/solaris/agent and type "make 32bit" or "make 64bit". The | |
94 distinction is necessary because the SPARC version of dbx ships with | |
95 two versions of its executable, and depending on which architecture | |
96 (v8 or v9) the debugger is running on selects the appropriate | |
97 executable. The SA tries the v8 version first, but if you are running | |
98 on a v9 machine you must provide both versions to the SA. | |
99 </P> | |
100 | |
101 <P> | |
102 | |
103 The system is currently hardwired to look on jano for its dbx | |
104 executable and import module. The relevant directory structure looks | |
105 like this: | |
106 | |
107 <UL> | |
108 <LI> .../hotspot/sa/ | |
109 <UL> | |
110 <LI> solaris/ | |
111 <UL> | |
112 <LI> sparc/ | |
113 <UL> | |
114 <LI> bin/ | |
115 <UL> | |
116 <LI> dbx: symlink to (v8) dbx 7.0 executable | |
117 </UL> | |
118 </UL> | |
119 <UL> | |
120 <LI> lib/ | |
121 <UL> | |
122 <LI> libsvc_agent_dbx.so: 32-bit version of import module | |
123 </UL> | |
124 </UL> | |
125 <LI> sparcv9/ | |
126 <UL> | |
127 <LI> lib/ | |
128 <UL> | |
129 <LI> libsvc_agent_dbx.so: 32-bit version of import module | |
130 </UL> | |
131 </UL> | |
132 </UL> | |
133 </UL> | |
134 </UL> | |
135 </P> | |
136 | |
137 <P> | |
138 The code which builds up path names to these executables is contained | |
139 in sun.jvm.hotspot.HotSpotAgent.java. There are hardcoded paths in | |
140 this file to jano, but the rest of the system is isolated from this. | |
141 </P> | |
142 | |
143 <P> | |
144 (It would be nice to have a panel in the debugger allowing | |
145 configuration of all of the known operating systems' options; right | |
146 now Solaris is the only supported OS, making that easier.) | |
147 </P> | |
148 | |
149 <H2> | |
150 <A NAME="RUNNING"> | |
151 Running HSDB | |
152 </A> | |
153 </H2> | |
154 | |
155 <P> | |
156 An installation of HSDB has been placed on jano. To access it, add the | |
157 following directory to your PATH: | |
158 </P> | |
159 | |
160 <P> | |
161 <PRE> | |
162 /net/jano/export/disk05/hotspot/sa/bin/common | |
163 </PRE> | |
164 </P> | |
165 | |
166 <P> | |
167 To start the debugger, type "hsdb". | |
168 </P> | |
169 | |
170 <P> | |
171 Alternatively, you can start a local build of the debugger by building | |
172 the sources in src/share/vm/agent, cd'ing to that directory, and | |
173 typing "java sun.jvm.hotspot.HSDB". | |
174 </P> | |
175 | |
176 <P> | |
177 There are three modes for the debugger: attaching to a local process, | |
178 opening a core file, and attaching to a remote "debug server". The | |
179 remote case requires two programs to be running on the remote machine: | |
180 the rmiregistry (see the script "start-rmiregistry" in this directory; | |
181 run this in the background) and the debug server (see the script | |
182 "start-debug-server"), in that order. start-rmiregistry takes no | |
183 arguments; start-debug-server takes as argument the process ID or the | |
184 executable and core file names to allow remote debugging of. Make sure | |
185 you do NOT have a CLASSPATH environment variable set when you run | |
186 these scripts. (The classes put into the rmiregistry are in sun.*, and | |
187 there are permissions problems if they aren't placed on the boot | |
188 classpath.) | |
189 </P> | |
190 | |
191 <P> | |
192 NOTE that the SA currently only works against VMs on Solaris/SPARC. | |
193 Remote debugging of Solaris/SPARC VMs on arbitrary platforms is | |
194 possible using the debug server; select "Connect to debug server..." | |
195 in HSDB. | |
196 </P> | |
197 | |
198 <P> | |
199 Once the debugger has been launched, the threads list is displayed. | |
200 The current set of functionality allows: | |
201 </P> | |
202 | |
203 <UL> | |
204 <LI> Browsing of the annotated stack memory ("Stack Memory" button). It | |
205 is currently annotated with the following information: | |
206 <UL> | |
207 <LI> Method names of the Java frames and their extents (supporting | |
208 inlined compiled methods) | |
209 <LI> Locations and types of oops, found using the oop map information | |
210 from compiled methods (interpreter oop maps coming soon) | |
211 <LI> If a Java frame was interrupted by a signal (e.g., because of a | |
212 crash), annotates the frame with the signal name and number | |
213 <LI> Interpreter codelet descriptions for interpreted frames | |
214 </UL> | |
215 <LI> Finding which thread or threads caused a crash (currently | |
216 identified by the presence of a signal handler frame) | |
217 <LI> Browsing of oops using the Oop Inspector. | |
218 <LI> Browsing of the java.lang.Thread object's oop. | |
219 <LI> Object histogram and inspection of objects therein. | |
220 </UL> | |
221 </P> | |
222 | |
223 <P> | |
224 More functionality is planned. Please <A HREF = | |
225 "mailto:kenneth.russell@eng">send email</A> with suggestions on what | |
226 would be useful, with any questions or comments, or if the debugger | |
227 crashes. | |
228 </P> | |
229 | |
230 <H2> | |
231 <A NAME="NOTES"> | |
232 Notes | |
233 </A> | |
234 </H2> | |
235 | |
236 <P> | |
237 HSDB does not suspend the system at a safepoint, but at an arbitrary | |
238 point. This means that many of the invariants in the VM's code are not | |
239 followed. | |
240 </P> | |
241 | |
242 <P> | |
243 As it happens, most of the places where the code ported over from the | |
244 VM has failed involve the topmost frame on the stack. Some | |
245 modifications have been made to allow the system to recognize | |
246 problematic situations. | |
247 </P> | |
248 | |
249 <P> | |
250 Certainly, not all of the failure modes of the debugger have been | |
251 found. Please <A HREF = "mailto:kenneth.russell@eng">send email</A> if | |
252 HSDB throws an exception. The best debugging aid in these situations | |
253 is a core file since it is a static view of the VM to which we can | |
254 then adapt the debugger code, as opposed to having to try to suspend | |
255 the VM over and over to reproduce the failure. gcore (1) is a useful | |
256 tool. (NOTE: do not try gcore with any application using the DGA X | |
257 server extension (example: Java2Demo); the kernel will panic. See bug | |
258 4343237.) | |
259 </P> | |
260 | |
261 </BODY> | |
262 </HTML> |