Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / dalvik / refs/heads/int/p/fp2 / . / docs / embedded-vm-control.html
blob: 5c444de702be6e2f8be2f6a400337f0b141025b0 [file] [log] [blame]
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]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>
Andy McFaddenf20c92f2010-02-01 14:39:21 -0800[diff] [blame]11 <li><a href="#introduction">Introduction</a> (read this first!)
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]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>
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]16 <li><a href="#stackdump">Stack Dumps</a>
Andy McFadden0af0a8c2009-04-03 11:09:44 -0700[diff] [blame]17 <li><a href="#dexcheck">DEX File Checksums</a>
Andy McFaddend8b5bd12010-07-15 10:30:23 -0700[diff] [blame]18 <li><a href="#general">General Flags</a>
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]19</ul>
20
Andy McFaddenf20c92f2010-02-01 14:39:21 -0800[diff] [blame]21<h2><a name="introduction">Introduction (read this first!)</a></h2>
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]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
25it's not possible to pass arbitrary arguments through the
26Android application runtime. It is, however, possible to affect the
27VM behavior through certain system properties.
28
29<p>For all of the features described below, you would set the system property
30with <code>setprop</code>,
31issuing a shell command on the device like this:
32<pre>adb shell setprop &lt;name&gt; &lt;value&gt;</pre>
33
Andy McFaddenf20c92f2010-02-01 14:39:21 -0800[diff] [blame]34<p><strong>The Android runtime must be restarted before the changes will take
35effect</strong> (<code>adb shell stop; adb shell start</code>). This is because the
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]36settings are processed in the "zygote" process, which starts early and stays
37around "forever".
38
Andy McFaddenf20c92f2010-02-01 14:39:21 -0800[diff] [blame]39<p>You may not be able to set <code>dalvik.*</code> properties or restart
40the system as an unprivileged user. You can use
Andy McFaddenc7659ec2009-09-18 16:14:41 -0700[diff] [blame]41<code>adb root</code> or run the <code>su</code> command from the device
42shell on "userdebug" builds to become root first. When in doubt,
43<pre>adb shell getprop &lt;name&gt;</pre>
44will tell you if the <code>setprop</code> took.
45
46<p>If you don't want the property to evaporate when the device reboots,
47add a line to <code>/data/local.prop</code> that looks like:
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]48<pre>&lt;name&gt; = &lt;value&gt;</pre>
49
Andy McFaddenc7659ec2009-09-18 16:14:41 -0700[diff] [blame]50<p>Such changes will survive reboots, but will be lost if the data
51partition is wiped. (Hint: create a <code>local.prop</code>
Andy McFaddenf20c92f2010-02-01 14:39:21 -0800[diff] [blame]52on your workstation, then <code>adb push local.prop /data</code>. Or,
Andy McFaddenc7659ec2009-09-18 16:14:41 -0700[diff] [blame]53use one-liners like
54<code>adb shell "echo name = value &gt;&gt; /data/local.prop"</code> -- note
55the quotes are important.)
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]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
61Java programming language
62interact with native (C/C++) code. The extended JNI checks will cause
63the system to run more slowly, but they can spot a variety of nasty bugs
64before they have a chance to cause problems.
65
66<p>There are two system properties that affect this feature, which is
67enabled with the <code>-Xcheck:jni</code> command-line argument. The
68first is <code>ro.kernel.android.checkjni</code>. This is set by the
69Android build system for development builds. (It may also be set by
70the Android emulator unless the <code>-nojni</code> flag is provided on the
71emulator command line.) Because this is an "ro." property, the value cannot
72be changed once the device has started.
73
74<p>To allow toggling of the CheckJNI flag, a second
75property, <code>dalvik.vm.checkjni</code>, is also checked. The value
76of 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>
79is set to <code>false</code>, the <code>-Xcheck:jni</code> flag is
80not 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
86property. The value set for <code>dalvik.vm.jniopts</code> will
Andy McFaddenc7659ec2009-09-18 16:14:41 -0700[diff] [blame]87be passed in as the <code>-Xjniopts</code> argument. For example:
88<pre>adb shell setprop dalvik.vm.jniopts forcecopy</pre>
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]89
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]90
91<h2><a name="assertions">Assertions</a></h2>
92
93<p>Dalvik VM supports the Java programming language "assert" statement.
94By default they are off, but the <code>dalvik.vm.enableassertions</code>
95property 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
98can provide a class name, a package name (followed by "..."), or the
99special value "all".
100
101<p>For example, this:
102<pre>adb shell setprop dalvik.vm.enableassertions all</pre>
103enables assertions in all non-system classes.
104
105<p>The system property is much more limited than the full command line.
106It is not possible to specify more than one <code>-ea</code> entry, and there
107is no way to specify a <code>-da</code> entry. There is presently no
108equivalent 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
114class load overhead, and performs a series of optimizations to improve
115runtime performance. Both of these are done by the <code>dexopt</code>
116command, either in the build system or by the installer. On a development
117device, <code>dexopt</code> may be run the first time a DEX file is used
118and whenever it or one of its dependencies is updated ("just-in-time"
119optimization and verification).
120
121<p>There are two command-line flags that control the just-in-time
122verification and optimization,
123<code>-Xverify</code> and <code>-Xdexopt</code>. The Android framework
124configures these based on the <code>dalvik.vm.dexopt-flags</code>
125property.
126
127<p>If you set:
128<pre>adb shell setprop dalvik.vm.dexopt-flags v=a,o=v</pre>
129then the framework will pass <code>-Xverify:all -Xdexopt:verified</code>
130to the VM. This enables verification, and only optimizes classes that
131successfully 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>
133to have the framework pass <code>-Xverify:none -Xdexopt:verified</code>
134to disable verification. (We could pass in <code>-Xdexopt:all</code> to
135allow optimization, but that wouldn't necessarily optimize more of the
136code, since classes that fail verification may well be skipped by the
137optimizer 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
141take significantly longer, because the verification process is fairly slow.
142Once the verified and optimized DEX files have been prepared, verification
143incurs no additional overhead except when loading classes that failed
144to pre-verify.
145
146<p>If your DEX files are processed with verification disabled, and you
147later turn the verifier on, application loading will be noticeably
148slower (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
151this property changes. You can do this with:
152<pre>adb shell "rm /data/dalvik-cache/*"</pre>
153This removes the cached versions of the DEX files. Remember to
154stop 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
158superceded 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
164interpreter cores. These are referred to as "fast", "portable", and
165"debug". The "fast" interpreter is optimized for the current
166platform, and might consist of hand-optimized assembly routines. In
167constrast, the "portable" interpreter is written in C and expected to
168run on a broad range of platforms. The "debug" interpreter is a variant
169of "portable" that includes support for profiling and single-stepping.
170
Andy McFaddenc7659ec2009-09-18 16:14:41 -0700[diff] [blame]171<p>The VM may also support just-in-time compilation. While not strictly
172a different interpreter, the JIT compiler may be enabled or disabled
173with the same flag. (Check the output of <code>dalvikvm -help</code> to
174see if JIT compilation is enabled in your VM.)
175
176<p>The VM allows you to choose between "fast", "portable", and "jit" with an
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]177extended form of the <code>-Xint</code> argument. The value of this
178argument can be set through the <code>dalvik.vm.execution-mode</code>
179system property.
180
181<p>To select the "portable" interpreter, you would use:
182<pre>adb shell setprop dalvik.vm.execution-mode int:portable</pre>
183If the property is not specified, the most appropriate interpreter
184will be selected automatically. At some point this mechanism may allow
185selection of other modes, such as JIT compilation.
186
187<p>Not all platforms have an optimized implementation. In such cases,
188the "fast" interpreter is generated as a series of C stubs, and the
189result will be slower than the
190"portable" version. (When we have optimized versions for all popular
191architectures the naming convention will be more accurate.)
192
193<p>If profiling is enabled or a debugger is attached, the VM
194switches to the "debug" interpreter. When profiling ends or the debugger
195disconnects, the original interpreter is resumed. (The "debug" interpreter
196is substantially slower, something to keep in mind when evaluating
197profiling data.)
198
Andy McFadden54df4ec2010-04-05 10:07:30 -0700[diff] [blame]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>
201tag in <code>AndroidManifest.xml</code>. This can be useful if you
202suspect that JIT compilation is causing your application to behave
203incorrectly.
204
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]205
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]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.
210By 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
213specify the name of the file where the thread stack traces will be written.
214The file will be created (world writable) if it doesn't exist, and the
215new information will be appended to the end of the file. The filename
216is 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
222the Android log when the signal arrives.
223
Andy McFadden0af0a8c2009-04-03 11:09:44 -0700[diff] [blame]224
225<h2><a name="dexcheck">DEX File Checksums</a></h2>
226
227<p>For performance reasons, the checksum on "optimized" DEX files is
228ignored. This is usually safe, because the files are generated on the
229device, and have access permissions that prevent modification.
230
231<p>If the storage on a device becomes unreliable, however, data corruption
232can occur. This usually manifests itself as a repeatable virtual machine
233crash. To speed diagnosis of such failures, the VM provides the
234<code>-Xcheckdexsum</code> argument. When set, the checksums on all DEX
235files are verified before the contents are used.
236
237<p>The application framework will provide this argument during VM
238creation 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
244cause errors to be written to the log file. If a device has a history of
245problems it may be useful to add the property to
246<code>/data/local.prop</code>.
247
Aart Bik1a650522015-07-08 21:20:41 +0000[diff] [blame]248<p>Note also that the
249<code>dexdump</code> tool always verifies DEX checksums, and can be used
250to check for corruption in a large set of files.
251
Andy McFadden0af0a8c2009-04-03 11:09:44 -0700[diff] [blame]252
Andy McFaddend8b5bd12010-07-15 10:30:23 -0700[diff] [blame]253<h2><a name="general">General Flags</a></h2>
254
Andy McFadden802ffdf2010-09-15 11:22:26 -0700[diff] [blame]255<p>In the "Gingerbread" release, a general mechanism for passing flags to
Andy McFaddend8b5bd12010-07-15 10:30:23 -0700[diff] [blame]256the 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
261so 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,
265which means they will override earlier settings. This can be used, for
266example, to experiment with different values for <code>-Xmx</code> even
267though the Android framework is setting it explicitly.
268
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame]269<address>Copyright &copy; 2008 The Android Open Source Project</address>
270
271</body></html>