Various minor changes to Dalvik documentation.
Some updates for Eclair, some minor fixes.
diff --git a/docs/embedded-vm-control.html b/docs/embedded-vm-control.html
index 28b19f6..0b279e8 100644
--- a/docs/embedded-vm-control.html
+++ b/docs/embedded-vm-control.html
@@ -36,12 +36,22 @@
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 this 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>
@@ -73,7 +83,8 @@
<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.
+be passed in as the <code>-Xjniopts</code> argument. For example:
+<pre>adb shell setprop dalvik.vm.jniopts forcecopy</pre>
<p>For more information about JNI checks, see
<a href="jni-tips.html">JNI Tips</a>.
@@ -159,7 +170,12 @@
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.
diff --git a/docs/heap-profiling.html b/docs/heap-profiling.html
index 0a6ce5c..e36b606 100644
--- a/docs/heap-profiling.html
+++ b/docs/heap-profiling.html
@@ -95,11 +95,10 @@
</p><p>
You now have the hprof dump in <code>dump.hprof</code>.
-
</p><p>
-<h3>"Cupcake" release (1.5)</h3>
+<h3>Android 1.5 ("Cupcake")</h3>
<p>
Some steps were taken to make this simpler. Notably, the two output
files are now combined for you, and a new API call was added that allows
@@ -142,6 +141,21 @@
device without root access.
+
+<h3>Android 1.6 ("Donut")</h3>
+<p>
+In 1.6, features were added that allow DDMS to request a heap dump on
+demand, and automatically pull the result across. Select your application
+and click the "dump HPROF file" button.
+</p><p>
+However, 1.6 also introduced the <code>WRITE_EXTERNAL_STORAGE</code>
+permission, which is required to write data to the SD card. To use
+the DDMS feature, which always writes files to the SD card,
+you must have a card inserted and the permission enabled in your application.
+</p><p>
+Otherwise, things are the same as they were in 1.5.
+
+
<h2>Examining the data</h2>
<p>
The data file format was augmented slightly from the common hprof format,
diff --git a/docs/hello-world.html b/docs/hello-world.html
index 690c213..dbbaea6 100644
--- a/docs/hello-world.html
+++ b/docs/hello-world.html
@@ -42,6 +42,53 @@
+<h2>Using a debugger</h2>
+
+<p>
+You can debug stand-alone applications with any JDWP-compliant debugger.
+There are two basic approaches.
+</p><p>
+The first way is to connect directly through TCP. Add, to the "dalvikvm"
+invocation line above, an argument like:
+</p><p>
+<code> -agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=y</code>
+</p><p>
+This tells the VM to wait for a debugger to connect to it on TCP port 8000.
+You need to tell adb to forward local port 8000 to device port 8000:
+</p><p>
+<code>% <font color="green">adb forward tcp:8000 tcp:8000</font></code>
+</p><p>
+and then connect to it with your favorite debugger (using <code>jdb</code>
+as an example here):
+</p><p>
+<code>% <font color="green">jdb -attach localhost:8000</font></code>
+</p><p>
+When the debugger attaches, the VM will be in a suspended state. You can
+set breakpoints and then tell it to continue.
+
+
+</p><p>
+You can also connect through DDMS, like you would for an Android application.
+Add, to the "dalvikvm" command line:
+</p><p>
+<code> -agentlib:jdwp=transport=dt_android_adb,suspend=y,server=y</code>
+</p><p>
+Note the <code>transport</code> has changed, and you no longer need to
+specify a TCP port number. When your application starts, it will appear
+in DDMS, with "?" as the application name. Select it in DDMS, and connect
+to it as usual, e.g.:
+</p><p>
+<code>% <font color="green">jdb -attach localhost:8700</font></code>
+</p><p>
+Because command-line applications don't include the client-side
+DDM setup, features like thread monitoring and allocation tracking will not
+be available in DDMS. It's strictly a debugger pass-through in this mode.
+</p><p>
+See <a href="debugger.html">Dalvik Debugger Support</a> for more information
+about using debuggers with Dalvik.
+
+
+
<h2>Working with the desktop build</h2>
<!-- largely lifted from
diff --git a/docs/jni-tips.html b/docs/jni-tips.html
index 881f534..30207bf 100644
--- a/docs/jni-tips.html
+++ b/docs/jni-tips.html
@@ -169,6 +169,13 @@
you must use the <code>IsSameObject</code> function.</strong> Never compare
references with "==" in native code.
</p><p>
+One consequence of this is that you
+<strong>must not assume object references are constant</strong>
+in native code. The 32-bit value representing an object may be different
+from one invocation of a method to the next, and it's possible that two
+different objects could have the same 32-bit value at different times. Do
+not use jobjects as keys.
+</p><p>
Programmers are required to "not excessively allocate" local references. In practical terms this means
that if you're creating large numbers of local references, perhaps while running through an array of
Objects, you should free them manually with
@@ -312,10 +319,10 @@
</p><p>
This accomplishes the same thing, with several advantages:
<ul>
- <li>Requires one JNI call instead of 3, reducing overhead.
+ <li>Requires one JNI call instead of 2, reducing overhead.
<li>Doesn't require pinning or extra data copies.
- <li>Reduces the risk of programmer error -- no need to match up
- <code>Get</code> and <code>Release</code> calls.
+ <li>Reduces the risk of programmer error -- no risk of forgetting
+ to call <code>Release</code> after something fails.
</ul>
</p><p>
Similarly, you can use the <code>Set<Type>ArrayRegion</code> call
@@ -384,7 +391,7 @@
an extended series of checks before calling the standard implementation.
</p><p>
-Some things that may be verified:
+Some things that may be checked:
</p><p>
</p>
<ul>
@@ -427,6 +434,7 @@
are over-allocated and surrounded with a guard pattern to help identify
code writing outside the buffer, and the contents are erased before the
storage is freed to trip up code that uses the data after calling Release.
+This will have a noticeable performance impact on some applications.
<dt>warnonly
<dd>By default, JNI "warnings" cause the VM to abort. With this flag
it continues on.
diff --git a/docs/opcodes/opcode-04-move-wide.html b/docs/opcodes/opcode-04-move-wide.html
index 42202be..e043be9 100644
--- a/docs/opcodes/opcode-04-move-wide.html
+++ b/docs/opcodes/opcode-04-move-wide.html
@@ -9,7 +9,7 @@
<body>
-<h1>move</h1>
+<h1>move-wide</h1>
<h2>Purpose</h2>
diff --git a/docs/verifier.html b/docs/verifier.html
index 84d513c..022923b 100644
--- a/docs/verifier.html
+++ b/docs/verifier.html
@@ -146,7 +146,7 @@
</ol>
<p>
-In early versions of Dalvik (as shipped with Android 1.0/1.5), the verifier
+In early versions of Dalvik (as found in Android 1.6 and earlier), the verifier
simply regarded all problems as immediately fatal. This generally worked,
but in some cases the VM was rejecting classes because of bits of code
that were never used. The VerifyError itself was sometimes difficult to
