Maxine-VM Documentation Release 2.9.0 The Maxine Team of the University of Manchester Jun 18, 2020 Contents 1 Project Overview3 2 Citation 5 3 Getting Started7 4 Features 9 5 Roadmap 11 6 Acknowledgements 13 7 Table of Contents 15 7.1 Build and Usage Instructions................................ 15 7.2 Status............................................ 19 7.3 Developing Maxine on IDEs................................ 22 7.4 Papers and Presentations.................................. 25 7.5 The Maxine Project: Contributors............................. 29 7.6 Debugging......................................... 32 7.7 Offline Compilation.................................... 35 7.8 Frequently Asked Questions................................ 40 7.9 Glossary of Maxine terminology and concepts...................... 42 7.10 Actors........................................... 47 7.11 JDK interoperation..................................... 49 7.12 VM Boot Image...................................... 53 7.13 Memory Management................................... 60 7.14 Management of Code Dependencies............................ 61 7.15 Code Eviction in the Maxine VM............................. 63 7.16 Object representation in the Maxine VM......................... 65 7.17 Schemes: Interfaces for Maxine VM Configuration.................... 73 7.18 Snippets in the Maxine VM................................ 77 7.19 Stack Walking in the Maxine VM............................. 84 7.20 Threads in the Maxine VM................................. 88 7.21 Type-based Logging.................................... 94 7.22 Virtual Machine Level Analysis.............................. 99 7.23 VM Operations....................................... 113 7.24 VM Tooling interface................................... 117 i 7.25 The Maxine Inspector................................... 119 8 Indices and tables 179 ii Maxine-VM Documentation, Release 2.9.0 A next generation, highly productive platform for virtual machine research. Contents 1 Maxine-VM Documentation, Release 2.9.0 2 Contents CHAPTER 1 Project Overview In this era of modern, managed languages we demand ever more from our virtual machines: better performance, more scalability, and support for the latest new languages. Research and experimentation is essential but challenging in the context of mature, complex, production VMs written in multiple languages. The Maxine VM is a next generation platform that establishes a new standard of productivity in this area of research. It is written entirely in Java, completely compatible with modern Java IDEs and the standard JDK, features a modular architecture that permits alternate implementations of subsystems such as GC and compilation to be plugged in, and is accompanied by a dedicated development tool (the Maxine Inspector) for debugging and visualizing nearly every aspect of the VM’s runtime state. As of the 2.0 release, September 2013, Maxine is no longer an active project at Oracle Labs. As of the 2.1 release, April 2017, Maxine VM is actively maintained and developed at the University of Manchester. We believe that Maxine represents the state of the art in a research VM, and actively encourage community involvement. The Maxine sources, including VM, Inspector, and other supporting tools, are Open Source and are licensed under GPL version 2.0. To obtain the code please visit https: //github.com/beehive-lab. 3 Maxine-VM Documentation, Release 2.9.0 4 Chapter 1. Project Overview CHAPTER 2 Citation For Maxine VM >= v2.1 please cite: Christos Kotselidis, et al. Heterogeneous Managed Runtime Sys- tems: A Computer Vision Case Study. In 13th ACM SIGPLAN/SIGOPS International Conference on Virtual Execution Environments (VEE), 2017. For the original Maxine VM please cite: C. Wimmer et al, “Maxine: An approachable virtual machine for, and in, java”, In ACM TACO 2013. To cite the software itself please use. 5 Maxine-VM Documentation, Release 2.9.0 6 Chapter 2. Citation CHAPTER 3 Getting Started • Download and build Maxine from source on any of the supported Supported Platforms. • Read the technical report “Maxine: An Approachable Virtual Machine For, and In, Java” • Send any questions to this mailing list([email protected]). • Read about the current status of the VM. • Learn more about the Maxine Inspector, the companion tool for visualizing internal state and debugging the VM: video introduction, video demos, and written documentation. • Learn more about Virtual Machine Level Analysis, an experimental extension for analysis the behavior of application (and eventually the VM). • View publications and presentations about Maxine. • Read the Glossary and FAQ. • Contact us on the the mailing list (or in private) and tell us about your work. 7 Maxine-VM Documentation, Release 2.9.0 8 Chapter 3. Getting Started CHAPTER 4 Features Some of the features of Maxine that make it a compelling platform for (J)VM research include: • Nearly all of the code base is written in Java and exploits advanced language features appearing in JDK 5 and beyond: for example annotations, static imports, and generics. • The VM integrates with openJDK. There’s no need to download (and build) other implementations of the standard Java classes. • The source code supports development in Eclipse, Netbeans or IntelliJ all of which provide ex- cellent support for cross-referencing and browsing the code. It also means that refactoring can be confidently employed to continuously improve the structure of the code. • The Maxine Inspector produces visualizations of nearly every aspect of the VM runtime state, and provides advanced, VM-specific debugging. • The source code is hosted on GitHub making downloading and collaboration easier. 9 Maxine-VM Documentation, Release 2.9.0 10 Chapter 4. Features CHAPTER 5 Roadmap • Implement JVMCI, Upgrade to latest Graal • Run Truffle on top of Maxine VM/Graal • Port MMTk to Maxine VM 11 Maxine-VM Documentation, Release 2.9.0 12 Chapter 5. Roadmap CHAPTER 6 Acknowledgements This documentation is heavily based on the original wiki pages (by Oracle) that can be found here and here. 13 Maxine-VM Documentation, Release 2.9.0 14 Chapter 6. Acknowledgements CHAPTER 7 Table of Contents 7.1 Build and Usage Instructions The easiest way to build and use Maxine is through the beehivelab/maxine-dev docker image. This image comes with all dependencies installed and configured. You only need to get the latest maxine sources and build them through the container. Note: If for some reason using docker is not desirable/possible please refer to the end of this page for instructions on building maxine without docker. 7.1.1 Getting the source code The docker image expects the source code to be in the layout shown below: $ tree -L1 maxine-src maxine-src maxine mx To get the source code in this layout execute: $ mkdir maxine-src $ git clone https://github.com/graalvm/mx.git maxine-src/mx $ git clone https://github.com/beehive-lab/Maxine-VM.git maxine-src/maxine 7.1.2 Developing using a docker container On macOS (and Windows) unfortunately simply mounting host directories on docker containers, al- though functional, is slow. To work arround this issue we use docker-sync. Additionally we run an rsync daemon on the docker container, this way users that don’t want to use docker-sync can manualy 15 Maxine-VM Documentation, Release 2.9.0 rsync files from the host to the container and vice versa (through rsync://localhost:9873/ root which maps to /root/ on the container). To create a docker container named maxine-dev from the beehivelab/maxine-dev docker image enter maxine-src/maxine/docker and run: docker-compose up --no-start Note that the container is now created but does not contain the source code. Keeping your data on the host in sync with your data on the docker container Install docker-rsync: gem install docker-sync To start it enter maxine-src/maxine/docker/ and run: docker-sync start To stop it: docker-sync stop Using the maxine-dev container To use the container issue docker start -i maxine-dev. This will start the container and open a bash shell in it. From this shell you can build and run maxine. As long as docker-sync is running any changes you make on the host or the container will become visible to the counterpart as well. To exit the shell and stop the container type Ctrl-D. 7.1.3 Build • Enter the maxine source directory: cd $MAXINE_HOME • Compile the source code: mx build Executing mx build in the $MAXINE_HOME directory compiles the Java source code of Maxine to class files using javac (or the Eclipse batch compiler if you use the -jdt option) and compiles the native code of Maxine to executable code using your platform’s C compiler. The build process attempts to download some necessary files from the internet. If you are behind a firewall set the HTTP_PROXY environment variable appropriately before starting the build. • Generate the boot image: mx image 16 Chapter 7. Table of Contents Maxine-VM Documentation, Release 2.9.0 The mx image command is used to generate a boot image. This command runs Maxine on a host JVM to configure a prototype, then compiles its own code and data to create an executable program for the target platform. 7.1.4 Running With the native substrate and a boot image built, the Maxine VM can now be executed. The mx vm command handles the details of class and library paths and provides an interface similar to the standard java launcher command. The mx script includes a command to run a simple HelloWorld program to verify that the VM is working: mx helloworld Now let’s use Maxine to run a more substantial program: mx vm -cp test/bin test.output.GCTest2 To launch the VM (or any other command for that matter) without using mx, the -v option echoes the commands issued by the mx script: mx -v helloworld 7.1.5 Creating a Maxine-based JDK To create a Maxine-based JDK that can serve as a replacement for OpenJDK or OracleJDK issue: mx makejdk This will create the directory $MAXINE_HOME/maxjdk which you can now use as the JAVA_HOME for running java with Maxine. 7.1.6 Profiling Various profiling tools are available for the Java platform, with varying degrees of overhead.