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