Docs: Update docs for default-methods and dex version 037
Bug: 24618811
Bug: 26942717
Bug: 27809626
Change-Id: I5d64597ca111fd5c6b24d35646d75078f56c04f1
diff --git a/src/devices/tech/dalvik/constraints.jd b/src/devices/tech/dalvik/constraints.jd
index c95bae0..6fe10dc 100644
--- a/src/devices/tech/dalvik/constraints.jd
+++ b/src/devices/tech/dalvik/constraints.jd
@@ -53,7 +53,8 @@
</td>
<td>
- The <code>magic</code> number of the <code>.dex</code> file must be: <code>dex\n035\0</code>
+ The <code>magic</code> number of the <code>.dex</code> file must be
+ <code>dex\n035\0</code> or <code>dex\n037\0</code>.
</td>
</tr>
@@ -451,8 +452,7 @@
The <code>C</code> operand of the <code>invoke-virtual</code>,
<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).
+ method constant pool.
</td>
</tr>
@@ -465,8 +465,7 @@
The <code>B</code> operand of the <code>invoke-virtual/range</code>,
<code>invoke-super/range</code>, <code>invoke-direct/range</code>, and
<code>invoke-static/range</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).
+ into the method constant pool.
</td>
</tr>
@@ -591,6 +590,34 @@
must be non-negative and smaller than <code>registers_size-1</code>.
</td>
</tr>
+ <tr>
+ <td>
+ A24
+ </td>
+
+ <td>
+ The <code>method_id</code> operand of the <code>invoke-virtual</code>
+ and <code>invoke-direct</code> instructions must belong to a class
+ (not an interface). In Dex files prior to version <code>037</code>
+ the same must be true of <code>invoke-super</code> and
+ <code>invoke-static</code> instructions.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A25
+ </td>
+
+ <td>
+ The <code>method_id</code> operand of the
+ <code>invoke-virtual/range</code> and
+ <code>invoke-direct/range</code> instructions must belong to a class
+ (not an interface). In Dex files prior to version <code>037</code>
+ the same must be true of <code>invoke-super/range</code> and
+ <code>invoke-static/range</code> instructions.
+ </td>
+ </tr>
</table>
<h2 id="struct-constraints">
diff --git a/src/devices/tech/dalvik/dalvik-bytecode.jd b/src/devices/tech/dalvik/dalvik-bytecode.jd
index f449bce..f018fa3 100644
--- a/src/devices/tech/dalvik/dalvik-bytecode.jd
+++ b/src/devices/tech/dalvik/dalvik-bytecode.jd
@@ -774,14 +774,22 @@
<p><code>invoke-virtual</code> is used to invoke a normal virtual
method (a method that is not <code>private</code>, <code>static</code>,
or <code>final</code>, and is also not a constructor).</p>
- <p><code>invoke-super</code> is used to invoke the closest superclass's
+ <p>When the <code>method_id</code> references a method of a non-interface
+ class, <code>invoke-super</code> is used to invoke the closest superclass's
virtual method (as opposed to the one with the same <code>method_id</code>
in the calling class). The same method restrictions hold as for
<code>invoke-virtual</code>.</p>
+ <p>In Dex files version <code>037</code> or later, if the
+ <code>method_id</code> refers to an interface method,
+ <code>invoke-super</code> is used to invoke the most specific,
+ non-overridden version of that method defined on that interface. The same
+ method restrictions hold as for <code>invoke-virtual</code>. In Dex files
+ prior to version <code>037</code>, having an interface
+ <code>method_id</code> is illegal and undefined.</p>
<p><code>invoke-direct</code> is used to invoke a non-<code>static</code>
direct method (that is, an instance method that is by its nature
- non-overridable, namely either a <code>private</code> instance method
- or a constructor).</p>
+ non-overridable, namely either a <code>private</code> instance method or a
+ constructor).</p>
<p><code>invoke-static</code> is used to invoke a <code>static</code>
method (which is always considered a direct method).</p>
<p><code>invoke-interface</code> is used to invoke an
diff --git a/src/devices/tech/dalvik/dex-format.jd b/src/devices/tech/dalvik/dex-format.jd
index 8c59b01..aa11792 100644
--- a/src/devices/tech/dalvik/dex-format.jd
+++ b/src/devices/tech/dalvik/dex-format.jd
@@ -271,8 +271,8 @@
expected to increase monotonically over time as the format evolves.</p>
<pre>
-ubyte[8] DEX_FILE_MAGIC = { 0x64 0x65 0x78 0x0a 0x30 0x33 0x35 0x00 }
- = "dex\n035\0"
+ubyte[8] DEX_FILE_MAGIC = { 0x64 0x65 0x78 0x0a 0x30 0x33 0x37 0x00 }
+ = "dex\n037\0"
</pre>
<p class="note"><strong>Note:</strong> At least a couple earlier versions of the format have
@@ -284,6 +284,16 @@
versions of the format differ significantly from the version described in this
document.</p>
+<p class="note"><strong>Note:</strong> Support for version <code>037</code> of
+the format was added in the Android N release. Prior to this release most
+versions of Android have used version <code>035</code> of the format. The only
+difference between versions <code>035</code> and <code>037</code> is the
+addition of default methods and the adjustment of the <code>invoke</code>
+instruction semantics to support this feature. Due to a Dalvik bug present in
+older versions of Android, Dex version <code>036</code> has been skipped.
+Dex version <code>036</code> is not valid for any version of Android and never
+will be.</p>
+
<h3 id="endian-constant">ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT</h3>
<h4>embedded in header_item</h4>