AI 144469: Added test for dalvik.vm.check-dex-sum property.

  Enables -Xcheckdexsum argument, which causes the VM to test checksums
  when loading optimized DEX files.
  BUG=1749836

Automated import of CL 144469

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/embedded-vm-control.html b/docs/embedded-vm-control.html
index f90f0e596..28b19f63b 100644
--- a/docs/embedded-vm-control.html
+++ b/docs/embedded-vm-control.html
@@ -15,6 +15,7 @@
     <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>
 </ul>
 
 <h2><a name="overview">Overview</a></h2>
@@ -235,6 +236,35 @@ is passed into the VM via the <code>-Xstacktracefile</code> argument.
 <p>If the property is not defined, the VM will write the stack traces to
 the Android log when the signal arrives.
 
+
+<h2><a name="dexcheck">DEX File Checksums</a></h2>
+
+<p>For performance reasons, the checksum on "optimized" DEX files is
+ignored.  This is usually safe, because the files are generated on the
+device, and have access permissions that prevent modification.
+
+<p>If the storage on a device becomes unreliable, however, data corruption
+can occur.  This usually manifests itself as a repeatable virtual machine
+crash.  To speed diagnosis of such failures, the VM provides the
+<code>-Xcheckdexsum</code> argument.  When set, the checksums on all DEX
+files are verified before the contents are used.
+
+<p>The application framework will provide this argument during VM
+creation if the <code>dalvik.vm.check-dex-sum</code> property is enabled.
+
+<p>To enable extended DEX checksum verification:
+<pre>adb shell setprop dalvik.vm.check-dex-sum true</pre>
+
+<p>Incorrect checksums will prevent the DEX data from being used, and will
+cause errors to be written to the log file.  If a device has a history of
+problems it may be useful to add the property to
+<code>/data/local.prop</code>.
+
+<p>Note also that the
+<code>dexdump</code> tool always verifies DEX checksums, and can be used
+to check for corruption in a large set of files.
+
+
 <address>Copyright &copy; 2008 The Android Open Source Project</address>
 
 </body></html>