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