Controlling the Embedded VM

• Introduction (read this first!)
• Extended JNI Checks
• Assertions
• Bytecode Verification and Optimization
• Execution Mode
• Stack Dumps
• DEX File Checksums
• General Flags

Introduction (read this first!)

The Dalvik VM supports a variety of command-line arguments (use adb shell dalvikvm -help to get a summary), but it's not possible to pass arbitrary arguments through the Android application runtime. It is, however, possible to affect the VM behavior through certain system properties.

For all of the features described below, you would set the system property with setprop, issuing a shell command on the device like this:

adb shell setprop <name> <value>

The Android runtime must be restarted before the changes will take effect (adb shell stop; adb shell start). This is because the settings are processed in the "zygote" process, which starts early and stays around "forever".

You may not be able to set dalvik.* properties or restart the system as an unprivileged user. You can use adb root or run the su command from the device shell on "userdebug" builds to become root first. When in doubt,

adb shell getprop <name>

If you don't want the property to evaporate when the device reboots, add a line to /data/local.prop that looks like:

<name> = <value>

Such changes will survive reboots, but will be lost if the data partition is wiped. (Hint: create a local.prop on your workstation, then adb push local.prop /data. Or, use one-liners like adb shell "echo name = value >> /data/local.prop" -- note the quotes are important.)

Extended JNI Checks

JNI, the Java Native Interface, provides a way for code written in the Java programming language interact with native (C/C++) code. The extended JNI checks will cause the system to run more slowly, but they can spot a variety of nasty bugs before they have a chance to cause problems.

There are two system properties that affect this feature, which is enabled with the -Xcheck:jni command-line argument. The first is ro.kernel.android.checkjni. This is set by the Android build system for development builds. (It may also be set by the Android emulator unless the -nojni flag is provided on the emulator command line.) Because this is an "ro." property, the value cannot be changed once the device has started.

To allow toggling of the CheckJNI flag, a second property, dalvik.vm.checkjni, is also checked. The value of this overrides the value from ro.kernel.android.checkjni.

If neither property is defined, or dalvik.vm.checkjni is set to false, the -Xcheck:jni flag is not passed in, and JNI checks will be disabled.

To enable JNI checking:

adb shell setprop dalvik.vm.checkjni true

You can also pass JNI-checking options into the VM through a system property. The value set for dalvik.vm.jniopts will be passed in as the -Xjniopts argument. For example:

adb shell setprop dalvik.vm.jniopts forcecopy

Assertions

Dalvik VM supports the Java programming language "assert" statement. By default they are off, but the dalvik.vm.enableassertions property provides a way to set the value for a -ea argument.

The argument behaves the same as it does in other desktop VMs. You can provide a class name, a package name (followed by "..."), or the special value "all".

For example, this:

adb shell setprop dalvik.vm.enableassertions all

The system property is much more limited than the full command line. It is not possible to specify more than one -ea entry, and there is no way to specify a -da entry. There is presently no equivalent for -esa/-dsa.

Bytecode Verification and Optimization

The system tries to pre-verify all classes in a DEX file to reduce class load overhead, and performs a series of optimizations to improve runtime performance. Both of these are done by the dexopt command, either in the build system or by the installer. On a development device, dexopt may be run the first time a DEX file is used and whenever it or one of its dependencies is updated ("just-in-time" optimization and verification).

There are two command-line flags that control the just-in-time verification and optimization, -Xverify and -Xdexopt. The Android framework configures these based on the dalvik.vm.dexopt-flags property.

If you set:

adb shell setprop dalvik.vm.dexopt-flags v=a,o=v

You could also set dalvik.vm.dexopt-flags to v=n to have the framework pass -Xverify:none -Xdexopt:verified to disable verification. (We could pass in -Xdexopt:all to allow optimization, but that wouldn't necessarily optimize more of the code, since classes that fail verification may well be skipped by the optimizer for the same reasons.) Classes will not be verified by dexopt, and unverified code will be loaded and executed.

Enabling verification will make the dexopt command take significantly longer, because the verification process is fairly slow. Once the verified and optimized DEX files have been prepared, verification incurs no additional overhead except when loading classes that failed to pre-verify.

If your DEX files are processed with verification disabled, and you later turn the verifier on, application loading will be noticeably slower (perhaps 40% or more) as classes are verified on first use.

For best results you should force a re-dexopt of all DEX files when this property changes. You can do this with:

adb shell "rm /data/dalvik-cache/*"

(Previous version of the runtime supported the boolean dalvik.vm.verify-bytecode property, but that has been superceded by dalvik.vm.dexopt-flags.)

Execution Mode

The current implementation of the Dalvik VM includes three distinct interpreter cores. These are referred to as "fast", "portable", and "debug". The "fast" interpreter is optimized for the current platform, and might consist of hand-optimized assembly routines. In constrast, the "portable" interpreter is written in C and expected to run on a broad range of platforms. The "debug" interpreter is a variant of "portable" that includes support for profiling and single-stepping.

The VM may also support just-in-time compilation. While not strictly a different interpreter, the JIT compiler may be enabled or disabled with the same flag. (Check the output of dalvikvm -help to see if JIT compilation is enabled in your VM.)

The VM allows you to choose between "fast", "portable", and "jit" with an extended form of the -Xint argument. The value of this argument can be set through the dalvik.vm.execution-mode system property.

To select the "portable" interpreter, you would use:

adb shell setprop dalvik.vm.execution-mode int:portable

Not all platforms have an optimized implementation. In such cases, the "fast" interpreter is generated as a series of C stubs, and the result will be slower than the "portable" version. (When we have optimized versions for all popular architectures the naming convention will be more accurate.)

If profiling is enabled or a debugger is attached, the VM switches to the "debug" interpreter. When profiling ends or the debugger disconnects, the original interpreter is resumed. (The "debug" interpreter is substantially slower, something to keep in mind when evaluating profiling data.)

The JIT compiler can be disabled on a per-application basis by adding android:vmSafeMode="true" in the application tag in AndroidManifest.xml. This can be useful if you suspect that JIT compilation is causing your application to behave incorrectly.

Stack Dumps

Like other desktop VMs, when the Dalvik VM receives a SIGQUIT (Ctrl-\ or kill -3), it dumps stack traces for all threads. By default this goes to the Android log, but it can also be written to a file.

The dalvik.vm.stack-trace-file property allows you to specify the name of the file where the thread stack traces will be written. The file will be created (world writable) if it doesn't exist, and the new information will be appended to the end of the file. The filename is passed into the VM via the -Xstacktracefile argument.

For example:

adb shell setprop dalvik.vm.stack-trace-file /tmp/stack-traces.txt

If the property is not defined, the VM will write the stack traces to the Android log when the signal arrives.

DEX File Checksums

For performance reasons, the checksum on "optimized" DEX files is ignored. This is usually safe, because the files are generated on the device, and have access permissions that prevent modification.

If the storage on a device becomes unreliable, however, data corruption can occur. This usually manifests itself as a repeatable virtual machine crash. To speed diagnosis of such failures, the VM provides the -Xcheckdexsum argument. When set, the checksums on all DEX files are verified before the contents are used.

The application framework will provide this argument during VM creation if the dalvik.vm.check-dex-sum property is enabled.

To enable extended DEX checksum verification:

adb shell setprop dalvik.vm.check-dex-sum true

Incorrect checksums will prevent the DEX data from being used, and will cause errors to be written to the log file. If a device has a history of problems it may be useful to add the property to /data/local.prop.

Note also that the dexdump tool always verifies DEX checksums, and can be used to check for corruption in a large set of files.

General Flags

In the "Gingerbread" release, a general mechanism for passing flags to the VM was introduced:

adb shell setprop dalvik.vm.extra-opts "flag1 flag2 ... flagN"

The flags are separated by spaces. You can specify as many as you want so long as they all fit within the system property value length limit (currently 92 characters).

The extra-opts flags will be added at the end of the command line, which means they will override earlier settings. This can be used, for example, to experiment with different values for -Xmx even though the Android framework is setting it explicitly.