Merge "Add invoke-custom bytecode and format changes."

3 files changed, 252 insertions, 11 deletions

diff --git a/src/devices/tech/dalvik/dalvik-bytecode.jd b/src/devices/tech/dalvik/dalvik-bytecode.jd
index 5e326806..d2aef973 100644
--- a/src/devices/tech/dalvik/dalvik-bytecode.jd
+++ b/src/devices/tech/dalvik/dalvik-bytecode.jd
@@ -1060,7 +1060,66 @@ page.title=Dalvik bytecode
   </td>
 </tr>
 <tr>
-  <td>fc..ff 10x</td>
+  <td>fc 35c</td>
+  <td>invoke-custom {vC, vD, vE, vF, vG}, call_site@BBBB</td>
+  <td>
+    <code>A:</code> argument word count (4 bits) <br>
+    <code>B:</code> call site reference index (16 bits) <br>
+    <code>C..G:</code> argument registers (4 bits each)
+  </td>
+  <td> Resolves and invokes the indicated call site.
+    The result from the invocation (if any) may be stored with an
+    appropriate <code>move-result*</code> variant as the immediately
+    subsequent instruction.
+
+    <p> This instruction executes in two phases: call site
+        resolution and call site invocation.
+
+    <p> Call site resolution checks whether the indicated
+      call site has an associated <code>java.lang.invoke.CallSite</code> instance.
+      If not, the bootstrap linker method for the indicated call site is
+      invoked using arguments present in the DEX file
+      (see <a href="dex-format.html#call-site-item">call_site_item</a>). The
+      bootstrap linker method returns
+      a <code>java.lang.invoke.CallSite</code> instance that will then
+      be associated with the indicated call site if no association
+      exists. Another thread may have already made the association first,
+      and if so execution of the instruction continues with the
+      first associated <code>java.lang.invoke.CallSite</code> instance.
+
+    <p> Call site invocation is made on the <code>java.lang.invoke.MethodHandle</code> target of the
+      resolved <code>java.lang.invoke.CallSite</code> instance. The target is invoked as if
+      executing <code>invoke-polymorphic</code> (described above)
+      using the method handle and arguments to
+      the <code>invoke-custom</code> instruction as the arguments to an
+      exact method handle invocation.
+
+    <p> Exceptions raised by the bootstrap linker method are wrapped
+      in a <code>java.lang.BootstrapMethodError</code>.  A <code>BootstrapMethodError</code> is also raised if:
+      <ul>
+        <li>the bootstrap linker method fails to return a <code>java.lang.invoke.CallSite</code> instance.</li>
+        <li>the returned <code>java.lang.invoke.CallSite</code> has a <code>null</code> method handle target.</li>
+        <li>the method handle target is not of the requested type.</li>
+      </ul>
+    <p> Present in Dex files from version <code>038</code> onwards.
+  </td>
+</tr>
+<tr>
+  <td>fd 3rc</td>
+  <td>invoke-custom/range {vCCCC .. vNNNN}, call_site@BBBB</td>
+  <td>
+    <code>A:</code> argument word count (8 bits) <br>
+    <code>B:</code> call site reference index (16 bits) <br>
+    <code>C:</code> first argument register (16-bits) <br>
+    <code>N = A + C - 1</code>
+  </td>
+  <td>
+    Resolve and invoke a call site. See the <code>invoke-custom</code> description above for details.
+    <p> Present in Dex files from version <code>038</code> onwards.
+  </td>
+</tr>
+<tr>
+  <td>fe..ff 10x</td>
   <td><i>(unused)</i></td>
   <td>&nbsp;</td>
   <td><i>(unused)</i></td>
diff --git a/src/devices/tech/dalvik/dex-format.jd b/src/devices/tech/dalvik/dex-format.jd
index 8bf5081d..33d96adf 100644
--- a/src/devices/tech/dalvik/dex-format.jd
+++ b/src/devices/tech/dalvik/dex-format.jd
@@ -237,6 +237,21 @@ values are unlikely to be needed).</p>
   </td>
 </tr>
 <tr>
+  <td>call_site_ids</td>
+  <td>call_site_id_item[]</td>
+  <td>call site identifiers list. These are identifiers for all call sites
+    referred to by this file, whether defined in the file or not. This list
+    must be sorted in ascending order of <code>call_site_off</code>. This
+    list must not contain any duplicate entries.
+</tr>
+<tr>
+  <td>method_handles</td>
+  <td>method_handle_item[]</td>
+  <td>method handles list. A list of all method handles referred to by this file,
+    whether defined in the file or not. This list is not sorted and may contain
+    duplicates which will logically correspond to different method handle instances.
+</tr>
+<tr>
   <td>data</td>
   <td>ubyte[]</td>
   <td>data area, containing all the support data for the tables listed above.
@@ -272,8 +287,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 0x37 0x00 }
-                        = "dex\n037\0"
+ubyte[8] DEX_FILE_MAGIC = { 0x64 0x65 0x78 0x0a 0x30 0x33 0x38 0x00 }
+                        = "dex\n038\0"
 </pre>
 
 <p class="note"><strong>Note:</strong> At least a couple earlier versions of the format have
@@ -285,15 +300,17 @@ 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>038</code> of the format was added in the Android 8.0
+release. Version <code>038</code> added new bytecodes
+(<code>invoke-polymorphic</code> and <code>invoke-custom</code>) and
+data for method handles.
+
 <p class="note"><strong>Note:</strong> Support for version <code>037</code> of
-the format was added in the Android 7.0 release. Prior to this release most
+the format was added in the Android 7.0 release. Prior to version <code>037</code> 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>
+addition of default methods and the adjustment of the <code>invoke</code>.
 
 <h3 id="endian-constant">ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT</h3>
 <h4>embedded in header_item</h4>
@@ -651,6 +668,26 @@ be both compact and straightforward to parse.</p>
   </td>
 </tr>
 <tr>
+  <td>VALUE_METHOD_TYPE</td>
+  <td>0x15</td>
+  <td>size - 1 (0&hellip;3)</td>
+  <td>ubyte[size]</td>
+  <td>unsigned (zero-extended) four-byte integer value,
+    interpreted as an index into
+    the <code>proto_ids</code> section and representing a method type value
+  </td>
+</tr>
+<tr>
+  <td>VALUE_METHOD_HANDLE</td>
+  <td>0x16</td>
+  <td>size - 1 (0&hellip;3)</td>
+  <td>ubyte[size]</td>
+  <td>unsigned (zero-extended) four-byte integer value,
+    interpreted as an index into
+    the <code>method_handles</code> section and representing a method handle value
+  </td>
+</tr>
+<tr>
   <td>VALUE_STRING</td>
   <td>0x17</td>
   <td>size - 1 (0&hellip;3)</td>
@@ -1454,6 +1491,18 @@ be ordered by initial offset and must not overlap.</p>
   <td>0x20</td>
 </tr>
 <tr>
+  <td>call_site_id_item</td>
+  <td>TYPE_CALL_SITE_ID_ITEM</td>
+  <td>0x0007</td>
+  <td>0x04</td>
+</tr>
+<tr>
+  <td>method_handle_item</td>
+  <td>TYPE_METHOD_HANDLE_ITEM</td>
+  <td>0x0008</td>
+  <td>0x08</td>
+</tr>
+<tr>
   <td>map_list</td>
   <td>TYPE_MAP_LIST</td>
   <td>0x1000</td>
@@ -1835,6 +1884,135 @@ be ordered by initial offset and must not overlap.</p>
 </tbody>
 </table>
 
+<h3 id="call-site-id-item">call_site_id_item</h3>
+<h4>appears in the call_site_ids section</h4>
+<h4>alignment: 4 bytes</h4>
+
+<table class="format">
+<thead>
+<tr>
+  <th>Name</th>
+  <th>Format</th>
+  <th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+  <td>call_site_off</td>
+  <td>uint</td>
+  <td>offset from the start of the file to call site defintion. The offset should
+  be in the data section, and the data there should be in the format specified by
+  "call_site_item" below.
+  </td>
+</tr>
+</tbody>
+</table>
+
+<h3 id="call-site-item">call_site_item</h3>
+<h4>appears in the data section</h4>
+<h4>alignment: none (byte aligned)</h4>
+
+<p> The call_site_item is an encoded_array_item whose elements correspond to the arguments
+provided to a bootstrap linker method. The first three arguments are:
+<ol>
+<li>A method handle representing the bootstrap linker method (VALUE_METHOD_HANDLE).</li>
+<li>A method name that the bootstrap linker should resolve (VALUE_STRING).</li>
+<li>A method type corresponding to the type of the method name to be resolved (VALUE_METHOD_TYPE).</li>
+</ol>
+
+<p>Any additional arguments are constant values passed to the bootstrap linker method. These arguments are
+passed in order and without any type conversions.
+
+<p>The method handle representing the bootstrap linker method must have return type <code>java.lang.invoke.CallSite</code>. The first three parameter types are:
+<ol>
+<li><code>java.lang.invoke.Lookup</code></li>
+<li><code>java.lang.String</code></li>
+<li><code>java.lang.invoke.MethodType</code></li>
+</ol>
+
+<p>And any remaining parameter types correspond to the additional arguments being passed to the bootstrap linker method.
+
+<h3 id="method-handle-item">method_handle_item</h3>
+<h4>appears in the method_handles section</h4>
+<h4>alignment: 4 bytes</h4>
+
+<table class="format">
+<thead>
+<tr>
+  <th>Name</th>
+  <th>Format</th>
+  <th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+  <td>method_handle_type</td>
+  <td>ushort</td>
+  <td>type of the method handle; see table below
+  </td>
+</tr>
+<tr>
+  <td>unused</td>
+  <td>ushort</td>
+  <td><i>(unused)</i></td>
+</tr>
+<tr>
+  <td>field_or_method_id/td>
+  <td>ushort</td>
+  <td>Field or method id depending on whether the method handle type is an accessor or a method invoker</td>
+</tr>
+<tr>
+  <td>unused</td>
+  <td>ushort</td>
+  <td><i>(unused)</i></td>
+</tr>
+</tbody>
+</table>
+
+<h3 id="method-handle-type-codes">Method Handle Type Codes</h3>
+
+<table class="format">
+<thead>
+<tr>
+  <th>Constant</th>
+  <th>Value</th>
+  <th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+  <td>METHOD_HANDLE_TYPE_STATIC_PUT</td>
+  <td>0x00</td>
+  <td>Method handle is a static field setter (accessor)</td>
+</tr>
+<tr>
+  <td>METHOD_HANDLE_TYPE_STATIC_GET</td>
+  <td>0x01</td>
+  <td>Method handle is a static field getter (accessor)</td>
+</tr>
+<tr>
+  <td>METHOD_HANDLE_TYPE_INSTANCE_PUT</td>
+  <td>0x02</td>
+  <td>Method handle is an instance field setter (accessor)</td>
+</tr>
+<tr>
+  <td>METHOD_HANDLE_TYPE_INSTANCE_GET</td>
+  <td>0x03</td>
+  <td>Method handle is an instance field getter (accessor)</td>
+</tr>
+<tr>
+  <td>METHOD_HANDLE_TYPE_INVOKE_STATIC</td>
+  <td>0x04</td>
+  <td>Method handle is a static method invoker</td>
+</tr>
+<tr>
+  <td>METHOD_HANDLE_TYPE_INVOKE_INSTANCE</td>
+  <td>0x05</td>
+  <td>Method handle is an instance method invoker</td>
+</tr>
+</tbody>
+</table>
+
 <h3 id="class-data-item">class_data_item</h3>
 <h4>referenced from class_def_item</h4>
 <h4>appears in the data section</h4>
diff --git a/src/devices/tech/dalvik/instruction-formats.jd b/src/devices/tech/dalvik/instruction-formats.jd
index d82f54c1..697bc02c 100644
--- a/src/devices/tech/dalvik/instruction-formats.jd
+++ b/src/devices/tech/dalvik/instruction-formats.jd
@@ -189,10 +189,11 @@ form "<code>+<i>X</i></code>".</p>
 "<code><i>kind</i>@<i>X</i></code>", where "<code><i>kind</i></code>"
 indicates which constant pool is being referred to. Each opcode that
 uses such a format explicitly allows only one kind of constant; see
-the opcode reference to figure out the correspondence. The four
+the opcode reference to figure out the correspondence. The
 kinds of constant pool are "<code>string</code>" (string pool index),
 "<code>type</code>" (type pool index), "<code>field</code>" (field
-pool index), and "<code>meth</code>" (method pool index).</p>
+pool index), "<code>meth</code>" (method pool index), and
+"<code>site</code>" (call site index).</p>
 
 <p>Similar to the representation of constant pool indices, there are
 also suggested (optional) forms that indicate prelinked offsets or
@@ -370,6 +371,8 @@ the correspondence.</p>
   <td><i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG},
     meth@BBBB<br/>
     <i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG},
+    site@BBBB<br/>
+    <i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG},
     type@BBBB<br/>
     <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF},
     <i><code>kind</code></i>@BBBB<br/>
@@ -431,6 +434,7 @@ the correspondence.</p>
   <td rowspan="3">AA|<i>op</i> BBBB CCCC</td>
   <td>3rc</td>
   <td><i><code>op</code></i> {vCCCC .. vNNNN}, meth@BBBB<br/>
+    <i><code>op</code></i> {vCCCC .. vNNNN}, site@BBBB<br/>
     <i><code>op</code></i> {vCCCC .. vNNNN}, type@BBBB<br/>
     <p><i>where <code>NNNN = CCCC+AA-1</code>, that is <code>A</code>
     determines the count <code>0..255</code>, and <code>C</code>