JDWP Debugging

JDWP Debugging

Java Debug Wire Protocol (JDWP) remote debugging backend for JNode, enabling host-based debugging via jdb or other JDWP-compatible tools.

Overview

JNode implements a JDWP backend that allows debugging JNode from a host machine using standard Java debugging tools. The implementation uses a socket-based transport protocol and provides core debugging capabilities: class inspection, thread management, stack walking, variable access, and method invocation. This enables developers to debug JNode applications and the JNode runtime itself without relying solely on serial console output.

Key Components

Class/File	Purpose
cli/src/cli/org/jnode/command/dev/DebugCommand.java	Shell command to start JDWP listener
core/src/classpath/ext/gnu/classpath/jdwp/Jdwp.java	Main JDWP protocol handler
core/src/classpath/ext/gnu/classpath/jdwp/transport/JNodeSocketTransport.java	Socket-based transport for JDWP connections
core/src/classpath/vm/gnu/classpath/jdwp/JDIVirtualMachine.java	VM integration layer
core/src/classpath/vm/gnu/classpath/jdwp/NativeVMMethod.java	Method introspection
core/src/classpath/ext/gnu/classpath/jdwp/processor/MethodResolver.java	Index-based method ID resolution
tests/jdwp/	Python-based test suite (52 tests)

How It Works

Starting the Debug Listener

debug -p 8000

The debug command starts a JDWP listener on the specified port. It:

1. Creates a JNodeSocketTransport listening on the given port
2. Waits for a debugger (e.g., jdb) to connect
3. Handles JDWP packet processing in a dedicated thread

JDWP Command Sets

The implementation supports these JDWP command sets:

Command Set	Operations
VirtualMachine	Version, classes by signature, all classes, capabilities, instance counts
ReferenceType	Signature, fields, methods, constant pool, source file
ClassType	Superclass, instances, values
ThreadReference	Status, suspend/resume, stack trace, thread groups
ObjectReference	Reference type, field values, monitor info
StackFrame	Get/set local variables, this object
MethodInvocation	Invoke methods via reflection (static and instance)

Transport Protocol

JNodeSocketTransport implements the JDWP transport interface:

• TCP socket-based connection
• Handles JDWP packet framing (length prefix + flags + command + data)
• Supports command/reply/event packet types
• Connection lifecycle management

Method Invocation

Method invocation is implemented via reflection:

• Static methods: Method.invoke(null, args)
• Instance methods: Method.invoke(instance, args)
• Constructor invocation supported
• Return value encoding handles primitives, objects, arrays, and void

Stack Walking

Real stack walking is implemented:

• VmStackFrame provides frame information (method, PC, locals)
• VmStackFrameEnumerator walks the call stack
• Local variable access via VmLocalVariableTable
• Proper null checking and bounds validation

Test Suite

Location: tests/jdwp/

The test suite uses Python with pytest:

• 52 tests covering all command sets
• 100% pass rate
• Tests run against a live JNode VM with JDWP listener
• Requires VirtualBox or QEMU with JNode booted

Running Tests

cd tests/jdwp
python3 -m pytest -v

Tests require:

• JNode VM running with JDWP listener on port 8000
• Network connectivity between host and VM
• Python with pytest installed on host

Gotchas

1. Reflection-based invocation: Method invocation uses Java reflection, which may have limitations with final methods, private constructors, or security-restricted operations.

2. Thread suspension: Thread suspend/resume operations may not work correctly with JNode's native thread scheduler.

3. No hot-swap: Class redefinition (hot-swap) is not implemented.

4. Limited array support: Array inspection and modification have limited functionality.

5. Transport timeout: Socket transport may hang on network failures; bounded timeouts are not fully implemented.

6. Single connection: Only one debugger can connect at a time.

Related Pages

• GDB-Debugging-Support — In-kernel keyboard debugger
• Testing — Test infrastructure and boot testing
• VM-Unsafe — Low-level VM operations
• Core-Thread-Scheduling — Thread scheduler (affects suspend/resume)