Mercurial > hg > truffle
diff agent/make/index.html @ 0:a61af66fc99e jdk7-b24
Initial load
| author | duke |
|---|---|
| date | Sat, 01 Dec 2007 00:00:00 +0000 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/agent/make/index.html Sat Dec 01 00:00:00 2007 +0000 @@ -0,0 +1,262 @@ +<HTML> + + +<HEAD> +<TITLE> +Using The HotSpot Serviceability Agent +</TITLE> +</HEAD> + +<BODY TEXT="#000000" BGCOLOR="#FFFFFF"> +<H1> +Using The HotSpot Serviceability Agent +</H1> + +<P> +<H2> +Contents +</H2> +</P> + +<UL> +<LI> <A HREF = "#INTRODUCTION">Introduction</A> +<LI> <A HREF = "#SOURCES">Organization of the sources</A> +<LI> <A HREF = "#RUNNING">Running HSDB</A> +<LI> <A HREF = "#NOTES">Notes</A> +</UL> + +<H2> +<A NAME="INTRODUCTION"> +Introduction +</A> +</H2> + +<P> +The HotSpot Serviceability Agent (SA) is a set of Java APIs which +mirror the internal APIs of the HotSpot VM and which can be used to +examine the state of a HotSpot VM. +</P> + +<P> +The system understands the layout of certain VM data structures and is +able to traverse these structures in an examination-only fashion; that +is, it does not rely on being able to run code in the target VM. For +this reason it transparently works with either a running VM or a core +file. +</P> + +<P> +The system can reconstruct information about Java frames on the stack +and objects in the heap. Many of the important data structures in the +VM like the CodeCache, Universe, StubQueue, Frames, and VFrames have +been exposed and have relatively complete (or at least useful) +implementations. +</P> + +<P> +A small graphical debugger called HSDB (the "HotSpot Debugger") has +been written using these APIs. It provides stack memory dumps +annotated with method invocations, compiled-code inlining (if +present), interpreted vs. compiled code, interpreter codelets (if +interpreted), and live oops from oop-map information. It also provides +a tree-based oop inspector. More information will be added as +necessary; please <A HREF = "mailto:kenneth.russell@eng">send +email</A> with suggestions on what would be useful. +</P> + +<P> +The SA currently only works on Solaris. It uses dbx to connect to the +remote process or core file and communicates with a small piece of +code (an "import module") loaded into the debugger. +</P> + +<H2> +<A NAME="SOURCES"> +Organization of the sources +</A> +</H2> + +<P> +The Java-side source code, which is the bulk of the SA, is in +src/share/vm/agent. The organization of the sun.jvm.hotspot package +hierarchy mirrors the organization in the VM. This should allow +engineers familiar with the HotSpot sources to quickly understand how +the SA works and to make modifications if necessary. To build these +sources, cd to src/share/vm/agent and type "make". +</P> + +<P> + +The SA on Solaris works by communicating with a small piece of code +(an "import module") loaded into dbx. The source code for this import +module is in src/os/solaris/agent. To build this library, cd to +src/os/solaris/agent and type "make 32bit" or "make 64bit". The +distinction is necessary because the SPARC version of dbx ships with +two versions of its executable, and depending on which architecture +(v8 or v9) the debugger is running on selects the appropriate +executable. The SA tries the v8 version first, but if you are running +on a v9 machine you must provide both versions to the SA. +</P> + +<P> + +The system is currently hardwired to look on jano for its dbx +executable and import module. The relevant directory structure looks +like this: + +<UL> + <LI> .../hotspot/sa/ + <UL> + <LI> solaris/ + <UL> + <LI> sparc/ + <UL> + <LI> bin/ + <UL> + <LI> dbx: symlink to (v8) dbx 7.0 executable + </UL> + </UL> + <UL> + <LI> lib/ + <UL> + <LI> libsvc_agent_dbx.so: 32-bit version of import module + </UL> + </UL> + <LI> sparcv9/ + <UL> + <LI> lib/ + <UL> + <LI> libsvc_agent_dbx.so: 32-bit version of import module + </UL> + </UL> + </UL> + </UL> +</UL> +</P> + +<P> +The code which builds up path names to these executables is contained +in sun.jvm.hotspot.HotSpotAgent.java. There are hardcoded paths in +this file to jano, but the rest of the system is isolated from this. +</P> + +<P> +(It would be nice to have a panel in the debugger allowing +configuration of all of the known operating systems' options; right +now Solaris is the only supported OS, making that easier.) +</P> + +<H2> +<A NAME="RUNNING"> +Running HSDB +</A> +</H2> + +<P> +An installation of HSDB has been placed on jano. To access it, add the +following directory to your PATH: +</P> + +<P> +<PRE> + /net/jano/export/disk05/hotspot/sa/bin/common +</PRE> +</P> + +<P> +To start the debugger, type "hsdb". +</P> + +<P> +Alternatively, you can start a local build of the debugger by building +the sources in src/share/vm/agent, cd'ing to that directory, and +typing "java sun.jvm.hotspot.HSDB". +</P> + +<P> +There are three modes for the debugger: attaching to a local process, +opening a core file, and attaching to a remote "debug server". The +remote case requires two programs to be running on the remote machine: +the rmiregistry (see the script "start-rmiregistry" in this directory; +run this in the background) and the debug server (see the script +"start-debug-server"), in that order. start-rmiregistry takes no +arguments; start-debug-server takes as argument the process ID or the +executable and core file names to allow remote debugging of. Make sure +you do NOT have a CLASSPATH environment variable set when you run +these scripts. (The classes put into the rmiregistry are in sun.*, and +there are permissions problems if they aren't placed on the boot +classpath.) +</P> + +<P> +NOTE that the SA currently only works against VMs on Solaris/SPARC. +Remote debugging of Solaris/SPARC VMs on arbitrary platforms is +possible using the debug server; select "Connect to debug server..." +in HSDB. +</P> + +<P> +Once the debugger has been launched, the threads list is displayed. +The current set of functionality allows: +</P> + +<UL> +<LI> Browsing of the annotated stack memory ("Stack Memory" button). It + is currently annotated with the following information: + <UL> + <LI> Method names of the Java frames and their extents (supporting + inlined compiled methods) + <LI> Locations and types of oops, found using the oop map information + from compiled methods (interpreter oop maps coming soon) + <LI> If a Java frame was interrupted by a signal (e.g., because of a + crash), annotates the frame with the signal name and number + <LI> Interpreter codelet descriptions for interpreted frames + </UL> +<LI> Finding which thread or threads caused a crash (currently + identified by the presence of a signal handler frame) +<LI> Browsing of oops using the Oop Inspector. +<LI> Browsing of the java.lang.Thread object's oop. +<LI> Object histogram and inspection of objects therein. +</UL> +</P> + +<P> +More functionality is planned. Please <A HREF = +"mailto:kenneth.russell@eng">send email</A> with suggestions on what +would be useful, with any questions or comments, or if the debugger +crashes. +</P> + +<H2> +<A NAME="NOTES"> +Notes +</A> +</H2> + +<P> +HSDB does not suspend the system at a safepoint, but at an arbitrary +point. This means that many of the invariants in the VM's code are not +followed. +</P> + +<P> +As it happens, most of the places where the code ported over from the +VM has failed involve the topmost frame on the stack. Some +modifications have been made to allow the system to recognize +problematic situations. +</P> + +<P> +Certainly, not all of the failure modes of the debugger have been +found. Please <A HREF = "mailto:kenneth.russell@eng">send email</A> if +HSDB throws an exception. The best debugging aid in these situations +is a core file since it is a static view of the VM to which we can +then adapt the debugger code, as opposed to having to try to suspend +the VM over and over to reproduce the failure. gcore (1) is a useful +tool. (NOTE: do not try gcore with any application using the DGA X +server extension (example: Java2Demo); the kernel will panic. See bug +4343237.) +</P> + +</BODY> +</HTML>