jdk8-mips64-public/hotspot: agent/doc/jsdb.html@dbb05f6d93c4 (annotated)

agent/doc/jsdb.html@dbb05f6d93c4 (annotated)

agent/doc/jsdb.html

Mon, 28 Jul 2014 15:06:38 -0700

author: fzhinkin
date: Mon, 28 Jul 2014 15:06:38 -0700
changeset 6997: dbb05f6d93c4
parent 0: f90c822e73f8
permissions: -rw-r--r--

8051344: JVM crashed in Compile::start() during method parsing w/ UseRTMDeopt turned on
Summary: call rtm_deopt() only if there were no compilation bailouts before.
Reviewed-by: kvn

 <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>

Mercurial > jdk8-mips64-public > hotspot / annotate

agent/doc/jsdb.html@dbb05f6d93c4 (annotated)

agent/doc/jsdb.html