The Maxine Inspector

Skip to end of metadata
Go to start of metadata

The Maxine Project: The Maxine Inspector


The Maxine Inspector is the essential all-in-one companion tool for Open Source Maxine VM development. It plays many roles:

  • object, class, and method browser;
  • code views include disassembled machine code, disassembled bytecode, and source;
  • low-level debugger (imagine gdb or dbx) with visual displays of threads, registers, stacks, stack frames, thread local values, breakpoints, memory watchpoints, etc.;
  • intermediate representation debugger;
  • source-level Java debugger (eventually); and
  • serviceability agent (eventually).
This short (5 minute) 2009 video appearing at the right describes the goals of the inspector and highlights some of the ways in which it makes Maxine VM development highly productive.

For a much longer (33 minute) technical discussion of the Inspector and its relation to the Maxine project, please see the video recording of Michael Van De Vanter's presentation at the 2010 JVM Language Summit.

Please be aware that the Inspector is very much a work in progress, as is the Maxine VM itself. The two have co-evolved and will continue to do so as the design of the VM matures and the concerns of the developers expand. Functionality is constantly being improved and extended, so there are already places where the current system differs from what you will find here.

More discussion and more detailed documentation follows below.


In addition to enhancing the productivity of our own development team, the Maxine Inspector is part of our strategic goal of making VM experimentation more accessible to a wider audience. By leveraging the meta-circularity of the VM itself (and sharing a great deal of the VM's source code), the Inspector makes it possible to visualize concisely many aspects of VM state that are elusive and widely distributed in other systems. These same advantages also make it possible to debug the VM with a single tool, highly specialized for this purpose.

Background and Rationale

Debugging virtual machines (VMs) presents unique challenges, expecially for a meta-circular VM, such as Maxine, that is self-implemented in the same language it implements. Making sense of Maxine's runtime state requires interaction simultaneously at the source, bytecode, and machine code abstraction levels, and it must leverage knowledge of the VM's design. Specific issues include:

  • Maxine VM code must be largely optimized statically, not only for ordinary performance reasons, but also in order to be able to bootstrap the VM at all.
  • Dynamic optimization at runtime can be applied to the VM's own implementation, not just application code.
  • Mapping optimized code locations back to bytecode and source locations is not generally possible without onerous limitations.
  • Dynamically de-optimizing code for debugging can be effective for application code, but only when the VM can be assumed correct.
  • Debugging the VM itself, however, requires scrutinizing its lowest-level, most optimized code representations and runtime machine state.
  • Special considerations arise when debugging garbage collection, for example the Inspector's dependence on the VM's meta-information about classes, methods, etc., which are represented as ordinary Java objects in the heap; garbage collection, however, routinely breaks the heap invariants that make those objects accessible.
  • Good debugging support is paramount for a VM intended for experimentation and fast prototyping.
    The Maxine Inspector addreses these concerns, supporting comprehensive inspection and interaction at all program representation levels.
  • Finally, these services must be available to developers in a wide variety of contexts: examining a pre-execution boot image, examining and controlling a live VM process (local or remote), and post-mortem examination of a VM core dump.

Furthermore, the Inspector's design exploits the fact that it is implemented in the same language that the VM implements and is implemented in; this gives rise to many code reuse opportunities. For example, the same mechanisms used by the VM's boot image generator, which allow the creation of objects in the binary runtime format for a potentially different platform, can be used by the Inspector to examine binary runtime state for a potentially different platform than the Inspector's host.

Downloading and Building the Inspector

The Inspector source code is part of the Maxine VM repository. It will download and build automatically with the rest of the Maxine code, as described on the Maxine VM Home Page. See also Inspector-specific issues on various platforms.

A Tour Through The Maxine Inspector

The best way to learn about the Inspector (and about many aspects of the Maxine VM) is to start up the Inspector on a simple VM session. For a beginner's introduction, however, the following pages introduce specific aspects of the Inspector's operation, in some cases with short video segments. The pages are threaded in a sequence so that you can navigate through them in order if you are new to the Inspector.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.

The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.