Add invoke-custom bytecode and format changes.
Test: m online-sac-docs
Bug: 33191717,30550796
Change-Id: I13fa9cee06cc653e073d7daa299a530e5788ed9c
diff --git a/src/devices/tech/dalvik/dalvik-bytecode.jd b/src/devices/tech/dalvik/dalvik-bytecode.jd
index 5e32680..d2aef97 100644
--- a/src/devices/tech/dalvik/dalvik-bytecode.jd
+++ b/src/devices/tech/dalvik/dalvik-bytecode.jd
@@ -1060,7 +1060,66 @@
</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> </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 8bf5081..33d96ad 100644
--- a/src/devices/tech/dalvik/dex-format.jd
+++ b/src/devices/tech/dalvik/dex-format.jd
@@ -237,6 +237,21 @@
</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 @@
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 @@
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 @@
</td>
</tr>
<tr>
+ <td>VALUE_METHOD_TYPE</td>
+ <td>0x15</td>
+ <td>size - 1 (0…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…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…3)</td>
@@ -1454,6 +1491,18 @@
<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 @@
</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 d82f54c..697bc02 100644
--- a/src/devices/tech/dalvik/instruction-formats.jd
+++ b/src/devices/tech/dalvik/instruction-formats.jd
@@ -189,10 +189,11 @@
"<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 @@
<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 @@
<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>
