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