annotate agent/make/index.html @ 6031:6e4b0b4481b9

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