Docs: Adding ART references to Dalvik
Bug: 16631982
Change-Id: I6ee6c31349daf56f34d123322c67ea96722c4db0
diff --git a/src/devices/tech/dalvik/art.jd b/src/devices/tech/dalvik/art.jd
deleted file mode 100644
index 33a82ed..0000000
--- a/src/devices/tech/dalvik/art.jd
+++ /dev/null
@@ -1,244 +0,0 @@
-page.title=Introducing ART
-@jd:body
-
-<!--
- Copyright 2013 The Android Open Source Project
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-
-<div id="qv-wrapper">
-<div id="qv">
- <h2 id="Contents">In this document</h2>
- <ol id="auto-toc">
- </ol>
- <strong>See also</strong>
- <ol>
- <li><a
- href="http://developer.android.com/guide/practices/verifying-apps-art.html">Verifying
- App Behavior on the Android Runtime (ART)</a></li>
- </ol>
-</div>
-</div>
-
-<p>
-ART is a new Android runtime being introduced experimentally in the 4.4
-release. This is a preview of work in progress in KitKat that can be turned on
-in <strong>Settings</strong> > <strong>developer options</strong>. This is
-available for the purpose of obtaining early developer and partner feedback.</p>
-
-<p class="caution"><strong>Important:</strong> Dalvik must remain the default
-runtime or you risk breaking your Android implementations and third-party
-applications.</p>
-
-<p>Most existing apps should just work when running with ART. However, some
-techniques that work on Dalvik do not work on ART. For information about the
-most important issues, see <a
-href="http://developer.android.com/guide/practices/verifying-apps-art.html">Verifying
-App Behavior on the Android Runtime (ART)</a>.</p>
-
-<h2 id="features">ART Features</h2>
-
-<p>Here are some of the major new features implemented by ART.</p>
-
-<h3 id="AOT_compilation">Ahead-of-time (AOT) compilation</h3>
-
-<p>ART introduces ahead-of-time (AOT) compilation, which can improve app
-performance. ART also has tighter install-time verification than Dalvik.</p>
-
-<p>At install time, ART compiles apps using the on-device
-<strong>dex2oat</strong> tool. This utility accepts <a
-href="http://source.android.com/devices/tech/dalvik/dex-format.html">DEX</a> files as input and
-generates a compiled app executable for the target device. The utility should be
-able to compile all valid DEX files without difficulty. However, some
-post-processing tools produce invalid files that may be tolerated by Dalvik but
-cannot be compiled by ART. For more information, see <a
-href="http://developer.android.com/guide/practices/verifying-apps-art.html#GC_Migration">Addressing
-Garbage Collection Issues</a>.</p>
-
-<h3 id="Improved_GC">Improved garbage collection</h3>
-
-<p>Garbage collection (GC) can impair an app's performance, resulting in choppy
-display, poor UI responsiveness, and other problems. ART improves garbage
-collection in several ways:</p>
-
-<ul>
- <li>One GC pause instead of two</li>
- <li>Parallelized processing during the remaining GC pause</li>
- <li>Collector with lower pause time for the special case of cleaning up
- recently-allocated, short-lived objects</li>
- <li>Improved garbage collection ergonomics, making concurrent garbage
- collections more timely, which makes <a
- href="http://developer.android.com/tools/debugging/debugging-memory.html#LogMessages"><code>GC_FOR_ALLOC</code></a>
- events extremely rare in typical use cases</li>
-</ul>
-
-<p>ART currently does not use compacting GC, but this feature is under
-development in the <a href="https://source.android.com">Android Open Source
-Project (AOSP)</a>. In the meantime, don't perform operations that are
-incompatible with compacting GC, such as storing pointers to object fields. For
-more information, see <a
-href="http://developer.android.com/guide/practices/verifying-apps-art.html#GC_Migration">Addressing
-Garbage Collection Issues</a>.</p>
-
-<h3 id="Debugging_Imp">Development and debugging improvements</h3>
-
-<p>ART offers a number of features to improve app development and debugging.</p>
-
-<h4 id="Sampling_Profiler">Support for sampling profiler</h4>
-
-<p>Historically, developers have used the <a
-href=" http://developer.android.com/tools/help/traceview.html">Traceview</a>
-tool (designed for tracing
-application execution) as a profiler. While Traceview gives useful information,
-its results on Dalvik have been skewed by the per-method-call overhead, and use
-of the tool noticeably affects run time performance.</p>
-
-<p>ART adds support for a dedicated sampling profiler that does not have these
-limitations. This gives a more accurate view of app execution without
-significant slowdown. Sampling support has also been added to Traceview for
-Dalvik.</p>
-
-<h4 id="Debugging_Features">Support for more debugging features</h4>
-
-<p>ART supports a number of new debugging options, particularly in monitor- and
-garbage collection-related functionality. For example, you can:</p>
-
-<ul>
- <li>See what locks are held in stack traces, then jump to the thread that
- holds a lock.</li>
- <li>Ask how many live instances there are of a given class, ask to see the
- instances, and see what references are keeping an object live.</li>
- <li>Filter events (like breakpoint) for a specific instance.</li>
- <li>See the value returned by a method when it exits (using “method-exit”
- events).</li>
- <li>Set field watchpoint to suspend the execution of a program when a specific
- field is accessed and/or modified.</li>
-</ul>
-
-<h4 id="Crash_Reports">Improved diagnostic detail in exceptions and crash reports</h4>
-
-<p>ART gives you as much context and detail as possible when runtime exceptions
-occur. ART provides expanded exception detail for <code><a
-href="http://developer.android.com/reference/java/lang/ClassCastException.html">java.lang.ClassCastException</a></code>,
-<code><a
-href="http://developer.android.com/reference/java/lang/ClassNotFoundException.html">java.lang.ClassNotFoundException</a></code>,
-and <code><a
-href="http://developer.android.com/reference/java/lang/NullPointerException.html">java.lang.NullPointerException</a></code>.
-(Later versions of Dalvik provided expanded exception detail for <code><a
-href="http://developer.android.com/reference/java/lang/ArrayIndexOutOfBoundsException.html">java.lang.ArrayIndexOutOfBoundsException</a></code>
-and <code><a
-href="http://developer.android.com/reference/java/lang/ArrayStoreException.html">java.lang.ArrayStoreException</a></code>,
-which now include the size of the array and the out-of-bounds offset, and ART
-does this as well.)</p>
-
-<p>For example, <code><a
-href="http://developer.android.com/reference/java/lang/NullPointerException.html">java.lang.NullPointerException</a></code>
-now shows information about what the app was trying to do with the null pointer,
-such as the field the app was trying to write to, or the method it was trying to
-call. Here are some typical examples:</p>
-
-<pre class="no-pretty-print">
-java.lang.NullPointerException: Attempt to write to field 'int
-android.accessibilityservice.AccessibilityServiceInfo.flags' on a null object
-reference</pre>
-
-<pre class="no-pretty-print">
-java.lang.NullPointerException: Attempt to invoke virtual method
-'java.lang.String java.lang.Object.toString()' on a null object reference</pre>
-
-<p>ART also provides improved context information in app native crash reports,
-by including both Java and native stack information. </p>
-
-<h2 id="Known_Issues">Known Issues</h2>
-
-<p>The following known issues are present in the 4.4.1 implementation of ART.</p>
-
-<ul>
-
- <li><em>Compile-time issue:</em> As noted above, ART flags unbalanced
- <code>monitorenter</code>/<code>moniterexit</code> instructions. We relaxed
- this check in 4.4.1 but intend to restore this verification in the future once
- tools are fixed, as this check is necessary for certain compiler
- optimizations. <a
- href="https://code.google.com/p/android/issues/detail?id=61916">https://code.google.com/p/android/issues/detail?id=61916</a></li>
-
- <li><em>Run-time issue:</em> There was an issue where JNI
- <code>GetFieldID</code> and <code>GetStaticFieldID</code> were using the wrong
- class loader on unattached threads, often leading to later CheckJNI errors or
- NoSuchFieldError exceptions. <a
- href="http://code.google.com/p/android/issues/detail?id=63970">http://code.google.com/p/android/issues/detail?id=63970</a></li>
-
- <li><em>Run-time issue:</em> Calling JNI <code>NewDirectByteBuffer()</code>
- with byte size of <code>0</code> led to the following CheckJNI error: <pre
- class="no-pretty-print"> JNI DETECTED ERROR IN APPLICATION: capacity must be
- greater than 0: 0</pre> <a
- href="http://code.google.com/p/android/issues/detail?id=63055">http://code.google.com/p/android/issues/detail?id=63055</a></li>
-
-</ul>
-
-<h3 id="Fixed_Issues">Fixed issues</h3>
-
-<ul>
-
- <li><em>Compile-time issue:</em> Overly aggressive verification and
- compilation of unused portions of dex files lead to corrupt package messages.
- This was addressed in AOSP with: <a
- href="https://android-review.googlesource.com/#/c/72374/">https://android-review.googlesource.com/#/c/72374/</a></li>
-
- <li><em>Debug-time issue:</em> Interactive debugging performance was slow,
- even in code without breakpoints. This has been addressed in the latest AOSP
- code.</li>
-
-</ul>
-
-<h2 id="building">Enabling ART in Android Build</h2>
-
-<p> Two runtimes are now available, the existing Dalvik runtime
-(<code>libdvm.so</code>) and the ART runtime (<code>libart.so</code>). A device
-can be built using either or both runtimes. (You can dual boot from
-<strong>Developer options</strong> if both runtimes are installed.) See
-runtime_common.mk. That is included from build/target/product/runtime_libdvm.mk
-or build/target/product/runtime_libart.mk or both.</p>
-
-<p> The <code>dalvikvm</code> command line tool can run with either runtime now.
-It will default to using the runtime specified in <strong>developer
-options</strong>. The default can be overridden by specifying the desired
-runtime library, for example with <code>-XXlib:libart.so</code> </p>
-
-<p>
-A new <code>PRODUCT_RUNTIMES</code> variable controls which runtimes
-are included in a build. Include it within either
-<code>build/target/product/core_minimal.mk</code> or
-<code>build/target/product/core_base.mk</code>.
-</p>
-
-<p>
-Add this to the device makefile to have both runtimes
-built and installed, with Dalvik as the default:
-</br>
-<code>PRODUCT_RUNTIMES := runtime_libdvm_default</code>
-</br>
-<code>PRODUCT_RUNTIMES += runtime_libart</code>
-</p>
-
-<h2 id="Reporting_Problems">Reporting Problems</h2>
-
-<p>If you run into any issues that aren’t due to app JNI issues, please report
-them via the Android Open Source Project Issue Tracker at <a
-href="https://code.google.com/p/android/issues/list">https://code.google.com/p/android/issues/list</a>.
-Please include an <code>"adb bugreport"</code> and link to the app in Google
-Play store if available. Otherwise, if possible, attach an APK that reproduces
-the issue. Please note that issues (including attachments) are publicly
-visible.</p>
diff --git a/src/devices/tech/dalvik/dalvik-bytecode.jd b/src/devices/tech/dalvik/dalvik-bytecode.jd
index 8d4f52b..1b9b9e3 100644
--- a/src/devices/tech/dalvik/dalvik-bytecode.jd
+++ b/src/devices/tech/dalvik/dalvik-bytecode.jd
@@ -1,8 +1,8 @@
-page.title=Bytecode for the Dalvik VM
+page.title=Dalvik bytecode
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -16,13 +16,21 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<h2>General Design</h2>
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id="design">General design</h2>
<ul>
<li>The machine model and calling conventions are meant to approximately
imitate common real architectures and C-style calling conventions:
<ul>
- <li>The VM is register-based, and frames are fixed in size upon creation.
+ <li>The machine is register-based, and frames are fixed in size upon creation.
Each frame consists of a particular number of registers (specified by
the method) as well as any adjunct data needed to execute the method,
such as (but not limited to) the program counter and a reference to the
@@ -149,7 +157,7 @@
</li>
</ul>
-<h2>Summary of Instruction Set</h2>
+<h2 id="instructions">Summary of bytecode set</h2>
<table class="instruc">
<thead>
@@ -987,7 +995,7 @@
</tbody>
</table>
-<h2>packed-switch-payload Format</h2>
+<h2 id="packed-switch">packed-switch-payload format</h2>
<table class="supplement">
<thead>
@@ -1026,7 +1034,7 @@
<p><b>Note:</b> The total number of code units for an instance of this
table is <code>(size * 2) + 4</code>.</p>
-<h2>sparse-switch-payload Format</h2>
+<h2 id="sparse-switch">sparse-switch-payload format</h2>
<table class="supplement">
<thead>
@@ -1066,7 +1074,7 @@
<p><b>Note:</b> The total number of code units for an instance of this
table is <code>(size * 4) + 2</code>.</p>
-<h2>fill-array-data-payload Format</h2>
+<h2 id="fill-array">fill-array-data-payload format</h2>
<table class="supplement">
<thead>
@@ -1104,7 +1112,7 @@
table is <code>(size * element_width + 1) / 2 + 4</code>.</p>
-<h2>Mathematical Operation Details</h2>
+<h2 id="math">Mathematical operation details</h2>
<p><b>Note:</b> Floating point operations must follow IEEE 754 rules, using
round-to-nearest and gradual underflow, except where stated otherwise.</p>
diff --git a/src/devices/tech/dalvik/dex-format.jd b/src/devices/tech/dalvik/dex-format.jd
index 744eb86..bd167fb 100644
--- a/src/devices/tech/dalvik/dex-format.jd
+++ b/src/devices/tech/dalvik/dex-format.jd
@@ -1,4 +1,4 @@
-page.title=Dalvik Executable Format
+page.title=Dalvik Executable format
@jd:body
<!--
@@ -20,7 +20,7 @@
files, which are used to hold a set of class definitions and their associated
adjunct data.</p>
-<h2>Guide To Types</h2>
+<h2 id="types">Guide to types</h2>
<table class="guide">
<thead>
@@ -77,7 +77,7 @@
</tbody>
</table>
-<h3>LEB128</h3>
+<h3 id="leb128">LEB128</h3>
<p>LEB128 ("<b>L</b>ittle-<b>E</b>ndian <b>B</b>ase <b>128</b>") is a
variable-length encoding for
@@ -157,7 +157,7 @@
</tbody>
</table>
-<h2>Overall File Layout</h2>
+<h2 id="file-layout">File layout</h2>
<table class="format">
<thead>
@@ -256,9 +256,9 @@
</tbody>
</table>
-<h2>Bitfield, String, and Constant Definitions</h2>
+<h2 id="definitions">Bitfield, string and constant definitions</h2>
-<h3>DEX_FILE_MAGIC</h3>
+<h3 id="dex-file-magic">DEX_FILE_MAGIC</h3>
<h4>embedded in header_item</h4>
<p>The constant array/string <code>DEX_FILE_MAGIC</code> is the list of
@@ -284,7 +284,7 @@
versions of the format differ significantly from the version described in this
document.</p>
-<h3>ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT</h3>
+<h3 id="endian-constant">ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT</h3>
<h4>embedded in header_item</h4>
<p>The constant <code>ENDIAN_CONSTANT</code> is used to indicate the
@@ -300,7 +300,7 @@
uint REVERSE_ENDIAN_CONSTANT = 0x78563412;
</pre>
-<h3>NO_INDEX</h3>
+<h3 id="no-index">NO_INDEX</h3>
<h4>embedded in class_def_item and debug_info_item</h4>
<p>The constant <code>NO_INDEX</code> is used to indicate that
@@ -316,7 +316,7 @@
uint NO_INDEX = 0xffffffff; // == -1 if treated as a signed int
</pre>
-<h3>access_flags Definitions</h3>
+<h3 id="access-flags">access_flags definitions</h3>
<h4>embedded in class_def_item, encoded_field, encoded_method, and
InnerClass</h4>
@@ -492,7 +492,7 @@
<p><super>*</super> Only allowed on for <code>InnerClass</code> annotations,
and must not ever be on in a <code>class_def_item</code>.</p>
-<h3>MUTF-8 (Modified UTF-8) Encoding</h3>
+<h3 id="mutf-8">MUTF-8 (Modified UTF-8) Encoding</h3>
<p>As a concession to easier legacy support, the <code>.dex</code> format
encodes its string data in a de facto standard modified UTF-8 form, hereafter
@@ -531,7 +531,7 @@
<a href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8
per se.</p>
-<h3>encoded_value Encoding</h3>
+<h3 id="encoding">encoded_value encoding</h3>
<h4>embedded in annotation_element and encoded_array_item </h4>
<p>An <code>encoded_value</code> is an encoded piece of (nearly)
@@ -573,7 +573,7 @@
</tbody>
</table>
-<h3>Value Formats</h3>
+<h3 id="value-formats">Value formats</h3>
<table class="encodedValue">
<thead>
@@ -699,7 +699,7 @@
<td><i>(none; must be <code>0</code>)</i></td>
<td>encoded_array</td>
<td>an array of values, in the format specified by
- "<code>encoded_array</code> Format" below. The size
+ "<code>encoded_array</code> format" below. The size
of the <code>value</code> is implicit in the encoding.
</td>
</tr>
@@ -709,7 +709,7 @@
<td><i>(none; must be <code>0</code>)</i></td>
<td>encoded_annotation</td>
<td>a sub-annotation, in the format specified by
- "<code>encoded_annotation</code> Format" below. The size
+ "<code>encoded_annotation</code> format" below. The size
of the <code>value</code> is implicit in the encoding.
</td>
</tr>
@@ -733,7 +733,7 @@
</tbody>
</table>
-<h3>encoded_array Format</h3>
+<h3 id="encoded-array">encoded_array format</h3>
<table class="format">
<thead>
@@ -760,7 +760,7 @@
</tbody>
</table>
-<h3>encoded_annotation Format</h3>
+<h3 id="encoded-annotation">encoded_annotation format</h3>
<table class="format">
<thead>
@@ -794,7 +794,7 @@
</tbody>
</table>
-<h3>annotation_element Format</h3>
+<h3 id="annotation-element">annotation_element format</h3>
<table class="format">
<thead>
@@ -821,13 +821,13 @@
</tbody>
</table>
-<h2>String Syntax</h2>
+<h2 id="string-syntax">String syntax</h2>
<p>There are several kinds of item in a <code>.dex</code> file which
ultimately refer to a string. The following BNF-style definitions
indicate the acceptable syntax for these strings.</p>
-<h3><i>SimpleName</i></h3>
+<h3 id="simplename"><i>SimpleName</i></h3>
<p>A <i>SimpleName</i> is the basis for the syntax of the names of other
things. The <code>.dex</code> format allows a fair amount of latitude
@@ -896,7 +896,7 @@
</tr>
</table>
-<h3><i>MemberName</i></h3>
+<h3 id="membername"><i>MemberName</i></h3>
<h4>used by field_id_item and method_id_item</h4>
<p>A <i>MemberName</i> is the name of a member of a class, members being
@@ -914,7 +914,7 @@
</tr>
</table>
-<h3><i>FullClassName</i></h3>
+<h3 id="fullclassname"><i>FullClassName</i></h3>
<p>A <i>FullClassName</i> is a fully-qualified class name, including an
optional package specifier followed by a required name.</p>
@@ -933,7 +933,7 @@
</tr>
</table>
-<h3><i>TypeDescriptor</i></h3>
+<h3 id="typedescriptor"><i>TypeDescriptor</i></h3>
<h4>used by type_id_item</h4>
<p>A <i>TypeDescriptor</i> is the representation of any type, including
@@ -1003,7 +1003,7 @@
</tr>
</table>
-<h3><i>ShortyDescriptor</i></h3>
+<h3 id="shortydescriptor"><i>ShortyDescriptor</i></h3>
<h4>used by proto_id_item</h4>
<p>A <i>ShortyDescriptor</i> is the short form representation of a method
@@ -1067,7 +1067,7 @@
</tr>
</table>
-<h3><i>TypeDescriptor</i> Semantics</h3>
+<h3 id="typedescriptor"><i>TypeDescriptor</i> Semantics</h3>
<p>This is the meaning of each of the variants of <i>TypeDescriptor</i>.</p>
@@ -1129,12 +1129,12 @@
</tbody>
</table>
-<h2>Items and Related Structures</h2>
+<h2 id="items">Items and related structures</h2>
<p>This section includes definitions for each of the top-level items that
may appear in a <code>.dex</code> file.
-<h3>header_item</h3>
+<h3 id="header-item">header_item</h3>
<h4>appears in the header section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1317,7 +1317,7 @@
</tbody>
</table>
-<h3>map_list</h3>
+<h3 id="map-list">map_list</h3>
<h4>appears in the data section</h4>
<h4>referenced from header_item</h4>
<h4>alignment: 4 bytes</h4>
@@ -1354,7 +1354,7 @@
</tbody>
</table>
-<h3>map_item Format</h3>
+<h3 id="map-item">map_item format</h3>
<table class="format">
<thead>
@@ -1389,7 +1389,7 @@
</table>
-<h3>Type Codes</h3>
+<h3 id="type-codes">Type Codes</h3>
<table class="typeCodes">
<thead>
@@ -1513,7 +1513,7 @@
</table>
-<h3>string_id_item</h3>
+<h3 id="string-item">string_id_item</h3>
<h4>appears in the string_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1539,7 +1539,7 @@
</tbody>
</table>
-<h3>string_data_item</h3>
+<h3 id="string-data-item">string_data_item</h3>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -1578,7 +1578,7 @@
</tbody>
</table>
-<h3>type_id_item</h3>
+<h3 id="type-id-item">type_id_item</h3>
<h4>appears in the type_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1602,7 +1602,7 @@
</tbody>
</table>
-<h3>proto_id_item</h3>
+<h3 id="proto-id-item">proto_id_item</h3>
<h4>appears in the proto_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1645,7 +1645,7 @@
</tbody>
</table>
-<h3>field_id_item</h3>
+<h3 id="field-id-item">field_id_item</h3>
<h4>appears in the field_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1683,7 +1683,7 @@
</tbody>
</table>
-<h3>method_id_item</h3>
+<h3 id="method-id-item">method_id_item</h3>
<h4>appears in the method_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1721,7 +1721,7 @@
</tbody>
</table>
-<h3>class_def_item</h3>
+<h3 id="class-def-item">class_def_item</h3>
<h4>appears in the class_defs section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1825,7 +1825,7 @@
</tbody>
</table>
-<h3>class_data_item</h3>
+<h3 id="class-data-item">class_data_item</h3>
<h4>referenced from class_def_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -1900,7 +1900,7 @@
<p><b>Note:</b> All elements' <code>field_id</code>s and
<code>method_id</code>s must refer to the same defining class.</p>
-<h3>encoded_field Format</h3>
+<h3 id="encoded-field-format">encoded_field format</h3>
<table class="format">
<thead>
@@ -1930,7 +1930,7 @@
</tbody>
</table>
-<h3>encoded_method Format</h3>
+<h3 id="encoded-method">encoded_method format</h3>
<table class="format">
<thead>
@@ -1970,7 +1970,7 @@
</tbody>
</table>
-<h3>type_list</h3>
+<h3 id="type-list">type_list</h3>
<h4>referenced from class_def_item and proto_id_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1997,7 +1997,7 @@
</tbody>
</table>
-<h3>type_item Format</h3>
+<h3 id="type-item-format">type_item format</h3>
<table class="format">
<thead>
@@ -2016,7 +2016,7 @@
</tbody>
</table>
-<h3>code_item</h3>
+<h3 id="code-item">code_item</h3>
<h4>referenced from encoded_method</h4>
<h4>appears in the data section</h4>
<h4>alignment: 4 bytes</h4>
@@ -2076,7 +2076,7 @@
<td>ushort[insns_size]</td>
<td>actual array of bytecode. The format of code in an <code>insns</code>
array is specified by the companion document
- <a href="dalvik-bytecode.html">"Bytecode for the Dalvik VM"</a>. Note
+ <a href="dalvik-bytecode.html">Dalvik bytecode</a>. Note
that though this is defined as an array of <code>ushort</code>, there
are some internal structures that prefer four-byte alignment. Also,
if this happens to be in an endian-swapped file, then the swapping is
@@ -2113,7 +2113,7 @@
</tbody>
</table>
-<h3>try_item Format</h3>
+<h3 id="type-item">try_item format</h3>
<table class="format">
<thead>
@@ -2151,7 +2151,7 @@
</tbody>
</table>
-<h3>encoded_catch_handler_list Format</h3>
+<h3 id="encoded-catch-handlerlist">encoded_catch_handler_list format</h3>
<table class="format">
<thead>
@@ -2176,7 +2176,7 @@
</tbody>
</table>
-<h3>encoded_catch_handler Format</h3>
+<h3 id="encoded-catch-handler">encoded_catch_handler format</h3>
<table class="format">
<thead>
@@ -2216,7 +2216,7 @@
</tbody>
</table>
-<h3>encoded_type_addr_pair Format</h3>
+<h3 id="encoded-type-addr-pair">encoded_type_addr_pair format</h3>
<table class="format">
<thead>
@@ -2242,7 +2242,7 @@
</tbody>
</table>
-<h3>debug_info_item</h3>
+<h3 id="debug-info-item">debug_info_item</h3>
<h4>referenced from code_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -2457,7 +2457,7 @@
</tbody>
</table>
-<h3>Special Opcodes</h3>
+<h3 id="opcodes">Special opcodes</h3>
<p>Opcodes with values between <code>0x0a</code> and <code>0xff</code>
(inclusive) move both the <code>line</code> and <code>address</code>
@@ -2475,7 +2475,7 @@
address += (adjusted_opcode / DBG_LINE_RANGE)
</pre>
-<h3>annotations_directory_item</h3>
+<h3 id="annotations-directory">annotations_directory_item</h3>
<h4>referenced from class_def_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: 4 bytes</h4>
@@ -2541,7 +2541,7 @@
<p><b>Note:</b> All elements' <code>field_id</code>s and
<code>method_id</code>s must refer to the same defining class.</p>
-<h3>field_annotation Format</h3>
+<h3 id="field-annotation">field_annotation format</h3>
<table class="format">
<thead>
@@ -2571,7 +2571,7 @@
</tbody>
</table>
-<h3>method_annotation Format</h3>
+<h3 id="method-annotation">method_annotation format</h3>
<table class="format">
<thead>
@@ -2601,7 +2601,7 @@
</tbody>
</table>
-<h3>parameter_annotation Format</h3>
+<h3 id="parameter-annotation">parameter_annotation format</h3>
<table class="format">
<thead>
@@ -2631,7 +2631,7 @@
</tbody>
</table>
-<h3>annotation_set_ref_list</h3>
+<h3 id="set-ref-list">annotation_set_ref_list</h3>
<h4>referenced from parameter_annotations_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: 4 bytes</h4>
@@ -2658,7 +2658,7 @@
</tbody>
</table>
-<h3>annotation_set_ref_item Format</h3>
+<h3 id="set-ref-item">annotation_set_ref_item format</h3>
<table class="format">
<thead>
@@ -2682,7 +2682,7 @@
</tbody>
</table>
-<h3>annotation_set_item</h3>
+<h3 id="annotation-set-item">annotation_set_item</h3>
<h4>referenced from annotations_directory_item, field_annotations_item,
method_annotations_item, and annotation_set_ref_item</h4>
<h4>appears in the data section</h4>
@@ -2712,7 +2712,7 @@
</tbody>
</table>
-<h3>annotation_off_item Format</h3>
+<h3 id="off-item">annotation_off_item format</h3>
<table class="format">
<thead>
@@ -2736,7 +2736,7 @@
</table>
-<h3>annotation_item</h3>
+<h3 id="annotation-item">annotation_item</h3>
<h4>referenced from annotation_set_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -2759,14 +2759,14 @@
<td>annotation</td>
<td>encoded_annotation</td>
<td>encoded annotation contents, in the format described by
- "<code>encoded_annotation</code> Format" under
- "<code>encoded_value</code> Encoding" above.
+ "<code>encoded_annotation</code> format" under
+ "<code>encoded_value</code> encoding" above.
</td>
</tr>
</tbody>
</table>
-<h3>Visibility values</h3>
+<h3 id="visibility">Visibility values</h3>
<p>These are the options for the <code>visibility</code> field in an
<code>annotation_item</code>:</p>
@@ -2802,7 +2802,7 @@
</tbody>
</table>
-<h3>encoded_array_item</h3>
+<h3 id="encoded-array-item">encoded_array_item</h3>
<h4>referenced from class_def_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -2827,7 +2827,7 @@
</tbody>
</table>
-<h2>System Annotations</h2>
+<h2 id="system-annotation">System annotations</h2>
<p>System annotations are used to represent various pieces of reflective
information about classes (and methods and fields). This information is
@@ -2836,7 +2836,7 @@
<p>System annotations are represented in <code>.dex</code> files as
annotations with visibility set to <code>VISIBILITY_SYSTEM</code>.
-<h3>dalvik.annotation.AnnotationDefault</h3>
+<h3 id="dalvik-annotation-default">dalvik.annotation.AnnotationDefault</h3>
<h4>appears on methods in annotation interfaces</h4>
<p>An <code>AnnotationDefault</code> annotation is attached to each
@@ -2862,7 +2862,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.EnclosingClass</h3>
+<h3 id="dalvik-enclosingclass">dalvik.annotation.EnclosingClass</h3>
<h4>appears on classes</h4>
<p>An <code>EnclosingClass</code> annotation is attached to each class
@@ -2890,7 +2890,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.EnclosingMethod</h3>
+<h3 id="dalvik-enclosingmethod">dalvik.annotation.EnclosingMethod</h3>
<h4>appears on classes</h4>
<p>An <code>EnclosingMethod</code> annotation is attached to each class
@@ -2916,7 +2916,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.InnerClass</h3>
+<h3 id="dalvik-innerclass">dalvik.annotation.InnerClass</h3>
<h4>appears on classes</h4>
<p>An <code>InnerClass</code> annotation is attached to each class
@@ -2953,7 +2953,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.MemberClasses</h3>
+<h3 id="dalvik-memberclasses">dalvik.annotation.MemberClasses</h3>
<h4>appears on classes</h4>
<p>A <code>MemberClasses</code> annotation is attached to each class
@@ -2977,7 +2977,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.Signature</h3>
+<h3 id="dalvik-signature">dalvik.annotation.Signature</h3>
<h4>appears on classes, fields, and methods</h4>
<p>A <code>Signature</code> annotation is attached to each class,
@@ -3020,7 +3020,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.Throws</h3>
+<h3 id="dalvik-throws">dalvik.annotation.Throws</h3>
<h4>appears on methods</h4>
<p>A <code>Throws</code> annotation is attached to each method which is
diff --git a/src/devices/tech/dalvik/index.jd b/src/devices/tech/dalvik/index.jd
index 71324d8..ed1bad1 100644
--- a/src/devices/tech/dalvik/index.jd
+++ b/src/devices/tech/dalvik/index.jd
@@ -1,8 +1,8 @@
-page.title=Dalvik Technical Information
+page.title=ART and Dalvik
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -16,14 +16,140 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>Dalvik is the managed runtime used by applications and some system
-services on Android. Dalvik was originally created specifically for
-the Android project.</p>
-<p>Much of the documentation in this directory is intended to help
-with the ongoing development of Dalvik, as opposed to most of the
-other documentation on this site, which is geared more towards
-application development.</p>
-<p>Please note, in Android 4.4 a new virtual machine - ART - is being introduced
-experimentally that will eventually replace Dalvik. Please see <a
-href="{@docRoot}devices/tech/dalvik/art.html">Introducing ART</a> for details.
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2 id="Contents">In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+</div>
+</div>
+
+<p>Android runtime (ART) is the managed runtime used by applications and some system
+services on Android. ART and its predecessor Dalvik were originally created
+specifically for the Android project. ART as the runtime executes the Dalvik
+Executable format and Dex bytecode specification.</p>
+
+<p>ART and Dalvik are compatible runtimes running Dex bytecode, so apps
+developed for Dalvik should work when running with ART. However, some
+techniques that work on Dalvik do not work on ART. For information about the
+most important issues, see <a
+href="http://developer.android.com/guide/practices/verifying-apps-art.html">Verifying
+App Behavior on the Android Runtime (ART)</a>.</p>
+
+<h2 id="features">ART Features</h2>
+
+<p>Here are some of the major features implemented by ART.</p>
+
+<h3 id="AOT_compilation">Ahead-of-time (AOT) compilation</h3>
+
+<p>ART introduces ahead-of-time (AOT) compilation, which can improve app
+performance. ART also has tighter install-time verification than Dalvik.</p>
+
+<p>At install time, ART compiles apps using the on-device
+<strong>dex2oat</strong> tool. This utility accepts <a
+href="http://source.android.com/devices/tech/dalvik/dex-format.html">DEX</a> files as input and
+generates a compiled app executable for the target device. The utility should be
+able to compile all valid DEX files without difficulty. However, some
+post-processing tools produce invalid files that may be tolerated by Dalvik but
+cannot be compiled by ART. For more information, see <a
+href="http://developer.android.com/guide/practices/verifying-apps-art.html#GC_Migration">Addressing
+Garbage Collection Issues</a>.</p>
+
+<h3 id="Improved_GC">Improved garbage collection</h3>
+
+<p>Garbage collection (GC) can impair an app's performance, resulting in choppy
+display, poor UI responsiveness, and other problems. ART improves garbage
+collection in several ways:</p>
+
+<ul>
+ <li>One GC pause instead of two</li>
+ <li>Parallelized processing during the remaining GC pause</li>
+ <li>Collector with lower total GC time for the special case of cleaning up
+ recently-allocated, short-lived objects</li>
+ <li>Improved garbage collection ergonomics, making concurrent garbage
+ collections more timely, which makes <a
+ href="http://developer.android.com/tools/debugging/debugging-memory.html#LogMessages"><code>GC_FOR_ALLOC</code></a>
+ events extremely rare in typical use cases</li>
+ <li>Compacting GC to reduce background memory usage and fragmentation</li>
+</ul>
+
+<h3 id="Debugging_Imp">Development and debugging improvements</h3>
+
+<p>ART offers a number of features to improve app development and debugging.</p>
+
+<h4 id="Sampling_Profiler">Support for sampling profiler</h4>
+
+<p>Historically, developers have used the <a
+href=" http://developer.android.com/tools/help/traceview.html">Traceview</a>
+tool (designed for tracing
+application execution) as a profiler. While Traceview gives useful information,
+its results on Dalvik have been skewed by the per-method-call overhead, and use
+of the tool noticeably affects run time performance.</p>
+
+<p>ART adds support for a dedicated sampling profiler that does not have these
+limitations. This gives a more accurate view of app execution without
+significant slowdown. Sampling support was added to Traceview for
+Dalvik in the KitKat release.</p>
+
+<h4 id="Debugging_Features">Support for more debugging features</h4>
+
+<p>ART supports a number of new debugging options, particularly in monitor- and
+garbage collection-related functionality. For example, you can:</p>
+
+<ul>
+ <li>See what locks are held in stack traces, then jump to the thread that
+ holds a lock.</li>
+ <li>Ask how many live instances there are of a given class, ask to see the
+ instances, and see what references are keeping an object live.</li>
+ <li>Filter events (like breakpoint) for a specific instance.</li>
+ <li>See the value returned by a method when it exits (using “method-exit”
+ events).</li>
+ <li>Set field watchpoint to suspend the execution of a program when a specific
+ field is accessed and/or modified.</li>
+</ul>
+
+<h4 id="Crash_Reports">Improved diagnostic detail in exceptions and crash reports</h4>
+
+<p>ART gives you as much context and detail as possible when runtime exceptions
+occur. ART provides expanded exception detail for <code><a
+href="http://developer.android.com/reference/java/lang/ClassCastException.html">java.lang.ClassCastException</a></code>,
+<code><a
+href="http://developer.android.com/reference/java/lang/ClassNotFoundException.html">java.lang.ClassNotFoundException</a></code>,
+and <code><a
+href="http://developer.android.com/reference/java/lang/NullPointerException.html">java.lang.NullPointerException</a></code>.
+(Later versions of Dalvik provided expanded exception detail for <code><a
+href="http://developer.android.com/reference/java/lang/ArrayIndexOutOfBoundsException.html">java.lang.ArrayIndexOutOfBoundsException</a></code>
+and <code><a
+href="http://developer.android.com/reference/java/lang/ArrayStoreException.html">java.lang.ArrayStoreException</a></code>,
+which now include the size of the array and the out-of-bounds offset, and ART
+does this as well.)</p>
+
+<p>For example, <code><a
+href="http://developer.android.com/reference/java/lang/NullPointerException.html">java.lang.NullPointerException</a></code>
+now shows information about what the app was trying to do with the null pointer,
+such as the field the app was trying to write to, or the method it was trying to
+call. Here are some typical examples:</p>
+
+<pre class="no-pretty-print">
+java.lang.NullPointerException: Attempt to write to field 'int
+android.accessibilityservice.AccessibilityServiceInfo.flags' on a null object
+reference</pre>
+
+<pre class="no-pretty-print">
+java.lang.NullPointerException: Attempt to invoke virtual method
+'java.lang.String java.lang.Object.toString()' on a null object reference</pre>
+
+<p>ART also provides improved context information in app native crash reports,
+by including both Java and native stack information. </p>
+
+<h2 id="Reporting_Problems">Reporting Problems</h2>
+
+<p>If you run into any issues that aren’t due to app JNI issues, please report
+them via the Android Open Source Project Issue Tracker at <a
+href="http://b.android.com">http://b.android.com</a>.
+Please include an <code>"adb bugreport"</code> and link to the app in Google
+Play store if available. Otherwise, if possible, attach an APK that reproduces
+the issue. Please note that issues (including attachments) are publicly
+visible.</p>
diff --git a/src/devices/tech/dalvik/instruction-formats.jd b/src/devices/tech/dalvik/instruction-formats.jd
index 37640da..91d876a 100644
--- a/src/devices/tech/dalvik/instruction-formats.jd
+++ b/src/devices/tech/dalvik/instruction-formats.jd
@@ -1,8 +1,8 @@
-page.title=Dalvik VM Instruction Formats
+page.title=Dalvik Executable instruction formats
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -16,13 +16,21 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<h2>Introduction and Overview</h2>
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
-<p>This document lists the instruction formats used by Dalvik bytecode
-and is meant to be used in conjunction with the
+<h2 id="intro">Introduction</h2>
+
+<p>This document lists the instruction formats used by the Dalvik Executable
+format and Dalvik bytecode. It is meant to be used in conjunction with the
<a href="dalvik-bytecode.html">bytecode reference document</a>.</p>
-<h3>Bitwise descriptions</h3>
+<h2 id="bitwise">Bitwise descriptions</h2>
<p>The first column in the format table lists the bitwise layout of
the format. It consists of one or more space-separated "words" each of
@@ -49,7 +57,7 @@
values in the high eight bits; and the second word consists of a single
16-bit value.</p>
-<h3>Format IDs</h3>
+<h2 id="format-ids">Format IDs</h2>
<p>The second column in the format table indicates the short identifier
for the format, which is used in other documents and in code to identify
@@ -69,7 +77,7 @@
"<code>s</code>" suffix, making them four characters total. Similarly,
suggested "inline" linking formats have an additional "<code>i</code>"
suffix. (In this context, inline linking is like static linking,
-except with more direct ties into a virtual machine's implementation.)
+except with more direct ties into a machine's implementation.)
Finally, a couple oddball suggested formats (e.g.,
"<code>20bc</code>") include two pieces of data which are both
represented in its format ID.</p>
@@ -147,7 +155,7 @@
</tbody>
</table>
-<h3>Syntax</h3>
+<h2 id="syntax">Syntax</h2>
<p>The third column of the format table indicates the human-oriented
syntax for instructions which use the indicated format. Each instruction
@@ -163,7 +171,7 @@
<p>Arguments which name a register have the form "<code>v<i>X</i></code>".
The prefix "<code>v</code>" was chosen instead of the more common
"<code>r</code>" exactly to avoid conflicting with (non-virtual) architectures
-on which a Dalvik virtual machine might be implemented which themselves
+on which the Dalvik Executable format might be implemented which themselves
use the prefix "<code>r</code>" for their registers. (That is, this
decision makes it possible to talk about both virtual and real registers
together without the need for circumlocution.)</p>
@@ -197,7 +205,7 @@
"<code>[<i>X</i>=<i>N</i>]</code>" (e.g., "<code>[A=2]</code>") to indicate
the correspondence.</p>
-<h2>The Formats</h2>
+<h2 id="formats">The formats</h2>
<table class="format">
<thead>