Mercurial > hg > truffle

diff agent/doc/jsdb.html @ 0:a61af66fc99e jdk7-b24

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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/doc/jsdb.html	Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,1369 @@
+<html>
+<head>
+<title>
+JavaScript interface to Hotspot Serviceability Agent
+</title>
+</head>
+<body>
+<h1>JavaScript interface to Hotspot Serviceability Agent</h1>
+
+<p>
+Serviceability Agent (SA) provides Java API and tools to diagnose HotSpot Virtual Machine and 
+Java apps running on it. SA is a snapshot debugger -- can be used to observe state of a frozen java process or java core dump.
+</p>
+
+<h2>Existing SA APIs</h2>
+<p>
+There are two application programmer interfaces (APIs) for SA:
+<dl>
+<dt>1. Private java API
+</dt>
+<dd>
+This tries to mimic hotspot VM's internal C++ classes and methods. Because VM data structures
+are a moving target, this API can never be 'stable'! Besides, to use SA's private API knowledge of
+HotSpot code base is essential.
+</dd>
+<dt>2. SA-JDI -- Java Debugger Interface read-only subset API
+</dt>
+<dd>
+This is read-only subset of JDI (Java Debugger Interface)
+This is a standardized interface to get java level state of a java process or java core dump. While this
+interface is useful, this misses parts of java level state from target process or core such as
+<ul>
+<li>heap walking interface -- only objects traceable to static variables (of classes) and local
+variables of stack frames can be accessed.
+<li>re-constructing .class from debuggee are missing.
+<li>re-constructing object mirrors for Java objects of the debuggee.
+</ul>
+</dd>
+</dl>
+</p>
+
+<h2>SA Scripting interface</h2>
+
+<p>
+Traditionally, platform debuggers such as dbx, gdb and Solaris mdb (Module Debugger), provide a scripting
+language interface. Scripting language interface provides easy-to-use, dynamically typed
+interface to access data structures from debuggee. dbx and mdb even allow user to write
+C/C++ modules to extend the scripting language commands. 
+</p>
+
+<p>
+SA provides SOQL - Simple Object Query Language -- a SQL-like query language to access
+Java heap as an object database. SA's main GUI (HSDB) also exposes scripting interface of underlying debugger such as dbx, windbg. 
+But to use this interface, user has to learn scripting interface of multiple debugger back-ends such as dbx, windbg. 
+And these scripting interfaces are 'raw' in the sense that no java state is exposed -- only C/C++ state of VM is exposed.
+Higher level SA services are not available through scripting interface.
+</p>
+
+<p>
+<b>jsdb -- JavaScript Debugger</b> attempts to provide JavaScript interface to SA. 
+jsdb provides
+
+<ul>
+<li>high-level hotspot (and SA) independent scripting interface
+<li>low-level SA-aware scripting interface. 
+</ul>
+</p>
+
+<h2>High level interface (Java State)</h2>
+
+<b>jsdb</b> is a command line <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">JavaScript</a> shell based on 
+<a href="http://www.mozilla.org/rhino/">Mozilla's Rhino JavaScript Engine</a>. 
+This command line utility attaches to Java process or core file or remote debug server and waits for user input.
+This shell supports the following global functions and objects in addition to the standard JavaScript functions and 
+objects:
+
+<h3>jdsb globals</h3>
+
+<table border="1">
+<tr>
+<th>Function/Variable</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>
+address(jobject)
+</td>
+<td>
+function that returns the address of the Java object as a string
+</td>
+</tr>
+<td>
+classof(jobject)
+</td>
+<td>
+function that returns the JavaScript object that represents class object of the Java object
+</td>
+</tr>
+<td>
+dumpClass(jclass,[dir])
+</td>
+<td>
+function that writes .class for the given Java Class. Optionally (second arg) accepts the directory where the
+.class has to be written.
+</td>
+</tr>
+<td>
+help()
+</td>
+<td>
+function that prints help message for global functions and objects
+</td>
+</tr>
+<tr>
+<td>
+identityHash(jobject)
+</td>
+<td>
+function that returns the identity hashCode of the Java object
+</td>
+</tr>
+<tr>
+<td>
+mirror(jobject)
+</td>
+<td>
+function that returns a local mirror of the Java object.
+</td>
+</tr>
+<tr>
+<td>
+load([file1, file2,...])
+</td>
+<td>
+function that loads zero or more JavaScript file(s). With no arguments, reads <stdin> for
+JavaScript code.
+</td>
+</tr>
+<tr>
+<td>
+object(string) 
+</td>
+<td>
+function that converts a string address into Java object
+</td>
+</tr>
+<tr>
+<td>
+owner(jobject)
+</td>
+<td>
+function that returns the owner thread of this monitor or null
+</td>
+</tr>
+<tr>
+<td>
+sizeof(jobject)
+</td>
+<td>
+function that returns the size of Java object in bytes
+</td>
+</tr>
+<tr>
+<td>
+staticof(jclass, field)
+</td>
+<td>
+function that returns the value of given field of the given Java class
+</td>
+</tr>
+<tr>
+<td>
+print(expr1, expr2,...)  
+</td>
+<td>
+function that prints zero or more JavaScript expressions after converting those as strings
+</td>
+</tr>
+<tr>
+<td>
+println(expr1, expr2..)
+</td>
+<td>
+function that same as print, but prints a newline at the end
+</td>
+</tr>
+<tr>
+<td>
+read([prompt])
+</td>
+<td>
+function that reads a single line from standard input
+</td>
+</tr>
+<tr>
+<td>
+quit()
+</td>
+<td>
+function that quits the interactive load call as well as the shell
+</td>
+</tr>
+<tr>
+<td>
+jvm
+</td>
+<td>
+variable -- a JavaScript object that represents the target jvm that is being debugged
+</td>
+</tr>
+</table>
+
+<h3>jvm object</h3>
+
+<p>
+jvm object supports the following read-only properties.
+</p>
+
+<table border="1">
+<tr>
+<th>
+Property name
+</th>
+<th>
+Description
+</th>
+</tr>
+<tr>
+<td>
+threads
+</td>
+<td>
+array of Java threads from the debuggee
+</td>
+</tr>
+<tr>
+<td>
+heap
+</td>
+<td>
+object representing the heap of the debuggee
+</td>
+</tr>
+<tr>
+<td>
+type
+</td>
+<td>
+string value that is either "Server" or "Client" or "Core" -- the flavour of debuggee VM
+</td>
+</tr>
+<tr>
+<td>
+bootClassPath
+</td>
+<td>
+string value of bootclasspath of the debuggee
+</td>
+</tr>
+<tr>
+<td>
+cpu
+</td>
+<td>
+string value of cpu on which the debuggee runs/ran
+</td>
+</tr>
+<tr>
+<td>
+sysProps
+</td>
+<td>
+name-value pairs (JavaScript associative array) of Java System properties of the debuggee
+</td>
+</tr>
+<tr>
+<td>
+addressSize
+</td>
+<td>
+int value -- 32 for 32 bit debuggee, 64 for 64 bit debuggee
+</td>
+</tr>
+<tr>
+<td>
+os
+</td>
+<td>
+string value of OS on which the debuggee runs/ran
+</td>
+</tr>
+<tr>
+<td>
+buildInfo
+</td>
+<td>
+internal build info string from debuggee
+</td>
+</tr>
+<tr>
+<td>
+flags
+</td>
+<td>
+name-value pairs (JavaScript associative array) of JVM command line flags of the debuggee
+</td>
+</tr>
+<tr>
+<td>
+classPath
+</td>
+<td>
+string value of classpath of the debuggee
+</td>
+</tr>
+<tr>
+<td>
+userDir
+</td>
+<td>
+string value of user.dir System property of the debuggee
+</td>
+</tr>
+</table>
+
+<h3>heap object</h3>
+
+<p>
+heap object represents Java heap of the debuggee VM
+</p>
+<table border="1">
+<tr>
+<th>
+Function or property name
+</th>
+<th>
+Description
+</th>
+</tr>
+<tr>
+<td>
+capacity
+</td>
+<td>
+byte size of capacity of the heap
+</td>
+</tr>
+<tr>
+<td>
+used
+</td>
+<td>
+byte size of used portion (of live objects) of the heap
+</td>
+</tr>
+<tr>
+<td>
+forEachObject(func, [class], [include subtypes -- true|false])
+</td>
+<td>
+This function accepts a callback function 'func' and optionally class name and boolean arguments.
+This function calls the callback for each Java object in the debuggee's heap. The optional class
+argument may be used to receive objects of given class only. The third arguments specifies whether
+to include objects of subtype of given class [or interface] or not. The default value of class is "java.lang.Object"
+and and that of the third argument is true. i.e., by default all objects are included.
+</td>
+</tr>
+<tr>
+<td>
+forEachClass(func, [initiating loader -- true|false])
+</td>
+<td>
+This function accepts a callback function 'func'. This function iterates through the classes of the debuggee and calls the
+callback for each class. The second parameter tells whether to pass initiating loader to the iterator callback or not.
+</td>
+</tr>
+</table>
+
+<h3>Accessing Java objects and arrays in script</h3>
+
+<p>
+From a given Java object, we can access all fields of the Java object by usual '.' operator. i.e., if you got a Java object
+called 'o' of type java.lang.Thread from debuggee, you can access 'stackSize' field by o.stackSize syntax. Similarly, length of Java array
+objects can be accessed by length property. And array indexing follows usual syntax. i.e., n'th element of array 'a' is 
+accessed by a[n].
+</p>
+
+<h3>jvm.threads array</h3>
+
+<p>
+This is a JavaScript array of Java threads of the debuggee. As usual, 'length' property tells the number of threads and individual
+threads may be accessed by index operator -- i.e, jvm.threads[0] returns the first thread.
+</p>
+
+<h3>thread object</h3>
+
+
+<p>
+In addition to the fields of java.lang.Thread (or subclass) fields, thread objects have two additional properties.
+
+<ul>
+<li>frames -- array of stack frame objects
+<li>monitors -- array of monitor objects owned by the thread
+</ul>
+
+</p>
+
+<h3>stack frame object</h3>
+
+<table border="1">
+<tr>
+<th>
+Property name
+</th>
+<th>
+Description
+</th>
+</tr>
+<td>
+thisObject
+</td>
+<td>
+Object representing 'this' of the current frame [will be null for static methods]
+</td>
+</tr>
+<tr>
+<td>
+locals
+</td>
+<td>
+name-value pairs of local variables [JavaScript associative array]
+</td>
+</tr>
+<tr>
+<td>
+line
+</td>
+<td>
+Java source line number at which the frame is executing
+</td>
+</tr>
+<tr>
+<td>
+bci
+</td>
+<td>
+byte code index of the bytecode that the frame is executing
+</td>
+</tr>
+<tr>
+<td>
+thread
+</td>
+<td>
+thread to which this frame belongs
+</td>
+</tr>
+<tr>
+<td>
+method
+</td>
+<td>
+Java method that the frame is executing
+</td>
+</tr>
+</table>
+
+<h3>method object</h3>
+
+<p>
+method object represents a Java method of debuggee
+</p>
+
+<table border="1">
+<tr>
+<th>
+Property name
+</th>
+<th>
+Description
+</th>
+</tr>
+<tr>
+<td>
+isStatic
+</td>
+<td>
+boolean - true for static methods and false for non-static methods
+</td>
+</tr>
+
+<tr>
+<td>
+isSynchronized
+</td>
+<td>
+boolean - true for synchronized methods and false for non-synchronized methods
+</td>
+</tr>
+
+<tr>
+<td>
+isNative
+</td>
+<td>
+boolean - true for native methods and false for non-native methods
+</td>
+</tr>
+
+<tr>
+<td>
+isProtected
+</td>
+<td>
+boolean - true for protected methods and false for non-protected methods
+</td>
+</tr>
+
+<tr>
+<td>
+isPrivate
+</td>
+<td>
+boolean - true for private methods and false for non-private methods
+</td>
+</tr>
+
+<tr>
+<td>
+isSynthetic
+</td>
+<td>
+boolean - true for Javac generated synthetic methods and false for non-synthetic methods
+</td>
+</tr>
+
+<tr>
+<td>
+isPackagePrivate
+</td>
+<td>
+boolean - true for package-private methods and false for non-package-private methods
+</td>
+</tr>
+
+<tr>
+<td>
+isPublic
+</td>
+<td>
+boolean - true for public methods and false for non-public methods
+</td>
+</tr>
+
+<tr>
+<td>
+holder
+</td>
+<td>
+an object that represents Class that contains this method
+</td>
+</tr>
+
+<tr>
+<td>
+signature
+</td>
+<td>
+string -- signature of this method
+</td>
+</tr>
+
+<tr>
+<td>
+isObsolete
+</td>
+<td>
+boolean - true for obsolete (hotswapped) methods and false for non-obsolete methods
+</td>
+</tr>
+
+<tr>
+<td>
+isStrict
+</td>
+<td>
+boolean - true for strictfp methods and false for non-strictfp methods
+</td>
+</tr>
+
+<tr>
+<td>
+isFinal
+</td>
+<td>
+boolean - true for final methods and false for non-final methods
+</td>
+</tr>
+
+<tr>
+<td>
+name
+</td>
+<td>
+string - name of this method
+</td>
+</tr>
+</table>
+
+<h3>class object</h3>
+
+<p>
+A class object represents loaded Java class in debuggee VM. This represents java.lang.Class instance in the debuggee.
+This is type of return value of classof global function. Also, method.holder property and field.holder are
+of this type.
+</p>
+
+<table border="1">
+<tr>
+<th>
+Property name
+</th>
+<th>
+Description
+</th>
+</tr>
+
+<tr>
+<td>
+name
+</td>
+<td>
+name of this class
+</td>
+</tr>
+
+<tr>
+<td>
+superClass
+</td>
+<td>
+class object representing super class of this class
+</td>
+</tr>
+
+<tr>
+<td>
+isArrayClass
+</td>
+<td>
+boolean -- is the current class an array class?
+</td>
+</tr>
+
+<tr>
+<td>
+isStatic
+</td>
+<td>
+boolean -- is the current class static or not
+</td>
+</tr>
+
+<tr>
+<td>
+isInterface
+</td>
+<td>
+boolean -- is the current class an interface
+</td>
+</tr>
+
+<tr>
+<td>
+isAbstract
+</td>
+<td>
+boolean -- is the current class abstract or not
+</td>
+</tr>
+
+<tr>
+<td>
+isProtected
+</td>
+<td>
+boolean -- is the current class protected or not
+</td>
+</tr>
+
+<tr>
+<td>
+isPrivate
+</td>
+<td>
+boolean -- is the current class private or not
+</td>
+</tr>
+
+<tr>
+<td>
+isPackagePrivate
+</td>
+<td>
+boolean -- is the current class package private or not
+</td>
+</tr>
+
+<tr>
+<td>
+isSynthetic
+</td>
+<td>
+boolean -- is the current class synthetic or not
+</td>
+</tr>
+
+<tr>
+<td>
+classLoader
+</td>
+<td>
+object that represents ClassLoader object that loaded the current class
+</td>
+</tr>
+
+
+<tr>
+<td>
+fields
+</td>
+<td>
+array of static and instance fields of the current class
+</td>
+</tr>
+
+<tr>
+<td>
+protectionDomain
+</td>
+<td>
+protection domain to which current class belongs
+</td>
+</tr>
+
+<tr>
+<td>
+isPublic
+</td>
+<td>
+boolean -- is the current class public or not
+</td>
+</tr>
+
+<tr>
+<td>
+signers
+</td>
+<td>
+array of signers for current class
+</td>
+</tr>
+
+<tr>
+<td>
+sourceFile
+</td>
+<td>
+string -- name of the source file for current class
+</td>
+</tr>
+
+<tr>
+<td>
+interfaces
+</td>
+<td>
+array -- interfaces implemented by current class
+</td>
+</tr>
+
+<tr>
+<td>
+isStrict
+</td>
+<td>
+boolean -- is the current class strictfp or not
+</td>
+</tr>
+
+<tr>
+<td>
+methods
+</td>
+<td>
+array of methods (static and instance) of the current class
+</td>
+</tr>
+
+
+<tr>
+<td>
+isFinal
+</td>
+<td>
+boolean -- is the current class final or not
+</td>
+</tr>
+
+<tr>
+<td>
+statics
+</td>
+<td>
+name-value pairs (JavaScript associate array) of static fields of the current class
+</td>
+</tr>
+</table>
+
+<h3>field object</h3>
+<p>
+field represents a static or instance field of some class in debuggee
+</p>
+
+<table border="1">
+<tr>
+<th>
+Property name
+</th>
+<th>
+Description
+</th>
+</tr>
+
+<tr>
+<td>
+isStatic
+</td>
+<td>
+boolean -- is this field a static field?
+</td>
+</tr>
+
+<tr>
+<td>
+holder
+</td>
+<td>
+class that owns this field
+</td>
+</tr>
+
+<tr>
+<td>
+signature
+</td>
+<td>
+string signature of this field
+</td>
+</tr>
+
+<tr>
+<td>
+isProtected
+</td>
+<td>
+boolean - is this field a protected field or not?
+</td>
+</tr>
+
+<tr>
+<td>
+isPrivate
+</td>
+<td>
+boolean - is this field a private field or not?
+</td>
+</tr>
+
+<tr>
+<td>
+isSynthetic
+</td>
+<td>
+boolean - is this javac generated synthetic field or not?
+</td>
+</tr>
+
+<tr>
+<td>
+isPackagePrivate
+</td>
+<td>
+boolean - is this field a package private field or not?
+</td>
+</tr>
+
+<tr>
+<td>
+isTransient
+</td>
+<td>
+boolean - is this field a transient field or not?
+</td>
+</tr>
+
+<tr>
+<td>
+isFinal
+</td>
+<td>
+boolean - is this field final or not?
+</td>
+</tr>
+
+<tr>
+<td>
+name
+</td>
+<td>
+string - name of this field
+</td>
+</tr>
+
+<tr>
+<td>
+isPublic
+</td>
+<td>
+boolean - is this field public or not?
+</td>
+</tr>
+</table>
+
+<h3>Initialization Script</h3>
+<p>
+jsdb engine looks for initialization script file named <b>jsdb.js</b> in user's home directory. If found, it loads just after attaching to debuggee but before printing prompt for user's input. User can assume that s/he can access debuggee VM
+state during initialization script.
+</p>
+
+<h3>Sample scripts</h3>
+
+Semantics and knowledge of application classes (for eg. AppServer's classes) would be needed to create app specific
+scripts. The following script samples are app-independent and provide a flavour of kind of scripts that can be written.
+ 	
+<h4>Script to print system properties of JVM</h4>
+
+<pre>
+<code>
+jvm.sysProps.toString()
+</code>
+</pre>
+
+<h4>Script to print JVM command line flags</h4>
+<pre>
+<code>
+jvm.flags.toString()
+</code>
+</pre>
+
+
+<h4>Script to print class-wise histogram of objects</h4>
+
+<pre>
+<code>
+
+// associate array to hold histogram
+var histo;
+function func(obj) {
+    var classname = classof(obj).name;
+    if (histo[classname] == undefined) {
+       // first time we are visiting this class type
+       histo[classname] = 1;
+    } else {
+       histo[classname]++; 
+    }
+}
+
+// iterate through java heap calling 'func' for each object
+jvm.heap.forEachObject(func);
+
+// print the histogram
+for (i in histo) {
+   println('number of instances of ', i, ' = ', histo[i]);
+}
+
+</code>
+</pre>
+
+<h4>Script to print stack trace of all Java threads</h4>
+
+<pre>
+<code>
+
+function printStackTrace(t) {
+    println(t.name);
+    println('');
+    for (i in t.frames) {
+       println(t.frames[i]);
+    }
+    println('');
+}
+
+// walk through the list of threads and call printStackTrace
+// for each thread
+for (o in jvm.threads) {
+    printStackTrace(jvm.threads[o]);
+}
+
+
+</code>
+</pre>
+
+
+<h4>Script to re-construct .class files for all non-bootstrap classes</h4>
+
+<pre>
+<code>
+
+function dump(cl) {
+   if (!cl.isArrayClass  && cl.classLoader != null) { 
+      // not an array class and a non-bootstrap class
+      // create .class files in e:\tmp dir
+      dumpClass(cl, "e:\\tmp); 
+   } else {
+      println("skipping bootstrap class ", cl.name);
+   }
+}
+
+// walk thru heap and call callback for each java.lang.Class instance
+jvm.heap.forEachObject(dump, "java.lang.Class");
+</code>
+</pre>
+
+<h4>Script to print paths of all java.io.File's currently accessed</h4>
+
+<pre>
+<code>
+
+function printFile(f) {
+   // construct a mirror java.io.File here and
+   // print absolute path here
+   println(mirror(f).getAbsolutePath());
+}
+
+jvm.heap.forEachObject(printFile, "java.io.File");
+
+</code>
+</pre>
+
+<h4>Script to print static fields of java.lang.Thread class</h4>
+<pre>
+<code>
+
+var threadClass = classof("java.lang.Thread");
+for (i in threadClass.statics) {
+  println(i, '=', threadClass.statics[i]);
+}
+
+</code>
+</pre>
+
+<h3>Low level interface (VM State)</h3>
+
+<p>
+Low level jsdb interface works by <a href="http://www.mozilla.org/rhino/ScriptingJava.html">JavaScript-to-Java (previously known as "LiveConnect")
+interface</a> provided by Rhino JavaScript engine. 
+</p>
+
+<h2>sapkg object</h2>
+<p>
+This object provides short names for SA package names. For eg. instead of writing
+Packages.sun.jvm.hotspot.memory, we can write sapkg.memory.
+</p>
+
+<h2>sa object</h2>
+<p>
+This object contains all SA singleton objects such as VM, Universe, SymbolTable,
+SystemDictionary, ObjectHeap, CollectedHeap, Debugger, CDebugger (if available),
+Interpreter, TypeDataBase and Threads. For eg. to access SymbolTable of Java debuggee,
+we can use sa.symbolTable. User can execute the following code to get fields of this object.
+</p>
+<pre>
+<code>
+for (i in sa) {
+  println(i);
+}
+</code>
+</pre>
+
+<h4>Heap Iterators</h4>
+<dl>
+<dt>forEachOop(callback)</dt>
+<dd>calls a callback function for each Oop in Java heap</dd>
+<dt>forEachOopOfKlass(callback, klass, [includeSubtypes])</dt>
+<dd>calls a callback function for each Oop of a give Klass type
+Optinally, third argument can specify whether to include subtype Oops
+or not.
+</dd>
+</dl>
+
+<h4>System Dictionary Access</h4>
+<dl>
+<dt>forEachKlass(callback)</dt>
+<dd>calls a callback function for each Klass in Java heap</dd>
+<dt>forEachKlassAndLoader(callback)</dt>
+<dd>
+calls callback with Klass and initiating loader (Oop) for System dictionary
+entry.
+</dd>
+<dt>forEachPrimArrayKlass(callback)</dt>
+<dd>
+calls callback with Klass and initiating loader (Oop) for each
+primitive array Klass in the system.
+</dd>
+<dt>findInstanceKlass(name)</dt>
+<dd>
+finds the first instance klass with given name from System dictionary
+</dd>
+</dl>
+
+<h4>Thread, Frame Iterators</h4>
+<dl>
+<dt>forEachJavaThread(callback)</dt>
+<dd>calls callback for each Java Thread</dd>
+<dt>forEachFrame(javaThread, callback)</dt>
+<dd>calls callback for each Frame of a given JavaThread</dd>
+<dt>forEachVFrame(javaThread, callback)</dt>
+<dd>calls callback for each JavaVFrame of a given JavaThread</dd>
+<dt>forEachThread(callback)</dt>
+<dd>calls callback for each (native) ThreadProxy (obtained by CDebugger.getThreadList)
+</dd>
+<dt>forEachCFrame(threadProxy, callback)</dt>
+<dd>
+calls callback for each CFrame of a given ThreadProxy object
+</dd>
+</dl>
+
+<h4>Code blobs, Interpreter codelets</h4>
+<dl>
+<dt>forEachCodeBlob(callback)</dt>
+<dd>
+calls callback with each code blob in code cache
+</dd>
+<dt>findCodeBlob(address)</dt>
+<dd>
+finds the code blob, if any, that contains the given address.
+Returns null, on failure.
+</dd>
+<dt>findNMethod(address)</dt>
+<dd>
+finds the NMethod that contains given address.
+</dd>
+<dt>pcDescAt(addr)</dt>
+<dd>
+returns PCDesc at given address or null.
+</dd>
+<dt>forEachInterpCodelet(callbacl)</dt>
+<dd>
+calls callback with each Interpreter codelet
+</dd>
+</dl>
+
+<h4>VM structs, constants</h4>
+<dl>
+<dt>forEachType(callback)</dt>
+<dd>
+calls callback for each Type in VM's type database
+</dd>
+<dt>forEachVMIntConst(callback)</dt>
+<dd>
+calls callback for each named integer constant. passes name 
+as argument.
+</dd>
+<dt>forEachVMLongConst(callback)</dt>
+<dd>
+calls callback for each named long constant. passes name 
+as argument.
+</dd>
+<dt>findVMType(name)</dt>
+<dd>
+finds a VM type by name. returns null if no known Type of given name
+exists in type database.
+</dd>
+<dt>findVMIntConst(name)</dt>
+<dd>
+finds an integer constant in type data base by name.
+</dd>
+<dt>findVMLongConst(name)</dt>
+<dd>
+finds an long constant in type data base by name.
+</dd>
+<dt>vmTypeof(addr)</dt>
+<dd>
+returns VM type of object at 'addr' if any. Else, returns null.
+</dd>
+<dt>isOfVMType(addr, type)</dt>
+<dd>
+returns whether object at 'addr' is of VM type 'type' or not.
+</dd>
+<dt>printVMType(type, addr)</dt>
+<dd>
+prints 'addr' as VM object of type 'type'
+</dd>
+<dt>print<i>XXX</i>(addr)</dt>
+<dd>
+For each VM type, these functions are defined. For eg. there is printUniverse,
+printSystemDictionary etc. are available. Without 'addr' being passed static fields are printed. With 'addr' param being passed, instance fields are printed.
+</dd>
+</dl>
+
+<h4>Low level debugger facilities</h4>
+<dl>
+<dt>num2addr(number)</dt>
+<dd>
+converts a (long) number to SA Address instance
+</dd>
+<dt>str2addr(string)</dt>
+<dd>
+converts a given hex string to SA Address instance
+</dd>
+<dt>any2addr(any)</dt>
+<dd>
+Takes a number or a string or an Address and returns
+an Address instance. For other types, returns 'undefined'
+</dd>
+<dt>addr2str(addr)</dt>
+<dd>
+converts a given Address instance to a hex string
+</dd>
+<dt>addr2num(addr)</dt>
+<dd>
+converts a given Address instance to a (long) number
+</dd>
+<dt>sym2addr(library, symbol)</dt>
+<dd>
+returns Address of a given symbol in a given library (shared object or DLL)
+Example: sym2addr('jvm.dll', 'JNI_CreateJavaVM')
+<dt>addr2sym(addr)</dt>
+<dd>
+Returns nearest symbol to a given address (if any). If no such symbol is found,
+returns the given address as a string.
+</dd>
+<dt>readBytesAt(addr, num)</dt>
+<dd>
+returns 'num' bytes at 'addr' as a Java byte[]
+</dd>
+<dt>readWordsAt(addr, num)</dt>
+<dd>
+returns 'num' words at 'addr' as a Java long[]
+</dd>
+<dt>readCStrAt(addr)</dt>
+<dd>
+returns 'C' String at given address
+</dd>
+<dt>readCStrLen(addr)</dt>
+<dd>
+returns the length of the 'C' String at given address
+</dd>
+<dt>readRegs(threadProxy)</dt>
+<dd>
+returns register set (of Thread Context) of a given thread specified
+by threadProxy. return value is an associate array having name-value pairs
+of registers.
+</dd>
+<dt>regs(threadProxy)</dt>
+<dd>
+prints register set of a given thread.
+</dd>
+<dt>mem(addr, [num])</dt>
+<dd>
+prints 'num' words (address size) at 'addr'. Prints nearest symbol for address, if found.
+</dd>
+<dt>dis(addr, [num])</dt>
+<dd>prints native code disassembly of 'num' bytes at given address 'addr'.
+Default value of 'num' is 4. This automatically detects whether the given address
+inside a nmethod. If so, it prints safepoint info, entry points , method signature etc. 
+of the nmethod.
+</dd>
+<dt>jdis(method [or addr])</dt>
+<dd>
+prints Java bytecode disassembly for given method Oop or address of a method Oop.
+</dd>
+<dt>nmethoddis(nmethod)</dt>
+<dd>
+prints disassembly of given nmethod object. Note that you don't have to call this directly
+instead use 'dis'.
+</dd>
+<dt>where</dt>
+<dd>
+prints Java stack trace for all Java threads
+</dd>
+</dl>
+
+<h4>Miscellaneous</h4>
+<dl>
+<dt>addr2oop(addr)</dt>
+<dd>
+converts a given address to a Oop object
+</dd>
+<dt>oop2addr(oop)</dt>
+<dd>
+returns address of a given Oop object
+</dd>
+<dt>isOfVMType(addr, type)</dt>
+<dd>
+returns whether the given 'addr' points to a (C++) VM object of specified
+type. type may be specified by SA Type object or string name of the type.
+</dd>
+<dt>newVMObject(addr)</dt>
+<dd>
+returns instance of SA object for a given address (similar to SA VirtualConstructor
+interface).
+</dd>
+<dt>vmobj2addr(vmobject)</dt>
+<dd>
+returns Address represented by a given SA VMObject
+</dd>
+<dt>addr2vmobj(addr)</dt>
+<dd>same as newVMObject(addr)</dd>
+<dt>whatis(addr)</dt>
+<dd>
+returns string description of given address (using SA FindPointer and guess type API).
+<dt>isOop(addr)</dt>
+<dd>
+returns whether a given address is a valid Oop address or not
+</dd>
+</dl>
+
+<h4>Moving b/w jsdb low level and high level interfaces</h4>
+
+<p>
+Java objects of debuggee are represented by different script wrappers in high level
+interface. In the low-level interface these are instances of SA Oop class or its'
+subclass. To move b/w low-level and high-level interfaces the following functions may
+be used
+</p>
+<dl>
+<dt>oop2obj(oop)</dt>
+<dd>
+converts a given Oop object to a high-level wrapper object
+</dd>
+<dt>obj2oop(obj)</dt>
+<dd>
+converts a jsdb high level wrapper to underlying Oop instance
+</dd>
+</dl>
+
+<h3>JavaScript tips</h3>
+
+<ul>
+<li>to know properties, functions of any object, use the script
+<pre>
+<core>
+for(i in object) { println(i); }
+</code>
+</pre>
+<li>to view the source code of any function, just type the name of
+function in jsdb prompt
+<li>to view global functions, properties, run
+<pre>
+<code>
+for(i in this) { println(i); }
+</code>
+</pre>
+</ul>
+
+</body>
+</html>