--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/hotspot/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>