docs/embedded-vm-control.html

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