1*055d4590SKeyi Gui<html> 2*055d4590SKeyi Gui<head> 3*055d4590SKeyi Gui <title>Controlling the Embedded VM</title> 4*055d4590SKeyi Gui <link rel=stylesheet href="android.css"> 5*055d4590SKeyi Gui</head> 6*055d4590SKeyi Gui 7*055d4590SKeyi Gui<body> 8*055d4590SKeyi Gui<h1>Controlling the Embedded VM</h1> 9*055d4590SKeyi Gui 10*055d4590SKeyi Gui<ul> 11*055d4590SKeyi Gui <li><a href="#introduction">Introduction</a> (read this first!) 12*055d4590SKeyi Gui <li><a href="#checkjni">Extended JNI Checks</a> 13*055d4590SKeyi Gui <li><a href="#assertions">Assertions</a> 14*055d4590SKeyi Gui <li><a href="#verifier">Bytecode Verification and Optimization</a> 15*055d4590SKeyi Gui <li><a href="#execmode">Execution Mode</a> 16*055d4590SKeyi Gui <li><a href="#stackdump">Stack Dumps</a> 17*055d4590SKeyi Gui <li><a href="#dexcheck">DEX File Checksums</a> 18*055d4590SKeyi Gui <li><a href="#general">General Flags</a> 19*055d4590SKeyi Gui</ul> 20*055d4590SKeyi Gui 21*055d4590SKeyi Gui<h2><a name="introduction">Introduction (read this first!)</a></h2> 22*055d4590SKeyi Gui 23*055d4590SKeyi Gui<p>The Dalvik VM supports a variety of command-line arguments 24*055d4590SKeyi Gui(use <code>adb shell dalvikvm -help</code> to get a summary), but 25*055d4590SKeyi Guiit's not possible to pass arbitrary arguments through the 26*055d4590SKeyi GuiAndroid application runtime. It is, however, possible to affect the 27*055d4590SKeyi GuiVM behavior through certain system properties. 28*055d4590SKeyi Gui 29*055d4590SKeyi Gui<p>For all of the features described below, you would set the system property 30*055d4590SKeyi Guiwith <code>setprop</code>, 31*055d4590SKeyi Guiissuing a shell command on the device like this: 32*055d4590SKeyi Gui<pre>adb shell setprop <name> <value></pre> 33*055d4590SKeyi Gui 34*055d4590SKeyi Gui<p><strong>The Android runtime must be restarted before the changes will take 35*055d4590SKeyi Guieffect</strong> (<code>adb shell stop; adb shell start</code>). This is because the 36*055d4590SKeyi Guisettings are processed in the "zygote" process, which starts early and stays 37*055d4590SKeyi Guiaround "forever". 38*055d4590SKeyi Gui 39*055d4590SKeyi Gui<p>You may not be able to set <code>dalvik.*</code> properties or restart 40*055d4590SKeyi Guithe system as an unprivileged user. You can use 41*055d4590SKeyi Gui<code>adb root</code> or run the <code>su</code> command from the device 42*055d4590SKeyi Guishell on "userdebug" builds to become root first. When in doubt, 43*055d4590SKeyi Gui<pre>adb shell getprop <name></pre> 44*055d4590SKeyi Guiwill tell you if the <code>setprop</code> took. 45*055d4590SKeyi Gui 46*055d4590SKeyi Gui<p>If you don't want the property to evaporate when the device reboots, 47*055d4590SKeyi Guiadd a line to <code>/data/local.prop</code> that looks like: 48*055d4590SKeyi Gui<pre><name> = <value></pre> 49*055d4590SKeyi Gui 50*055d4590SKeyi Gui<p>Such changes will survive reboots, but will be lost if the data 51*055d4590SKeyi Guipartition is wiped. (Hint: create a <code>local.prop</code> 52*055d4590SKeyi Guion your workstation, then <code>adb push local.prop /data</code>. Or, 53*055d4590SKeyi Guiuse one-liners like 54*055d4590SKeyi Gui<code>adb shell "echo name = value >> /data/local.prop"</code> -- note 55*055d4590SKeyi Guithe quotes are important.) 56*055d4590SKeyi Gui 57*055d4590SKeyi Gui 58*055d4590SKeyi Gui<h2><a name="checkjni">Extended JNI Checks</a></h2> 59*055d4590SKeyi Gui 60*055d4590SKeyi Gui<p>JNI, the Java Native Interface, provides a way for code written in the 61*055d4590SKeyi GuiJava programming language 62*055d4590SKeyi Guiinteract with native (C/C++) code. The extended JNI checks will cause 63*055d4590SKeyi Guithe system to run more slowly, but they can spot a variety of nasty bugs 64*055d4590SKeyi Guibefore they have a chance to cause problems. 65*055d4590SKeyi Gui 66*055d4590SKeyi Gui<p>There are two system properties that affect this feature, which is 67*055d4590SKeyi Guienabled with the <code>-Xcheck:jni</code> command-line argument. The 68*055d4590SKeyi Guifirst is <code>ro.kernel.android.checkjni</code>. This is set by the 69*055d4590SKeyi GuiAndroid build system for development builds. (It may also be set by 70*055d4590SKeyi Guithe Android emulator unless the <code>-nojni</code> flag is provided on the 71*055d4590SKeyi Guiemulator command line.) Because this is an "ro." property, the value cannot 72*055d4590SKeyi Guibe changed once the device has started. 73*055d4590SKeyi Gui 74*055d4590SKeyi Gui<p>To allow toggling of the CheckJNI flag, a second 75*055d4590SKeyi Guiproperty, <code>dalvik.vm.checkjni</code>, is also checked. The value 76*055d4590SKeyi Guiof this overrides the value from <code>ro.kernel.android.checkjni</code>. 77*055d4590SKeyi Gui 78*055d4590SKeyi Gui<p>If neither property is defined, or <code>dalvik.vm.checkjni</code> 79*055d4590SKeyi Guiis set to <code>false</code>, the <code>-Xcheck:jni</code> flag is 80*055d4590SKeyi Guinot passed in, and JNI checks will be disabled. 81*055d4590SKeyi Gui 82*055d4590SKeyi Gui<p>To enable JNI checking: 83*055d4590SKeyi Gui<pre>adb shell setprop dalvik.vm.checkjni true</pre> 84*055d4590SKeyi Gui 85*055d4590SKeyi Gui<p>You can also pass JNI-checking options into the VM through a system 86*055d4590SKeyi Guiproperty. The value set for <code>dalvik.vm.jniopts</code> will 87*055d4590SKeyi Guibe passed in as the <code>-Xjniopts</code> argument. For example: 88*055d4590SKeyi Gui<pre>adb shell setprop dalvik.vm.jniopts forcecopy</pre> 89*055d4590SKeyi Gui 90*055d4590SKeyi Gui 91*055d4590SKeyi Gui<h2><a name="assertions">Assertions</a></h2> 92*055d4590SKeyi Gui 93*055d4590SKeyi Gui<p>Dalvik VM supports the Java programming language "assert" statement. 94*055d4590SKeyi GuiBy default they are off, but the <code>dalvik.vm.enableassertions</code> 95*055d4590SKeyi Guiproperty provides a way to set the value for a <code>-ea</code> argument. 96*055d4590SKeyi Gui 97*055d4590SKeyi Gui<p>The argument behaves the same as it does in other desktop VMs. You 98*055d4590SKeyi Guican provide a class name, a package name (followed by "..."), or the 99*055d4590SKeyi Guispecial value "all". 100*055d4590SKeyi Gui 101*055d4590SKeyi Gui<p>For example, this: 102*055d4590SKeyi Gui<pre>adb shell setprop dalvik.vm.enableassertions all</pre> 103*055d4590SKeyi Guienables assertions in all non-system classes. 104*055d4590SKeyi Gui 105*055d4590SKeyi Gui<p>The system property is much more limited than the full command line. 106*055d4590SKeyi GuiIt is not possible to specify more than one <code>-ea</code> entry, and there 107*055d4590SKeyi Guiis no way to specify a <code>-da</code> entry. There is presently no 108*055d4590SKeyi Guiequivalent for <code>-esa</code>/<code>-dsa</code>. 109*055d4590SKeyi Gui 110*055d4590SKeyi Gui 111*055d4590SKeyi Gui<h2><a name="verifier">Bytecode Verification and Optimization</a></h2> 112*055d4590SKeyi Gui 113*055d4590SKeyi Gui<p>The system tries to pre-verify all classes in a DEX file to reduce 114*055d4590SKeyi Guiclass load overhead, and performs a series of optimizations to improve 115*055d4590SKeyi Guiruntime performance. Both of these are done by the <code>dexopt</code> 116*055d4590SKeyi Guicommand, either in the build system or by the installer. On a development 117*055d4590SKeyi Guidevice, <code>dexopt</code> may be run the first time a DEX file is used 118*055d4590SKeyi Guiand whenever it or one of its dependencies is updated ("just-in-time" 119*055d4590SKeyi Guioptimization and verification). 120*055d4590SKeyi Gui 121*055d4590SKeyi Gui<p>There are two command-line flags that control the just-in-time 122*055d4590SKeyi Guiverification and optimization, 123*055d4590SKeyi Gui<code>-Xverify</code> and <code>-Xdexopt</code>. The Android framework 124*055d4590SKeyi Guiconfigures these based on the <code>dalvik.vm.dexopt-flags</code> 125*055d4590SKeyi Guiproperty. 126*055d4590SKeyi Gui 127*055d4590SKeyi Gui<p>If you set: 128*055d4590SKeyi Gui<pre>adb shell setprop dalvik.vm.dexopt-flags v=a,o=v</pre> 129*055d4590SKeyi Guithen the framework will pass <code>-Xverify:all -Xdexopt:verified</code> 130*055d4590SKeyi Guito the VM. This enables verification, and only optimizes classes that 131*055d4590SKeyi Guisuccessfully verified. This is the safest setting, and is the default. 132*055d4590SKeyi Gui<p>You could also set <code>dalvik.vm.dexopt-flags</code> to <code>v=n</code> 133*055d4590SKeyi Guito have the framework pass <code>-Xverify:none -Xdexopt:verified</code> 134*055d4590SKeyi Guito disable verification. (We could pass in <code>-Xdexopt:all</code> to 135*055d4590SKeyi Guiallow optimization, but that wouldn't necessarily optimize more of the 136*055d4590SKeyi Guicode, since classes that fail verification may well be skipped by the 137*055d4590SKeyi Guioptimizer for the same reasons.) Classes will not be verified by 138*055d4590SKeyi Gui<code>dexopt</code>, and unverified code will be loaded and executed. 139*055d4590SKeyi Gui 140*055d4590SKeyi Gui<p>Enabling verification will make the <code>dexopt</code> command 141*055d4590SKeyi Guitake significantly longer, because the verification process is fairly slow. 142*055d4590SKeyi GuiOnce the verified and optimized DEX files have been prepared, verification 143*055d4590SKeyi Guiincurs no additional overhead except when loading classes that failed 144*055d4590SKeyi Guito pre-verify. 145*055d4590SKeyi Gui 146*055d4590SKeyi Gui<p>If your DEX files are processed with verification disabled, and you 147*055d4590SKeyi Guilater turn the verifier on, application loading will be noticeably 148*055d4590SKeyi Guislower (perhaps 40% or more) as classes are verified on first use. 149*055d4590SKeyi Gui 150*055d4590SKeyi Gui<p>For best results you should force a re-dexopt of all DEX files when 151*055d4590SKeyi Guithis property changes. You can do this with: 152*055d4590SKeyi Gui<pre>adb shell "rm /data/dalvik-cache/*"</pre> 153*055d4590SKeyi GuiThis removes the cached versions of the DEX files. Remember to 154*055d4590SKeyi Guistop and restart the runtime (<code>adb shell stop; adb shell start</code>). 155*055d4590SKeyi Gui 156*055d4590SKeyi Gui<p>(Previous version of the runtime supported the boolean 157*055d4590SKeyi Gui<code>dalvik.vm.verify-bytecode</code> property, but that has been 158*055d4590SKeyi Guisuperceded by <code>dalvik.vm.dexopt-flags</code>.)</p> 159*055d4590SKeyi Gui 160*055d4590SKeyi Gui 161*055d4590SKeyi Gui<h2><a name="execmode">Execution Mode</a></h2> 162*055d4590SKeyi Gui 163*055d4590SKeyi Gui<p>The current implementation of the Dalvik VM includes three distinct 164*055d4590SKeyi Guiinterpreter cores. These are referred to as "fast", "portable", and 165*055d4590SKeyi Gui"debug". The "fast" interpreter is optimized for the current 166*055d4590SKeyi Guiplatform, and might consist of hand-optimized assembly routines. In 167*055d4590SKeyi Guiconstrast, the "portable" interpreter is written in C and expected to 168*055d4590SKeyi Guirun on a broad range of platforms. The "debug" interpreter is a variant 169*055d4590SKeyi Guiof "portable" that includes support for profiling and single-stepping. 170*055d4590SKeyi Gui 171*055d4590SKeyi Gui<p>The VM may also support just-in-time compilation. While not strictly 172*055d4590SKeyi Guia different interpreter, the JIT compiler may be enabled or disabled 173*055d4590SKeyi Guiwith the same flag. (Check the output of <code>dalvikvm -help</code> to 174*055d4590SKeyi Guisee if JIT compilation is enabled in your VM.) 175*055d4590SKeyi Gui 176*055d4590SKeyi Gui<p>The VM allows you to choose between "fast", "portable", and "jit" with an 177*055d4590SKeyi Guiextended form of the <code>-Xint</code> argument. The value of this 178*055d4590SKeyi Guiargument can be set through the <code>dalvik.vm.execution-mode</code> 179*055d4590SKeyi Guisystem property. 180*055d4590SKeyi Gui 181*055d4590SKeyi Gui<p>To select the "portable" interpreter, you would use: 182*055d4590SKeyi Gui<pre>adb shell setprop dalvik.vm.execution-mode int:portable</pre> 183*055d4590SKeyi GuiIf the property is not specified, the most appropriate interpreter 184*055d4590SKeyi Guiwill be selected automatically. At some point this mechanism may allow 185*055d4590SKeyi Guiselection of other modes, such as JIT compilation. 186*055d4590SKeyi Gui 187*055d4590SKeyi Gui<p>Not all platforms have an optimized implementation. In such cases, 188*055d4590SKeyi Guithe "fast" interpreter is generated as a series of C stubs, and the 189*055d4590SKeyi Guiresult will be slower than the 190*055d4590SKeyi Gui"portable" version. (When we have optimized versions for all popular 191*055d4590SKeyi Guiarchitectures the naming convention will be more accurate.) 192*055d4590SKeyi Gui 193*055d4590SKeyi Gui<p>If profiling is enabled or a debugger is attached, the VM 194*055d4590SKeyi Guiswitches to the "debug" interpreter. When profiling ends or the debugger 195*055d4590SKeyi Guidisconnects, the original interpreter is resumed. (The "debug" interpreter 196*055d4590SKeyi Guiis substantially slower, something to keep in mind when evaluating 197*055d4590SKeyi Guiprofiling data.) 198*055d4590SKeyi Gui 199*055d4590SKeyi Gui<p>The JIT compiler can be disabled on a per-application basis by adding 200*055d4590SKeyi Gui<code>android:vmSafeMode="true"</code> in the <code>application</code> 201*055d4590SKeyi Guitag in <code>AndroidManifest.xml</code>. This can be useful if you 202*055d4590SKeyi Guisuspect that JIT compilation is causing your application to behave 203*055d4590SKeyi Guiincorrectly. 204*055d4590SKeyi Gui 205*055d4590SKeyi Gui 206*055d4590SKeyi Gui<h2><a name="stackdump">Stack Dumps</a></h2> 207*055d4590SKeyi Gui 208*055d4590SKeyi Gui<p>Like other desktop VMs, when the Dalvik VM receives a SIGQUIT 209*055d4590SKeyi Gui(Ctrl-\ or <code>kill -3</code>), it dumps stack traces for all threads. 210*055d4590SKeyi GuiBy default this goes to the Android log, but it can also be written to a file. 211*055d4590SKeyi Gui 212*055d4590SKeyi Gui<p>The <code>dalvik.vm.stack-trace-file</code> property allows you to 213*055d4590SKeyi Guispecify the name of the file where the thread stack traces will be written. 214*055d4590SKeyi GuiThe file will be created (world writable) if it doesn't exist, and the 215*055d4590SKeyi Guinew information will be appended to the end of the file. The filename 216*055d4590SKeyi Guiis passed into the VM via the <code>-Xstacktracefile</code> argument. 217*055d4590SKeyi Gui 218*055d4590SKeyi Gui<p>For example: 219*055d4590SKeyi Gui<pre>adb shell setprop dalvik.vm.stack-trace-file /tmp/stack-traces.txt</pre> 220*055d4590SKeyi Gui 221*055d4590SKeyi Gui<p>If the property is not defined, the VM will write the stack traces to 222*055d4590SKeyi Guithe Android log when the signal arrives. 223*055d4590SKeyi Gui 224*055d4590SKeyi Gui 225*055d4590SKeyi Gui<h2><a name="dexcheck">DEX File Checksums</a></h2> 226*055d4590SKeyi Gui 227*055d4590SKeyi Gui<p>For performance reasons, the checksum on "optimized" DEX files is 228*055d4590SKeyi Guiignored. This is usually safe, because the files are generated on the 229*055d4590SKeyi Guidevice, and have access permissions that prevent modification. 230*055d4590SKeyi Gui 231*055d4590SKeyi Gui<p>If the storage on a device becomes unreliable, however, data corruption 232*055d4590SKeyi Guican occur. This usually manifests itself as a repeatable virtual machine 233*055d4590SKeyi Guicrash. To speed diagnosis of such failures, the VM provides the 234*055d4590SKeyi Gui<code>-Xcheckdexsum</code> argument. When set, the checksums on all DEX 235*055d4590SKeyi Guifiles are verified before the contents are used. 236*055d4590SKeyi Gui 237*055d4590SKeyi Gui<p>The application framework will provide this argument during VM 238*055d4590SKeyi Guicreation if the <code>dalvik.vm.check-dex-sum</code> property is enabled. 239*055d4590SKeyi Gui 240*055d4590SKeyi Gui<p>To enable extended DEX checksum verification: 241*055d4590SKeyi Gui<pre>adb shell setprop dalvik.vm.check-dex-sum true</pre> 242*055d4590SKeyi Gui 243*055d4590SKeyi Gui<p>Incorrect checksums will prevent the DEX data from being used, and will 244*055d4590SKeyi Guicause errors to be written to the log file. If a device has a history of 245*055d4590SKeyi Guiproblems it may be useful to add the property to 246*055d4590SKeyi Gui<code>/data/local.prop</code>. 247*055d4590SKeyi Gui 248*055d4590SKeyi Gui<p>Note also that the 249*055d4590SKeyi Gui<code>dexdump</code> tool always verifies DEX checksums, and can be used 250*055d4590SKeyi Guito check for corruption in a large set of files. 251*055d4590SKeyi Gui 252*055d4590SKeyi Gui 253*055d4590SKeyi Gui<h2><a name="general">General Flags</a></h2> 254*055d4590SKeyi Gui 255*055d4590SKeyi Gui<p>In the "Gingerbread" release, a general mechanism for passing flags to 256*055d4590SKeyi Guithe VM was introduced: 257*055d4590SKeyi Gui 258*055d4590SKeyi Gui<pre>adb shell setprop dalvik.vm.extra-opts "flag1 flag2 ... flagN"</pre> 259*055d4590SKeyi Gui 260*055d4590SKeyi Gui<p>The flags are separated by spaces. You can specify as many as you want 261*055d4590SKeyi Guiso long as they all fit within the system property value length limit 262*055d4590SKeyi Gui(currently 92 characters). 263*055d4590SKeyi Gui 264*055d4590SKeyi Gui<p>The extra-opts flags will be added at the end of the command line, 265*055d4590SKeyi Guiwhich means they will override earlier settings. This can be used, for 266*055d4590SKeyi Guiexample, to experiment with different values for <code>-Xmx</code> even 267*055d4590SKeyi Guithough the Android framework is setting it explicitly. 268*055d4590SKeyi Gui 269*055d4590SKeyi Gui<address>Copyright © 2008 The Android Open Source Project</address> 270*055d4590SKeyi Gui 271*055d4590SKeyi Gui</body></html> 272