1<html> 2<head> 3 <title>Controlling the Embedded VM</title> 4 <link rel=stylesheet href="android.css"> 5</head> 6 7<body> 8<h1>Controlling the Embedded VM</h1> 9 10<ul> 11 <li><a href="#overview">Overview</a> 12 <li><a href="#checkjni">Extended JNI Checks</a> 13 <li><a href="#assertions">Assertions</a> 14 <li><a href="#verifier">Bytecode Verification and Optimization</a> 15 <li><a href="#execmode">Execution Mode</a> 16 <li><a href="#dp">Deadlock Prediction</a> 17 <li><a href="#stackdump">Stack Dumps</a> 18 <li><a href="#dexcheck">DEX File Checksums</a> 19</ul> 20 21<h2><a name="overview">Overview</a></h2> 22 23<p>The Dalvik VM supports a variety of command-line arguments 24(use <code>adb shell dalvikvm -help</code> to get a summary), but 25it's not possible to pass arbitrary arguments through the 26Android application runtime. It is, however, possible to affect the 27VM behavior through certain system properties. 28 29<p>For all of the features described below, you would set the system property 30with <code>setprop</code>, 31issuing a shell command on the device like this: 32<pre>adb shell setprop <name> <value></pre> 33 34<p>The Android runtime must be restarted before the changes will take 35effect (<code>adb shell stop; adb shell start</code>). This is because the 36settings are processed in the "zygote" process, which starts early and stays 37around "forever". 38 39<p>You may not be able to set this as an unprivileged user. You can use 40<code>adb root</code> or run the <code>su</code> command from the device 41shell on "userdebug" builds to become root first. When in doubt, 42<pre>adb shell getprop <name></pre> 43will tell you if the <code>setprop</code> took. 44 45<p>If you don't want the property to evaporate when the device reboots, 46add a line to <code>/data/local.prop</code> that looks like: 47<pre><name> = <value></pre> 48 49<p>Such changes will survive reboots, but will be lost if the data 50partition is wiped. (Hint: create a <code>local.prop</code> 51on your workstation, then <code>adb push local.prop /data</code> . Or, 52use one-liners like 53<code>adb shell "echo name = value >> /data/local.prop"</code> -- note 54the quotes are important.) 55 56 57<h2><a name="checkjni">Extended JNI Checks</a></h2> 58 59<p>JNI, the Java Native Interface, provides a way for code written in the 60Java programming language 61interact with native (C/C++) code. The extended JNI checks will cause 62the system to run more slowly, but they can spot a variety of nasty bugs 63before they have a chance to cause problems. 64 65<p>There are two system properties that affect this feature, which is 66enabled with the <code>-Xcheck:jni</code> command-line argument. The 67first is <code>ro.kernel.android.checkjni</code>. This is set by the 68Android build system for development builds. (It may also be set by 69the Android emulator unless the <code>-nojni</code> flag is provided on the 70emulator command line.) Because this is an "ro." property, the value cannot 71be changed once the device has started. 72 73<p>To allow toggling of the CheckJNI flag, a second 74property, <code>dalvik.vm.checkjni</code>, is also checked. The value 75of this overrides the value from <code>ro.kernel.android.checkjni</code>. 76 77<p>If neither property is defined, or <code>dalvik.vm.checkjni</code> 78is set to <code>false</code>, the <code>-Xcheck:jni</code> flag is 79not passed in, and JNI checks will be disabled. 80 81<p>To enable JNI checking: 82<pre>adb shell setprop dalvik.vm.checkjni true</pre> 83 84<p>You can also pass JNI-checking options into the VM through a system 85property. The value set for <code>dalvik.vm.jniopts</code> will 86be passed in as the <code>-Xjniopts</code> argument. For example: 87<pre>adb shell setprop dalvik.vm.jniopts forcecopy</pre> 88 89<p>For more information about JNI checks, see 90<a href="jni-tips.html">JNI Tips</a>. 91 92 93<h2><a name="assertions">Assertions</a></h2> 94 95<p>Dalvik VM supports the Java programming language "assert" statement. 96By default they are off, but the <code>dalvik.vm.enableassertions</code> 97property provides a way to set the value for a <code>-ea</code> argument. 98 99<p>The argument behaves the same as it does in other desktop VMs. You 100can provide a class name, a package name (followed by "..."), or the 101special value "all". 102 103<p>For example, this: 104<pre>adb shell setprop dalvik.vm.enableassertions all</pre> 105enables assertions in all non-system classes. 106 107<p>The system property is much more limited than the full command line. 108It is not possible to specify more than one <code>-ea</code> entry, and there 109is no way to specify a <code>-da</code> entry. There is presently no 110equivalent for <code>-esa</code>/<code>-dsa</code>. 111 112 113<h2><a name="verifier">Bytecode Verification and Optimization</a></h2> 114 115<p>The system tries to pre-verify all classes in a DEX file to reduce 116class load overhead, and performs a series of optimizations to improve 117runtime performance. Both of these are done by the <code>dexopt</code> 118command, either in the build system or by the installer. On a development 119device, <code>dexopt</code> may be run the first time a DEX file is used 120and whenever it or one of its dependencies is updated ("just-in-time" 121optimization and verification). 122 123<p>There are two command-line flags that control the just-in-time 124verification and optimization, 125<code>-Xverify</code> and <code>-Xdexopt</code>. The Android framework 126configures these based on the <code>dalvik.vm.dexopt-flags</code> 127property. 128 129<p>If you set: 130<pre>adb shell setprop dalvik.vm.dexopt-flags v=a,o=v</pre> 131then the framework will pass <code>-Xverify:all -Xdexopt:verified</code> 132to the VM. This enables verification, and only optimizes classes that 133successfully verified. This is the safest setting, and is the default. 134<p>You could also set <code>dalvik.vm.dexopt-flags</code> to <code>v=n</code> 135to have the framework pass <code>-Xverify:none -Xdexopt:verified</code> 136to disable verification. (We could pass in <code>-Xdexopt:all</code> to 137allow optimization, but that wouldn't necessarily optimize more of the 138code, since classes that fail verification may well be skipped by the 139optimizer for the same reasons.) Classes will not be verified by 140<code>dexopt</code>, and unverified code will be loaded and executed. 141 142<p>Enabling verification will make the <code>dexopt</code> command 143take significantly longer, because the verification process is fairly slow. 144Once the verified and optimized DEX files have been prepared, verification 145incurs no additional overhead except when loading classes that failed 146to pre-verify. 147 148<p>If your DEX files are processed with verification disabled, and you 149later turn the verifier on, application loading will be noticeably 150slower (perhaps 40% or more) as classes are verified on first use. 151 152<p>For best results you should force a re-dexopt of all DEX files when 153this property changes. You can do this with: 154<pre>adb shell "rm /data/dalvik-cache/*"</pre> 155This removes the cached versions of the DEX files. Remember to 156stop and restart the runtime (<code>adb shell stop; adb shell start</code>). 157 158<p>(Previous version of the runtime supported the boolean 159<code>dalvik.vm.verify-bytecode</code> property, but that has been 160superceded by <code>dalvik.vm.dexopt-flags</code>.)</p> 161 162 163<h2><a name="execmode">Execution Mode</a></h2> 164 165<p>The current implementation of the Dalvik VM includes three distinct 166interpreter cores. These are referred to as "fast", "portable", and 167"debug". The "fast" interpreter is optimized for the current 168platform, and might consist of hand-optimized assembly routines. In 169constrast, the "portable" interpreter is written in C and expected to 170run on a broad range of platforms. The "debug" interpreter is a variant 171of "portable" that includes support for profiling and single-stepping. 172 173<p>The VM may also support just-in-time compilation. While not strictly 174a different interpreter, the JIT compiler may be enabled or disabled 175with the same flag. (Check the output of <code>dalvikvm -help</code> to 176see if JIT compilation is enabled in your VM.) 177 178<p>The VM allows you to choose between "fast", "portable", and "jit" with an 179extended form of the <code>-Xint</code> argument. The value of this 180argument can be set through the <code>dalvik.vm.execution-mode</code> 181system property. 182 183<p>To select the "portable" interpreter, you would use: 184<pre>adb shell setprop dalvik.vm.execution-mode int:portable</pre> 185If the property is not specified, the most appropriate interpreter 186will be selected automatically. At some point this mechanism may allow 187selection of other modes, such as JIT compilation. 188 189<p>Not all platforms have an optimized implementation. In such cases, 190the "fast" interpreter is generated as a series of C stubs, and the 191result will be slower than the 192"portable" version. (When we have optimized versions for all popular 193architectures the naming convention will be more accurate.) 194 195<p>If profiling is enabled or a debugger is attached, the VM 196switches to the "debug" interpreter. When profiling ends or the debugger 197disconnects, the original interpreter is resumed. (The "debug" interpreter 198is substantially slower, something to keep in mind when evaluating 199profiling data.) 200 201 202<h2><a name="dp">Deadlock Prediction</a></h2> 203 204<p>If the VM is built with <code>WITH_DEADLOCK_PREDICTION</code>, the deadlock 205predictor can be enabled with the <code>-Xdeadlockpredict</code> argument. 206(The output from <code>dalvikvm -help</code> will tell you if the VM was 207built appropriately -- look for <code>deadlock_prediction</code> on the 208<code>Configured with:</code> line.) 209This feature tells the VM to keep track of the order in which object 210monitor locks are acquired. If the program attempts to acquire a set 211of locks in a different order from what was seen earlier, the VM logs 212a warning and optionally throws an exception. 213 214<p>The command-line argument is set based on the 215<code>dalvik.vm.deadlock-predict</code> property. Valid values are 216<code>off</code> to disable it (default), <code>warn</code> to log the 217problem but continue executing, <code>err</code> to cause a 218<code>dalvik.system.PotentialDeadlockError</code> to be thrown from the 219<code>monitor-enter</code> instruction, and <code>abort</code> to have 220the entire VM abort. 221 222<p>You will usually want to use: 223<pre>adb shell setprop dalvik.vm.deadlock-predict err</pre> 224unless you are keeping an eye on the logs as they scroll by. 225 226<p>Please note that this feature is deadlock prediction, not deadlock 227detection -- in the current implementation, the computations are performed 228after the lock is acquired (this simplifies the code, reducing the 229overhead added to every mutex operation). You can spot a deadlock in a 230hung process by sending a <code>kill -3</code> and examining the stack 231trace written to the log. 232 233<p>This only takes monitors into account. Native mutexes and other resources 234can also be the cause of deadlocks, but will not be detected by this. 235 236 237<h2><a name="stackdump">Stack Dumps</a></h2> 238 239<p>Like other desktop VMs, when the Dalvik VM receives a SIGQUIT 240(Ctrl-\ or <code>kill -3</code>), it dumps stack traces for all threads. 241By default this goes to the Android log, but it can also be written to a file. 242 243<p>The <code>dalvik.vm.stack-trace-file</code> property allows you to 244specify the name of the file where the thread stack traces will be written. 245The file will be created (world writable) if it doesn't exist, and the 246new information will be appended to the end of the file. The filename 247is passed into the VM via the <code>-Xstacktracefile</code> argument. 248 249<p>For example: 250<pre>adb shell setprop dalvik.vm.stack-trace-file /tmp/stack-traces.txt</pre> 251 252<p>If the property is not defined, the VM will write the stack traces to 253the Android log when the signal arrives. 254 255 256<h2><a name="dexcheck">DEX File Checksums</a></h2> 257 258<p>For performance reasons, the checksum on "optimized" DEX files is 259ignored. This is usually safe, because the files are generated on the 260device, and have access permissions that prevent modification. 261 262<p>If the storage on a device becomes unreliable, however, data corruption 263can occur. This usually manifests itself as a repeatable virtual machine 264crash. To speed diagnosis of such failures, the VM provides the 265<code>-Xcheckdexsum</code> argument. When set, the checksums on all DEX 266files are verified before the contents are used. 267 268<p>The application framework will provide this argument during VM 269creation if the <code>dalvik.vm.check-dex-sum</code> property is enabled. 270 271<p>To enable extended DEX checksum verification: 272<pre>adb shell setprop dalvik.vm.check-dex-sum true</pre> 273 274<p>Incorrect checksums will prevent the DEX data from being used, and will 275cause errors to be written to the log file. If a device has a history of 276problems it may be useful to add the property to 277<code>/data/local.prop</code>. 278 279<p>Note also that the 280<code>dexdump</code> tool always verifies DEX checksums, and can be used 281to check for corruption in a large set of files. 282 283 284<address>Copyright © 2008 The Android Open Source Project</address> 285 286</body></html> 287