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 could also add a line to <code>/data/local.prop</code> that looks like:
  40 <pre>&lt;name&gt; = &lt;value&gt;</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
 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
 268 <address>Copyright &copy; 2008 The Android Open Source Project</address>
 269
 270 </body></html>