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