Docs: Update docs for default-methods and dex version 037

Bug: 24618811
Bug: 26942717
Bug: 27809626

Change-Id: I5d64597ca111fd5c6b24d35646d75078f56c04f1

3 files changed, 55 insertions, 10 deletions

diff --git a/src/devices/tech/dalvik/constraints.jd b/src/devices/tech/dalvik/constraints.jd
index c95bae03..6fe10dc1 100644
--- a/src/devices/tech/dalvik/constraints.jd
+++ b/src/devices/tech/dalvik/constraints.jd
@@ -53,7 +53,8 @@ a runtime is required to support only valid .dex files.</p>
         </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 @@ a runtime is required to support only valid .dex files.</p>
           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 @@ a runtime is required to support only valid .dex files.</p>
           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 @@ a runtime is required to support only valid .dex files.</p>
           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 f449bceb..f018fa31 100644
--- a/src/devices/tech/dalvik/dalvik-bytecode.jd
+++ b/src/devices/tech/dalvik/dalvik-bytecode.jd
@@ -774,14 +774,22 @@ page.title=Dalvik bytecode
     <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 8c59b018..aa11792a 100644
--- a/src/devices/tech/dalvik/dex-format.jd
+++ b/src/devices/tech/dalvik/dex-format.jd
@@ -271,8 +271,8 @@ encodes a format version number as three decimal digits, which is
 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 @@ platform (February&ndash;March 2008). In several respects, these earlier
 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>