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