Docs: Finishing addition of Dalvik constraints to site
Bug: 19440212
Change-Id: I36186dc6a2a43d769e77fb6979434d0684498af6
diff --git a/src/devices/tech/dalvik/constraints.jd b/src/devices/tech/dalvik/constraints.jd
index 612b0bf..8ad6aac 100644
--- a/src/devices/tech/dalvik/constraints.jd
+++ b/src/devices/tech/dalvik/constraints.jd
@@ -1,4 +1,4 @@
-page.title=Dalvik bytecode constraints
+page.title=Constraints
@jd:body
<!--
@@ -26,7 +26,16 @@
</div>
</div>
- <h2 id="gen-constraints">General integrity constraints </h2>
+<p>A <code>.dex</code> file is the transport format for Dalvik Bytecode. There are certain
+syntactical and semantical constraints for a file to be a valid <code>.dex</code> file, and
+a runtime is required to support only valid .dex files.</p>
+
+ <h2 id="gen-constraints">General .dex integrity constraints</h2>
+
+ <p>General integrity constraints are concerned with the larger structure of a
+ <code>.dex</code> file, as described in detail in <a href="dex-format.html"><code>.dex</code>
+ format</a>.</p>
+
<table>
<tr>
<th>
@@ -40,84 +49,254 @@
<tr>
<td>
- A1
+ G1
</td>
<td>
- The magic number of the DEX file must be "dex\n035\0".
+ The <code>magic</code> number of the <code>.dex</code> file must be: <code>dex\n035\0</code>
</td>
</tr>
<tr>
<td>
- A1
+ G2
</td>
<td>
The checksum must be an Adler-32 checksum of the whole file contents
- except magic and checksum field.
+ except <code>magic</code> and <code>checksum</code> field.
</td>
</tr>
+
+ <tr>
+ <td>
+ G3
+ </td>
+
+ <td>
+ The signature must be a SHA-1 hash of the whole file contents except <code>magic</code>,
+ <code>checksum</code>, and <code>signature</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G4
+ </td>
+
+ <td>
+ The <code>file_size</code> must match the actual file size in bytes.
+ </td>
+ </tr>
+
+
+ <tr>
+ <td>
+ G5
+ </td>
+
+ <td>
+ The <code>header_size</code> must have the value: <code>0x70</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G6
+ </td>
+
+ <td>
+ The <code>endian_tag</code> must have either the value:
+ <code>ENDIAN_CONSTANT</code> or <code>REVERSE_ENDIAN_CONSTANT</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G7
+ </td>
+
+ <td>
+ For each of the <code>link</code>, <code>string_ids</code>,
+ <code>type_ids</code>, <code>proto_ids</code>,
+ <code>field_ids</code>, <code>method_ids</code>, <code>class_defs</code>, and
+ <code>data</code> sections, the <code>offset</code> and <code>size</code> fields must be
+ either both zero or both non-zero. In the latter case, the offset must be
+ four-byte-aligned.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G8
+ </td>
+
+ <td>
+ All offset fields in the header except <code>map_off</code> must be four-byte-aligned.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G9
+ </td>
+
+ <td>
+ The <code>map_off</code> field must be either zero or point into the
+ data section. In the latter case, the <code>data</code> section must exist.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G10
+ </td>
+
+ <td>
+ None of the <code>link</code>, <code>string_ids</code>,
+ <code>type_ids</code>, <code>proto_ids</code>, <code>field_ids</code>,
+ <code>method_ids</code>, <code>class_defs</code> and <code>data</code> sections
+ must overlap each other or the header.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G11
+ </td>
+
+ <td>
+ If a map exists, then each map entry must have a valid type. Each type may appear at most once.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G12
+ </td>
+
+ <td>
+ If a map exists, then each map entry must have a non-zero offset and
+ size. The offset must point into the corresponding section of the file (i.e. a
+ <code>string_id_item</code> must point into the <code>string_ids</code> section) and the explicit or
+ implicit size of the item must match the actual contents and size of the
+ section.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G13
+ </td>
+
+ <td>
+ If a map exists, then the offset of map entry <code>n+1</code> must be greater or
+ equal to the offset of map entry <code>n plus than size of map entry n</code>. This implies
+ non-overlapping entries and low-to-high ordering.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G14
+ </td>
+
+ <td>
+ The following types of entries must have an offset that is
+ four-byte-aligned: <code>string_id_item</code>,
+ <code>type_id_item</code>, <code>proto_id_item</code>,
+ <code>field_id_item</code>,
+ <code>method_id_item</code>, <code>class_def_item</code>,
+ <code>type_list</code>, <code>code_item</code>,
+ <code>annotations_directory_item</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G15
+ </td>
+
+ <td>
+ For each <code>string_id_item</code>, the <code>string_data_off</code> field must contain a
+ valid reference into the <code>data</code> section. For the referenced <code>string_data_item</code>, the
+ <code>data</code> field must contain a valid MUTF-8 string, and the <code>utf16_size</code> must match
+ the decoded length of the string.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G16
+ </td>
+
+ <td>
+ For each <code>type_id_item</code>, the <code>desciptor_idx</code> field must contain a valid
+ reference into the <code>string_ids</code> list. The referenced string must be a valid type
+ descriptor.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G17
+ </td>
+
+ <td>
+ For each <code>proto_id_item</code>, the <code>shorty_idx</code> field must contain a valid
+ reference into the <code>string_ids</code> list. The referenced string must be a valid
+ shorty descriptor. Also, the <code>return_type_idx</code> field must be a valid index into
+ the <code>type_ids</code> section, and the <code>parameters_off</code> field must be either zero or a
+ valid offset pointing into the <code>data</code> section. If non-zero, the parameter list
+ must not contain any void entries.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G18
+ </td>
+
+ <td>
+ For each <code>field_id_item</code>, both the <code>class_idx</code> and <code>type_idx</code> fields must
+ be valid indices into the <code>type_ids</code> list. The entry referenced by <code>class_idx</code>
+ must be a non-array reference type. In addition, the <code>name_idx</code> field must be a
+ valid reference into the <code>string_ids</code> section, and the contents of the referenced
+ entry must conform to the <code>MemberName</code> specification.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G19
+ </td>
+
+ <td>
+ For each <code>method_id_item</code>, the <code>class_idx</code> field must be a valid index
+ into the <code>type_ids</code> section, and the referenced entry must be a non-array
+ reference type. The <code>proto_id</code> field must be a valid reference into the <code>proto_ids</code>
+ list. The <code>name_idx</code> field must be a valid reference into the <code>string_ids</code> section,
+ and the contents of the referenced entry must conform to the <code>MemberName</code>
+ specification.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G20
+ </td>
+
+ <td>
+ For each <code>field_id_item</code>, the <code>class_idx</code> field must be a valid index
+ into the <code>type_ids</code> list. The referenced entry must be a non-array reference
+ type.
+ </td>
+ </tr>
+
</table>
-<p>The signature must be a SHA-1 hash of the whole file contents except magic,
- checksum, and signature.</p>
-<p>The file_size must match the actual file size in bytes.</p>
-<p>The header_size must have the value 0x70.</p>
-<p>The endian_tag must have either the value ENDIAN_CONSTANT or
- REVERSE_ENDIAN_CONSTANT.</p>
-<p>For each of the link, string_ids, type_ids, proto_ids, field_ids, method_ids, class_defs
- and data sections, the offset and size fields must be either both zero or both
- non-zero. In the latter case, the offset must be four-byte-aligned.</p>
-<p>All offset fields in the header except map_off must be four-byte-aligned.</p>
-<p>The map_off field must be either zero or point into the data section. In the
- latter case, the data section must exist.</p>
-<p>None of the link, string_ids, type_ids, proto_ids, field_ids, method_ids, class_defs
- and data sections must overlap each other or the header.</p>
-<p>If a map exists, then each map entry must have a valid type. Each type may
- appear at most once.</p>
-<p>If a map exists, then each map entry must have a nonzero offset and size. The
- offset must point into the corresponding section of the file (i.e. a
- string_id_item must point into the string_ids section) and the explicit or
- implicit size of the item must match the actual contents and size of the
- section.</p>
-<p>If a map exists, then the offset of map entry n+1 must be greater or equal to
- the offset of map entry n plus then size of map entry n. This implies
- non-overlapping entries and low-to-high ordering.</p>
-<p>The following types of entries must have an offset that is
- four-byte-aligned: string_id_item, type_id_item, proto_id_item, field_id_item,
- method_id_item, class_def_item, type_list, code_item,
- annotations_directory_item.</p>
-<p>For each string_id_item, the string_data_off field must contain a valid
- reference into the data section. For the referenced string_data_item, the data
- field must contain a valid MUTF-8 string, and the utf16_size must match the
- decoded length of the string.</p>
-<p>For each type_id_item, the desciptor_idx field must contain a valid reference
- into the string_ids list. The referenced string must be a valid type descriptor.</p>
-<p>For each proto_id_item, the shorty_idx field must contain a valid reference
- into the string_ids list. The referenced string must be a valid shorty descriptor.
- Also, the return_type_idx field must be a valid index into the type_ids section,
- and the parameters_off field must be either zero or a valid offset pointing
- into the data section. If nonzero, the parameter list must not contain any void
- entries.</p>
-<p>For each field_id_item, both the class_idx and type_idx fields must be a valid
- indices into the
- type_ids list. The entry referenced by class_idx must be a non-array reference type.
- In addition, the name_idx field must be a valid reference into the string_ids
- section, and the contents of the referenced entry must conform to the MemberName
- specification.</p>
-<p>For each method_id_item, the class_idx field must be a valid index into the
- type_ids section, and the
- referenced entry must be a non-array reference type. The proto_id field must
- be a valid reference into the proto_ids list. The name_idx field must be a
- valid reference into the string_ids
- section, and the contents of the referenced entry must conform to the MemberName
- specification.</p>
-<p>For each class_def_item, ...</p>
-<p>For each field_id_item, the class_idx field must be a valid index into the
- type_ids list. The referenced entry must be a non-array reference type.</p>
<h2 id="static-constraints">
- Static constraints
+ Static bytecode constraints
</h2>
<p>
@@ -163,7 +342,7 @@
</td>
<td>
- The <code>insns</code> array must only contain valid Dalvik opcodes.
+ The <code>insns</code> array must contain only valid Dalvik opcodes.
</td>
</tr>
@@ -197,7 +376,7 @@
<td>
All <code>goto</code> and <code>if-<kind></code> targets must
- be opcodes within in the same method.
+ be opcodes within the same method.
</td>
</tr>
@@ -208,7 +387,7 @@
<td>
All targets of a <code>packed-switch</code> instruction must be
- opcodes within in the same method. The size and the list of targets
+ opcodes within the same method. The size and the list of targets
must be consistent.
</td>
</tr>
@@ -220,7 +399,7 @@
<td>
All targets of a <code>sparse-switch</code> instruction must be
- opcodes within in the same method. The corresponding table must be
+ opcodes within the same method. The corresponding table must be
consistent and sorted low-to-high.
</td>
</tr>
@@ -270,7 +449,7 @@
<td>
The <code>C</code> operand of the <code>invoke-virtual</code>,
- <code>invoke-super</code>, <code<invoke-direct</code> and
+ <code>invoke-super</code>, <code>invoke-direct</code> and
<code>invoke-static</code> instructions must be a valid index into the
method constant pool. In all cases, the referenced
<code>method_id</code> must belong to a class (not an interface).
@@ -297,8 +476,8 @@
</td>
<td>
- A method the name of which starts with a '<' must only be invoked
- implicitly by the VM, not by code originating from a Dex file. The
+ A method the name of which starts with a '<' must only be invoked
+ implicitly by the VM, not by code originating from a <code>.dex</code> file. The
only exception is the instance initializer, which may be invoked by
<code>invoke-direct</code>.
</td>
@@ -415,7 +594,7 @@
</table>
<h2 id="struct-constraints">
- Structural constraints
+ Structural bytecode constraints
</h2>
<p>
@@ -473,8 +652,8 @@
</td>
<td>
- An <code>invoke-direct</code> instruction must only invoke an instance
- initializer or a method in the current class or one of its
+ An <code>invoke-direct</code> instruction must invoke an instance
+ initializer or a method only in the current class or one of its
superclasses.
</td>
</tr>
@@ -485,7 +664,7 @@
</td>
<td>
- An instance initializer must only be invoked on an uninitialized
+ An instance initializer must be invoked only on an uninitialized
instance.
</td>
</tr>
@@ -496,7 +675,7 @@
</td>
<td>
- Instance methods may only be invoked on and instance fields may only
+ Instance methods may be invoked only on and instance fields may only
be accessed on already initialized instances.
</td>
</tr>
@@ -507,7 +686,7 @@
</td>
<td>
- A register which holds the result of a <code>new-instance</code>
+ A register that holds the result of a <code>new-instance</code>
instruction must not be used if the same
<code>new-instance</code> instruction is again executed before
the instance is initialized.
@@ -678,7 +857,7 @@
</td>
<td>
- A <code>move-exception</code> instruction must only appear as the
+ A <code>move-exception</code> instruction must appear only as the
first instruction in an exception handler.
</td>
</tr>
diff --git a/src/index.jd b/src/index.jd
index d420ca0..1acaab0 100644
--- a/src/index.jd
+++ b/src/index.jd
@@ -41,6 +41,12 @@
<div class="landing-docs">
<div class="col-8">
<h3>What's New</h3>
+<a href="{@docRoot}devices/tech/dalvik/constraints.html">
+ <h4>Dalvik constraints published</h4></a>
+ <p>The Android Runtime (ART) team has released a list of syntactical and semantical <strong><a
+ href="{@docRoot}devices/tech/dalvik/constraints.html">constraints</a></strong>
+ to help construct valid <code>.dex</code> files supported by the runtime.</p>
+
<a href="{@docRoot}source/64-bit-builds.html">
<h4>64-bit build instructions added</h4></a>
<p>Detailed instructions for building Android on a <strong><a
@@ -83,13 +89,6 @@
href="https://android.googlesource.com/platform/docs/source.android.com/+/master/src/compatibility/">Compatibility
Definition Documents (CDD)</a></strong> have been uploaded to AOSP for easy
diffing.</p>
-
-<a href="{@docRoot}devices/audio/terminology.html">
- <h4>Audio terminology enhanced</h4></a>
- <p><strong><a
- href="{@docRoot}devices/audio/terminology.html">Audio Terminology</a></strong>
- has been updated to include definitions for <em>FIFO</em>,
- <em>lossy</em>, <em>transparency</em>, and more.</p>
</div>
<div class="col-8">