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