JavaTM Platform Debugger Architecture - Readme
JavaTM Platform Debugger
Architecture (JPDA) is the new debugging support for the
Java 2 Platform.
JPDA provides all the infrastructure needed to build
professional end-user debugger applications.
Check the license agreement for redistribution information.
JPDA has been tested most on the Classic Virtual Machine platforms
shipped with the Java 2 Software Development Kit (J2SDK), version 1.2.2,
and it is known to work well on those platforms.
However, JPDA can be used, with restrictions, on any of the following
versions of Sun VMs. Click on the VM you use to learn more about the
bugs and limitations associated with it.
- Sun Win32 Classic VM versions
1.2,
1.2.1,
1.2.2 and higher.
- Sun Win32 HotSpotTM Performance Engine version
1.0 and higher.
- Sun SolarisTM Reference (Classic) VM versions
1.2,
1.2.1,
1.2.2 and higher.
- Sun SolarisTM Production VM
versions 1.2.1_03 and higher.
- Sun SolarisTM HotSpotTM Performance Engine version
1.0 and higher.
We are very interested in your input. Send comments, questions, and bug
reports to
java-debugger@java.sun.com
The Debugging Interfaces
This release contains the reference implementations of the Java
Debug Interface (JDI) and the Java Debug Wire Protocol (JDWP).
See the documentation in doc/index.html
for more information on
these interfaces. We provide a set of class files and native libraries
which implement the JDI. This implementation uses the JDWP to communicate
between a debugger virtual machine (front-end) and target virtual machine
(back-end).
The front-end support is contained in
a set of class files. The back-end support is contained in
native libraries
that are loaded into the target virtual machine when an application is
debugged.
The Java Virtual Machine Debugging Interface (JVMDI) is a low level
native interface that is provided by a Java virtual machine.
Contents
The doc
directory contains
overview documentation for the
various interfaces as well as detailed
documentation for the JDI in doc/jdi/index.html.
The lib
directory contains jpda.jar
:
the JDI specification packages,
the reference implementation of the JDI, and
example debugger applications.
The examples
directory contains examples.jar
,
source code for
the example applications jdb
and javadt
.
On Win32 platforms, the bin
directory contains
jdb.exe
, a line mode debugger
implemented with JDI.
javadt.exe
, a simple,
graphical debugger implemented with JDI.
jdwp.dll
, the
native library that implements back-end support for the JDI.
dt_socket.dll
and dt_shmem.dll
, the
native libraries that implement socket and shared memory transports used
by JDI and JDWP.
On Solaris platforms, the bin
directory contains
jdb
, a line mode debugger
implemented with JDI.
javadt
, a simple,
graphical debugger implemented with JDI.
On Solaris platforms,
the lib/sparc
directory contains
libjdwp.so
, the native library that implements
back-end support for the JDI.
libdt_socket.so
, the
native library that implements the socket transports used by JDWP.
Manually Launching the Application VM
If you are running the version of jdb
provided in
this release, the application VM is launched for you with the debugger
back end loaded. However, in the following cases, you will be
launching your own application VM, either by hand or in your
implementation.
- Remote debugging with the
-attach
or -listen
jdb
option.
- You are implementing a debugger which uses the JDWP directly.
- You are implementing a debugger back end which uses JVMDI.
Currently, the first two cases require a command line like the following:
java -Xdebug -Xnoagent -Djava.compiler=NONE
-Xrunjdwp:transport=dt_socket,server=y,suspend=y
-classpath
class-path class-name
The -Xdebug
option enables debugging. The
-Xnoagent
disables the default sun.tools.debug debug Agent. The
-Djava.compiler=NONE
disables the JIT compiler.
For the third case, you must use the same command line options
as described above, but you are free to use your own mechanism for
loading the JVMDI client into the application VM. You do not need to use
-Xrun.
The Connection and Invocation Details document
contains more information on necessary
VM invocation options
and sub-options of -Xrunjdwp
.
Known Bugs and Limitations
All Platforms
The following bugs and limitation exist on all platforms.
- On all known platforms,
incorrectly generated local variable tables can cause the back-end to
crash (bug #4244598). IBM Jikes compiler has been known to generate
invalid tables in the presence of unused local variables. The 1.2 javac
compiler generates invalid tables under obscure circumstances (bug #4243183).
- 4230262: Out of memory conditions in the target VM are not handled gracefully
in all situations. In particular, an out of memory condition during the
processing of method entry or exception events can lead to stack overflow
in the target VM.
- 4252005: EventQueue.remove can throw an ObjectCollectedException if an
event is requested with suspend policy SUSPEND_NONE and associated
objects or classes are garbage-collected before the event is processed.
- 4252790: Locatable.location() should return null for abstract or native
methods. Instead it returns an invalid location which will result
in internal exceptions when used elsewhere. Use Method.isNative
and Method.isAbstract to work around this bug.
The following bugs exist in the 1.2.2 Win32 classic VM
and Solaris Reference VM JVMDI implementations.
- Attempts to retrieve a method's bytecodes can result in a
hang.
- 4184934: Returned method bytecodes can contain "quick" instruction
optimizations instead of the original method bytecodes.
- 4184913: Step events cannot be requested for the entire VM at once; instead,
they must be requested on a per-thread basis.
In addition to the bugs listed above for version 1.2.2,
the following bugs exist in the 1.2 and 1.2.1 Win32 classic VM
and Solaris Reference VM JVMDI implementations.
- 4195595: Some events that occur at the same location are not properly combined
into event sets; instead, they are reported separately as single-element
event sets. This happens when events of different kinds occur at the same
thread and location.
- 4199393: For classes compiled without -g, JDI responds to queries for
local variables with empty lists instead of throwing the appropriate
AbsentInformationException.
- 4195595: Some breakpoints at the start of methods are not reported if
you are also stepping over the method invocation.
- 4191820: Incorrect local variable values are reported during method exit events.
- 4184924: Redundant step events are generated when instruction stepping through
quicked instructions for the first time.
- Some crashes have been reported during step operations.
Sun Win32 Production VM and Solaris Reference VM, earlier than 1.2
Releases of the Sun Classic VM earlier than 1.2 cannot be
used with this release of JPDA.
Important: Due to a bug in this version of the Production VM,
you should set the environment variable
_JAVA_JDWP_OPTIONS
to "stdalloc=y"
before
running with this version of the Solaris Production VM with JPDA.
See list below for details.
JPDA has undergone limited testing with the
1.2.1_03 Solaris Production VM.
It is presumed that all
Solaris Reference VM, 1.2.1 bugs also
exist in this VM.
The following bugs are known to exist in this
version of the Solaris Production VM JVMDI implementation.
- 4241264: A bug in memory allocator usage causes a
segmentation fault, usually
fairly early in a debugging session. This can be worked around by forcing
the use of the standard allocator (malloc); however, as a result there is
a small chance of hanging due to contention for the malloc lock.
To force the use of the standard allocator either set the _JAVA_JDWP_OPTIONS
environment variable as shown above, or add "stdalloc=y" to the
"-Xrunjdwp:" arguments on the launching of the back-end.
- Hangs may occur caused by object creation contention for raw monitors.
Solaris Production VM, earlier than 1.2.1_03
Production releases of the Sun
Solaris VM earlier than 1.2.1_03 cannot be
used with this release of JPDA.
JPDA support is considered to be beta quality in version 1.0 of the
Hotspot Performance Engine. The following bugs exist in this version
of the HotSpot Performance Engine JVMDI implementation.
- 4248826: Method entry/exit events are not reported for empty methods.
- 4241116,4245697: Stepping is inconsistent.
- 4252694: Breakpoints on java.lang.Thread.resume are ignored.
- 4259923: Incorrect values reported for locals of type long, float, and double.
- 4261718: Access to ThreadGroup functionality causes VM crashes.
- 4259927: For classes compiled without -g, JDI responds to queries for
local variables with empty lists instead of throwing the appropriate
AbsentInformationException.
Change Log