About This Document

This document introduces the Native Code Access Interface and its implementation inside the DRL virtual machine.

Overview

Some Java* applications need to access native code via the Java* Native Interface (JNI) [1] to access native code. Common Java* debuggers, such as Eclipse* and NetBeans* debuggers, do not fully support debugging native code written in programming languages like C/C++. Some techniques, like the CDT plugin for Eclipse*, are used for debugging native code in Java* applications, but all of them have their own limitations.

Native Code Access Interface (NCAI) is a different approach to debugging JNI code in Java* applications. Together with JVMTI [2] it provides in-process debugging of both JIT-compiled and interpreted Java* bytecode, and native JNI code.

NCAI interface is a JVMTI-like interface exposed by DRLVM through a JVMTI extension. See detailed NCAI description for interface details.

The Eclipse* plugin utilizing NCAI interface is available at Intel* What If site [3]. This plugin supports Java* and C/C++, and builds into Eclipse* IDE re-using JDT and CDT debug views.

Examples of NCAI usage can be found in NCAI tests sources: trunk/drlvm/vm/tests/ncai.

Key Features

The current NCAI implementation supports x86 architecture; some features are available on x86_64.

Main NCAI features implemented for now:

Setting breakpoints in native code
Single-stepping through native code with 3 step modes: STEP_INTO, STEP_OVER and STEP_OUT
Trapping native signals and exceptions
Trapping loading and unloading of native modules
Getting information on loaded native modules
Getting the list of threads running in a VM process
OS-level thread operations: suspend, resume, terminate
Inspection and modification of processor registers for suspended threads
Getting the call stack with Java* and native frames
Native memory inspection and modification
Getting information on native signals and exceptions

NCAI in VM

NCAI is implemented as a part of DRLVM. The source code is generally located in the trunk/drlvm/vm/vmcore/src/ncai directory, with platform-dependent code in 'utils' subdirectory.

In addition to standalone code, NCAI includes code and changes in other parts of DRLVM, specifically:

In the VM Core subcomponent, NCAI extends JVMTI functionality, signal handling and breakpoints processing.
Thread Manager contains thread operations needed for NCAI operation.
The Porting Layer contains native modules enumeration and memory access functions for NCAI needs (both are also used now by Crash Handler), and OS-level thread operations including suspending and resuming of threads. NOTE: On Linux* OS, the SIGUSR2 signal is shared between NCAI threading and port_thread_yield_other() function implementation.
The encoder has been extended to enable the decoder to disassemble native code; this functionality is used by NCAI single stepping and by the Crash Handler.

Known issues

Known issues and limitations in the current NCAI implementation include:

Only threads attached to VM are reported.
The ModuleLoad and ModuleUnload events are reported only for JNI libraries.
The TerminateThread() function does not affect Java* thread status.
The GetStackTrace() function works fine for debug build only. On release build of either DRLVM or debugged library, the function can return partial stack trace.
The thread context obtained in during Breakpoint and Single Step processing is not synchronized with the thread context stored during thread suspension.

References

This section lists the resources used in this document and other related documents.

[1] Java* Native Interface Specification, http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/jniTOC.html

[2] JVM Tool Interface Specification, http://java.sun.com/j2se/1.5.0/docs/guide/jvmti/jvmti.html

[3] Intel* What If site, http://whatif.intel.com

* Other brands and names are the property of their respective owners.