1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/agent/make/index.html Wed Apr 27 01:25:04 2016 +0800
1.3 @@ -0,0 +1,262 @@
1.4 +<HTML>
1.5 +
1.6 +
1.7 +<HEAD>
1.8 +<TITLE>
1.9 +Using The HotSpot Serviceability Agent
1.10 +</TITLE>
1.11 +</HEAD>
1.12 +
1.13 +<BODY TEXT="#000000" BGCOLOR="#FFFFFF">
1.14 +<H1>
1.15 +Using The HotSpot Serviceability Agent
1.16 +</H1>
1.17 +
1.18 +<P>
1.19 +<H2>
1.20 +Contents
1.21 +</H2>
1.22 +</P>
1.23 +
1.24 +<UL>
1.25 +<LI> <A HREF = "#INTRODUCTION">Introduction</A>
1.26 +<LI> <A HREF = "#SOURCES">Organization of the sources</A>
1.27 +<LI> <A HREF = "#RUNNING">Running HSDB</A>
1.28 +<LI> <A HREF = "#NOTES">Notes</A>
1.29 +</UL>
1.30 +
1.31 +<H2>
1.32 +<A NAME="INTRODUCTION">
1.33 +Introduction
1.34 +</A>
1.35 +</H2>
1.36 +
1.37 +<P>
1.38 +The HotSpot Serviceability Agent (SA) is a set of Java APIs which
1.39 +mirror the internal APIs of the HotSpot VM and which can be used to
1.40 +examine the state of a HotSpot VM.
1.41 +</P>
1.42 +
1.43 +<P>
1.44 +The system understands the layout of certain VM data structures and is
1.45 +able to traverse these structures in an examination-only fashion; that
1.46 +is, it does not rely on being able to run code in the target VM. For
1.47 +this reason it transparently works with either a running VM or a core
1.48 +file.
1.49 +</P>
1.50 +
1.51 +<P>
1.52 +The system can reconstruct information about Java frames on the stack
1.53 +and objects in the heap. Many of the important data structures in the
1.54 +VM like the CodeCache, Universe, StubQueue, Frames, and VFrames have
1.55 +been exposed and have relatively complete (or at least useful)
1.56 +implementations.
1.57 +</P>
1.58 +
1.59 +<P>
1.60 +A small graphical debugger called HSDB (the "HotSpot Debugger") has
1.61 +been written using these APIs. It provides stack memory dumps
1.62 +annotated with method invocations, compiled-code inlining (if
1.63 +present), interpreted vs. compiled code, interpreter codelets (if
1.64 +interpreted), and live oops from oop-map information. It also provides
1.65 +a tree-based oop inspector. More information will be added as
1.66 +necessary; please <A HREF = "mailto:kenneth.russell@eng">send
1.67 +email</A> with suggestions on what would be useful.
1.68 +</P>
1.69 +
1.70 +<P>
1.71 +The SA currently only works on Solaris. It uses dbx to connect to the
1.72 +remote process or core file and communicates with a small piece of
1.73 +code (an "import module") loaded into the debugger.
1.74 +</P>
1.75 +
1.76 +<H2>
1.77 +<A NAME="SOURCES">
1.78 +Organization of the sources
1.79 +</A>
1.80 +</H2>
1.81 +
1.82 +<P>
1.83 +The Java-side source code, which is the bulk of the SA, is in
1.84 +src/share/vm/agent. The organization of the sun.jvm.hotspot package
1.85 +hierarchy mirrors the organization in the VM. This should allow
1.86 +engineers familiar with the HotSpot sources to quickly understand how
1.87 +the SA works and to make modifications if necessary. To build these
1.88 +sources, cd to src/share/vm/agent and type "make".
1.89 +</P>
1.90 +
1.91 +<P>
1.92 +
1.93 +The SA on Solaris works by communicating with a small piece of code
1.94 +(an "import module") loaded into dbx. The source code for this import
1.95 +module is in src/os/solaris/agent. To build this library, cd to
1.96 +src/os/solaris/agent and type "make 32bit" or "make 64bit". The
1.97 +distinction is necessary because the SPARC version of dbx ships with
1.98 +two versions of its executable, and depending on which architecture
1.99 +(v8 or v9) the debugger is running on selects the appropriate
1.100 +executable. The SA tries the v8 version first, but if you are running
1.101 +on a v9 machine you must provide both versions to the SA.
1.102 +</P>
1.103 +
1.104 +<P>
1.105 +
1.106 +The system is currently hardwired to look on jano for its dbx
1.107 +executable and import module. The relevant directory structure looks
1.108 +like this:
1.109 +
1.110 +<UL>
1.111 + <LI> .../hotspot/sa/
1.112 + <UL>
1.113 + <LI> solaris/
1.114 + <UL>
1.115 + <LI> sparc/
1.116 + <UL>
1.117 + <LI> bin/
1.118 + <UL>
1.119 + <LI> dbx: symlink to (v8) dbx 7.0 executable
1.120 + </UL>
1.121 + </UL>
1.122 + <UL>
1.123 + <LI> lib/
1.124 + <UL>
1.125 + <LI> libsvc_agent_dbx.so: 32-bit version of import module
1.126 + </UL>
1.127 + </UL>
1.128 + <LI> sparcv9/
1.129 + <UL>
1.130 + <LI> lib/
1.131 + <UL>
1.132 + <LI> libsvc_agent_dbx.so: 32-bit version of import module
1.133 + </UL>
1.134 + </UL>
1.135 + </UL>
1.136 + </UL>
1.137 +</UL>
1.138 +</P>
1.139 +
1.140 +<P>
1.141 +The code which builds up path names to these executables is contained
1.142 +in sun.jvm.hotspot.HotSpotAgent.java. There are hardcoded paths in
1.143 +this file to jano, but the rest of the system is isolated from this.
1.144 +</P>
1.145 +
1.146 +<P>
1.147 +(It would be nice to have a panel in the debugger allowing
1.148 +configuration of all of the known operating systems' options; right
1.149 +now Solaris is the only supported OS, making that easier.)
1.150 +</P>
1.151 +
1.152 +<H2>
1.153 +<A NAME="RUNNING">
1.154 +Running HSDB
1.155 +</A>
1.156 +</H2>
1.157 +
1.158 +<P>
1.159 +An installation of HSDB has been placed on jano. To access it, add the
1.160 +following directory to your PATH:
1.161 +</P>
1.162 +
1.163 +<P>
1.164 +<PRE>
1.165 + /net/jano/export/disk05/hotspot/sa/bin/common
1.166 +</PRE>
1.167 +</P>
1.168 +
1.169 +<P>
1.170 +To start the debugger, type "hsdb".
1.171 +</P>
1.172 +
1.173 +<P>
1.174 +Alternatively, you can start a local build of the debugger by building
1.175 +the sources in src/share/vm/agent, cd'ing to that directory, and
1.176 +typing "java sun.jvm.hotspot.HSDB".
1.177 +</P>
1.178 +
1.179 +<P>
1.180 +There are three modes for the debugger: attaching to a local process,
1.181 +opening a core file, and attaching to a remote "debug server". The
1.182 +remote case requires two programs to be running on the remote machine:
1.183 +the rmiregistry (see the script "start-rmiregistry" in this directory;
1.184 +run this in the background) and the debug server (see the script
1.185 +"start-debug-server"), in that order. start-rmiregistry takes no
1.186 +arguments; start-debug-server takes as argument the process ID or the
1.187 +executable and core file names to allow remote debugging of. Make sure
1.188 +you do NOT have a CLASSPATH environment variable set when you run
1.189 +these scripts. (The classes put into the rmiregistry are in sun.*, and
1.190 +there are permissions problems if they aren't placed on the boot
1.191 +classpath.)
1.192 +</P>
1.193 +
1.194 +<P>
1.195 +NOTE that the SA currently only works against VMs on Solaris/SPARC.
1.196 +Remote debugging of Solaris/SPARC VMs on arbitrary platforms is
1.197 +possible using the debug server; select "Connect to debug server..."
1.198 +in HSDB.
1.199 +</P>
1.200 +
1.201 +<P>
1.202 +Once the debugger has been launched, the threads list is displayed.
1.203 +The current set of functionality allows:
1.204 +</P>
1.205 +
1.206 +<UL>
1.207 +<LI> Browsing of the annotated stack memory ("Stack Memory" button). It
1.208 + is currently annotated with the following information:
1.209 + <UL>
1.210 + <LI> Method names of the Java frames and their extents (supporting
1.211 + inlined compiled methods)
1.212 + <LI> Locations and types of oops, found using the oop map information
1.213 + from compiled methods (interpreter oop maps coming soon)
1.214 + <LI> If a Java frame was interrupted by a signal (e.g., because of a
1.215 + crash), annotates the frame with the signal name and number
1.216 + <LI> Interpreter codelet descriptions for interpreted frames
1.217 + </UL>
1.218 +<LI> Finding which thread or threads caused a crash (currently
1.219 + identified by the presence of a signal handler frame)
1.220 +<LI> Browsing of oops using the Oop Inspector.
1.221 +<LI> Browsing of the java.lang.Thread object's oop.
1.222 +<LI> Object histogram and inspection of objects therein.
1.223 +</UL>
1.224 +</P>
1.225 +
1.226 +<P>
1.227 +More functionality is planned. Please <A HREF =
1.228 +"mailto:kenneth.russell@eng">send email</A> with suggestions on what
1.229 +would be useful, with any questions or comments, or if the debugger
1.230 +crashes.
1.231 +</P>
1.232 +
1.233 +<H2>
1.234 +<A NAME="NOTES">
1.235 +Notes
1.236 +</A>
1.237 +</H2>
1.238 +
1.239 +<P>
1.240 +HSDB does not suspend the system at a safepoint, but at an arbitrary
1.241 +point. This means that many of the invariants in the VM's code are not
1.242 +followed.
1.243 +</P>
1.244 +
1.245 +<P>
1.246 +As it happens, most of the places where the code ported over from the
1.247 +VM has failed involve the topmost frame on the stack. Some
1.248 +modifications have been made to allow the system to recognize
1.249 +problematic situations.
1.250 +</P>
1.251 +
1.252 +<P>
1.253 +Certainly, not all of the failure modes of the debugger have been
1.254 +found. Please <A HREF = "mailto:kenneth.russell@eng">send email</A> if
1.255 +HSDB throws an exception. The best debugging aid in these situations
1.256 +is a core file since it is a static view of the VM to which we can
1.257 +then adapt the debugger code, as opposed to having to try to suspend
1.258 +the VM over and over to reproduce the failure. gcore (1) is a useful
1.259 +tool. (NOTE: do not try gcore with any application using the DGA X
1.260 +server extension (example: Java2Demo); the kernel will panic. See bug
1.261 +4343237.)
1.262 +</P>
1.263 +
1.264 +</BODY>
1.265 +</HTML>
