<h1>Controlling the Embedded VM</h1>
<ul>
- <li><a href="#overview">Overview</a>
+ <li><a href="#introduction">Introduction</a> (read this first!)
<li><a href="#checkjni">Extended JNI Checks</a>
<li><a href="#assertions">Assertions</a>
<li><a href="#verifier">Bytecode Verification and Optimization</a>
<li><a href="#execmode">Execution Mode</a>
- <li><a href="#dp">Deadlock Prediction</a>
<li><a href="#stackdump">Stack Dumps</a>
<li><a href="#dexcheck">DEX File Checksums</a>
+ <li><a href="#general">General Flags</a>
</ul>
-<h2><a name="overview">Overview</a></h2>
+<h2><a name="introduction">Introduction (read this first!)</a></h2>
<p>The Dalvik VM supports a variety of command-line arguments
(use <code>adb shell dalvikvm -help</code> to get a summary), but
issuing a shell command on the device like this:
<pre>adb shell setprop <name> <value></pre>
-<p>The Android runtime must be restarted before the changes will take
-effect (<code>adb shell stop; adb shell start</code>). This is because the
+<p><strong>The Android runtime must be restarted before the changes will take
+effect</strong> (<code>adb shell stop; adb shell start</code>). This is because the
settings are processed in the "zygote" process, which starts early and stays
around "forever".
-<p>You could also add a line to <code>/data/local.prop</code> that looks like:
+<p>You may not be able to set <code>dalvik.*</code> properties or restart
+the system as an unprivileged user. You can use
+<code>adb root</code> or run the <code>su</code> command from the device
+shell on "userdebug" builds to become root first. When in doubt,
+<pre>adb shell getprop <name></pre>
+will tell you if the <code>setprop</code> took.
+
+<p>If you don't want the property to evaporate when the device reboots,
+add a line to <code>/data/local.prop</code> that looks like:
<pre><name> = <value></pre>
-<p>Such changes will survive reboots, but will be removed by anything
-that wipes the data partition. (Hint: create a <code>local.prop</code>
-on your workstation, then <code>adb push local.prop /data</code> .)
+<p>Such changes will survive reboots, but will be lost if the data
+partition is wiped. (Hint: create a <code>local.prop</code>
+on your workstation, then <code>adb push local.prop /data</code>. Or,
+use one-liners like
+<code>adb shell "echo name = value >> /data/local.prop"</code> -- note
+the quotes are important.)
<h2><a name="checkjni">Extended JNI Checks</a></h2>
<p>You can also pass JNI-checking options into the VM through a system
property. The value set for <code>dalvik.vm.jniopts</code> will
-be passed in as the <code>-Xjniopts</code> argument.
-
-<p>For more information about JNI checks, see
-<a href="jni-tips.html">JNI Tips</a>.
+be passed in as the <code>-Xjniopts</code> argument. For example:
+<pre>adb shell setprop dalvik.vm.jniopts forcecopy</pre>
<h2><a name="assertions">Assertions</a></h2>
run on a broad range of platforms. The "debug" interpreter is a variant
of "portable" that includes support for profiling and single-stepping.
-<p>The VM allows you to choose between "fast" and "portable" with an
+<p>The VM may also support just-in-time compilation. While not strictly
+a different interpreter, the JIT compiler may be enabled or disabled
+with the same flag. (Check the output of <code>dalvikvm -help</code> to
+see if JIT compilation is enabled in your VM.)
+
+<p>The VM allows you to choose between "fast", "portable", and "jit" with an
extended form of the <code>-Xint</code> argument. The value of this
argument can be set through the <code>dalvik.vm.execution-mode</code>
system property.
is substantially slower, something to keep in mind when evaluating
profiling data.)
-
-<h2><a name="dp">Deadlock Prediction</a></h2>
-
-<p>If the VM is built with <code>WITH_DEADLOCK_PREDICTION</code>, the deadlock
-predictor can be enabled with the <code>-Xdeadlockpredict</code> argument.
-(The output from <code>dalvikvm -help</code> will tell you if the VM was
-built appropriately -- look for <code>deadlock_prediction</code> on the
-<code>Configured with:</code> line.)
-This feature tells the VM to keep track of the order in which object
-monitor locks are acquired. If the program attempts to acquire a set
-of locks in a different order from what was seen earlier, the VM logs
-a warning and optionally throws an exception.
-
-<p>The command-line argument is set based on the
-<code>dalvik.vm.deadlock-predict</code> property. Valid values are
-<code>off</code> to disable it (default), <code>warn</code> to log the
-problem but continue executing, <code>err</code> to cause a
-<code>dalvik.system.PotentialDeadlockError</code> to be thrown from the
-<code>monitor-enter</code> instruction, and <code>abort</code> to have
-the entire VM abort.
-
-<p>You will usually want to use:
-<pre>adb shell setprop dalvik.vm.deadlock-predict err</pre>
-unless you are keeping an eye on the logs as they scroll by.
-
-<p>Please note that this feature is deadlock prediction, not deadlock
-detection -- in the current implementation, the computations are performed
-after the lock is acquired (this simplifies the code, reducing the
-overhead added to every mutex operation). You can spot a deadlock in a
-hung process by sending a <code>kill -3</code> and examining the stack
-trace written to the log.
-
-<p>This only takes monitors into account. Native mutexes and other resources
-can also be the cause of deadlocks, but will not be detected by this.
+<p>The JIT compiler can be disabled on a per-application basis by adding
+<code>android:vmSafeMode="true"</code> in the <code>application</code>
+tag in <code>AndroidManifest.xml</code>. This can be useful if you
+suspect that JIT compilation is causing your application to behave
+incorrectly.
<h2><a name="stackdump">Stack Dumps</a></h2>
to check for corruption in a large set of files.
+<h2><a name="general">General Flags</a></h2>
+
+<p>In the "Gingerbread" release, a general mechanism for passing flags to
+the VM was introduced:
+
+<pre>adb shell setprop dalvik.vm.extra-opts "flag1 flag2 ... flagN"</pre>
+
+<p>The flags are separated by spaces. You can specify as many as you want
+so long as they all fit within the system property value length limit
+(currently 92 characters).
+
+<p>The extra-opts flags will be added at the end of the command line,
+which means they will override earlier settings. This can be used, for
+example, to experiment with different values for <code>-Xmx</code> even
+though the Android framework is setting it explicitly.
+
<address>Copyright © 2008 The Android Open Source Project</address>
</body></html>