Update the docs for ICS.
I'm _moving_ these from dalvik/docs/ so we don't have to remember to copy
changes across in future...
Change-Id: I08215850439fe08c1a2ca70f597f376056c5fe9d
diff --git a/src/tech/dalvik/dalvik-bytecode.html b/src/tech/dalvik/dalvik-bytecode.html
index 35fa64b..66c9c48 100644
--- a/src/tech/dalvik/dalvik-bytecode.html
+++ b/src/tech/dalvik/dalvik-bytecode.html
@@ -24,8 +24,13 @@
such as (but not limited to) the program counter and a reference to the
<code>.dex</code> file that contains the method.
</li>
- <li>Registers are 32 bits wide. Adjacent register pairs are used for 64-bit
- values.
+ <li>When used for bit values (such as integers and floating point
+ numbers), registers are considered 32 bits wide. Adjacent register
+ pairs are used for 64-bit values. There is no alignment requirement
+ for register pairs.
+ </li>
+ <li>When used for object references, registers are considered wide enough
+ to hold exactly one such reference.
</li>
<li>In terms of bitwise representation, <code>(Object) null == (int)
0</code>.
@@ -52,19 +57,24 @@
reasonably common, many instructions are limited to only addressing
the first 16
registers. When reasonably possible, instructions allow references to
- up to the first 256 registers. In cases where an instruction variant isn't
+ up to the first 256 registers. In addition, some instructions have variants
+ that allow for much larger register counts, including a pair of catch-all
+ <code>move</code> instructions that can address registers in the range
+ <code>v0</code> – <code>v65535</code>.
+ In cases where an instruction variant isn't
available to address a desired register, it is expected that the register
contents get moved from the original register to a low register (before the
operation) and/or moved from a low result register to a high register
(after the operation).
</li>
<li>There are several "pseudo-instructions" that are used to hold
- variable-length data referred to by regular instructions (for example,
+ variable-length data payloads, which are referred to by regular
+ instructions (for example,
<code>fill-array-data</code>). Such instructions must never be
encountered during the normal flow of execution. In addition, the
instructions must be located on even-numbered bytecode offsets (that is,
4-byte aligned). In order to meet this requirement, dex generation tools
- should emit an extra <code>nop</code> instruction as a spacer if such an
+ must emit an extra <code>nop</code> instruction as a spacer if such an
instruction would otherwise be unaligned. Finally, though not required,
it is expected that most tools will choose to emit these instructions at
the ends of methods, since otherwise it would likely be the case that
@@ -81,16 +91,18 @@
<li>Human-syntax and mnemonics:
<ul>
<li>Dest-then-source ordering for arguments.</li>
- <li>Some opcodes have a disambiguating suffix with respect to the type(s)
- they operate on: Type-general 64-bit opcodes
- are suffixed with <code>-wide</code>.
- Type-specific opcodes are suffixed with their type (or a
+ <li>Some opcodes have a disambiguating name suffix to indicate the type(s)
+ they operate on:
+ <ul>
+ <li>Type-general 32-bit opcodes are unmarked.</li>
+ <li>Type-general 64-bit opcodes are suffixed with <code>-wide</code>.</li>
+ <li>Type-specific opcodes are suffixed with their type (or a
straightforward abbreviation), one of: <code>-boolean</code>
<code>-byte</code> <code>-char</code> <code>-short</code>
<code>-int</code> <code>-long</code> <code>-float</code>
<code>-double</code> <code>-object</code> <code>-string</code>
- <code>-class</code> <code>-void</code>. Type-general 32-bit opcodes
- are unmarked.
+ <code>-class</code> <code>-void</code>.</li>
+ </ul>
</li>
<li>Some opcodes have a disambiguating suffix to distinguish
otherwise-identical operations that have different instruction layouts
@@ -99,6 +111,27 @@
mapping with static constants in the code that generates and interprets
executables (that is, to reduce ambiguity for humans).
</li>
+ <li>In the descriptions here, the width of a value (indicating, e.g., the
+ range of a constant or the number of registers possibly addressed) is
+ emphasized by the use of a character per four bits of width.
+ </li>
+ <li>For example, in the instruction
+ "<code>move-wide/from16 vAA, vBBBB</code>":
+ <ul>
+ <li>"<code>move</code>" is the base opcode, indicating the base operation
+ (move a register's value).</li>
+ <li>"<code>wide</code>" is the name suffix, indicating that it operates
+ on wide (64 bit) data.</li>
+ <li>"<code>from16</code>" is the opcode suffix, indicating a variant
+ that has a 16-bit register reference as a source.</li>
+ <li>"<code>vAA</code>" is the destination register (implied by the
+ operation; again, the rule is that destination arguments always come
+ first), which must be in the range <code>v0</code> –
+ <code>v255</code>.</li>
+ <li>"<code>vBBBB</code>" is the source register, which must be in the
+ range <code>v0</code> – <code>v65535</code>.</li>
+ </ul>
+ </li>
</ul>
</li>
<li>See the <a href="instruction-formats.html">instruction formats
@@ -106,6 +139,10 @@
(listed under "Op & Format") as well as details about the opcode
syntax.
</li>
+<li>See the <a href="dex-format.html"><code>.dex</code> file format
+ document</a> for more details about where the bytecode fits into
+ the bigger picture.
+</li>
</ul>
<h2>Summary of Instruction Set</h2>
@@ -124,7 +161,14 @@
<td>00 10x</td>
<td>nop</td>
<td> </td>
- <td>Waste cycles.</td>
+ <td>Waste cycles.
+ <p><b>Note:</b>
+ Data-bearing pseudo-instructions are tagged with this opcode, in which
+ case the high-order byte of the opcode unit indicates the nature of
+ the data. See "<code>packed-switch-payload</code> Format",
+ "<code>sparse-switch-payload</code> Format", and
+ "<code>fill-array-data-payload</code> Format" below.</p>
+ </td>
</tr>
<tr>
<td>01 12x</td>
@@ -237,7 +281,7 @@
<td>0d 11x</td>
<td>move-exception vAA</td>
<td><code>A:</code> destination register (8 bits)</td>
- <td>Save a just-caught exception into the given register. This should
+ <td>Save a just-caught exception into the given register. This must
be the first instruction of any exception handler whose caught
exception is not to be ignored, and this instruction must <i>only</i>
ever occur as the first instruction of an exception handler; anywhere
@@ -438,10 +482,12 @@
</tr>
<tr>
<td>24 35c</td>
- <td>filled-new-array {vD, vE, vF, vG, vA}, type@CCCC</td>
- <td><code>B:</code> array size and argument word count (4 bits)<br/>
- <code>C:</code> type index (16 bits)<br/>
- <code>D..G, A:</code> argument registers (4 bits each)</td>
+ <td>filled-new-array {vC, vD, vE, vF, vG}, type@BBBB</td>
+ <td>
+ <code>A:</code> array size and argument word count (4 bits)<br/>
+ <code>B:</code> type index (16 bits)<br/>
+ <code>C..G:</code> argument registers (4 bits each)
+ </td>
<td>Construct an array of the given type and size, filling it with the
supplied contents. The type must be an array type. The array's
contents must be single-word (that is,
@@ -466,7 +512,7 @@
<tr>
<td>26 31t</td>
<td>fill-array-data vAA, +BBBBBBBB <i>(with supplemental data as specified
- below in "<code>fill-array-data</code> Format")</i></td>
+ below in "<code>fill-array-data-payload</code> Format")</i></td>
<td><code>A:</code> array reference (8 bits)<br/>
<code>B:</code> signed "branch" offset to table data pseudo-instruction
(32 bits)
@@ -515,7 +561,7 @@
<tr>
<td>2b 31t</td>
<td>packed-switch vAA, +BBBBBBBB <i>(with supplemental data as
- specified below in "<code>packed-switch</code> Format")</i></td>
+ specified below in "<code>packed-switch-payload</code> Format")</i></td>
<td><code>A:</code> register to test<br/>
<code>B:</code> signed "branch" offset to table data pseudo-instruction
(32 bits)
@@ -529,7 +575,7 @@
<tr>
<td>2c 31t</td>
<td>sparse-switch vAA, +BBBBBBBB <i>(with supplemental data as
- specified below in "<code>sparse-switch</code> Format")</i></td>
+ specified below in "<code>sparse-switch-payload</code> Format")</i></td>
<td><code>A:</code> register to test<br/>
<code>B:</code> signed "branch" offset to table data pseudo-instruction
(32 bits)
@@ -698,16 +744,18 @@
</tr>
<tr>
<td>6e..72 35c</td>
- <td>invoke-<i>kind</i> {vD, vE, vF, vG, vA}, meth@CCCC<br/>
+ <td>invoke-<i>kind</i> {vC, vD, vE, vF, vG}, meth@BBBB<br/>
6e: invoke-virtual<br/>
6f: invoke-super<br/>
70: invoke-direct<br/>
71: invoke-static<br/>
72: invoke-interface
</td>
- <td><code>B:</code> argument word count (4 bits)<br/>
- <code>C:</code> method index (16 bits)<br/>
- <code>D..G, A:</code> argument registers (4 bits each)</td>
+ <td>
+ <code>A:</code> argument word count (4 bits)<br/>
+ <code>B:</code> method reference index (16 bits)<br/>
+ <code>C..G:</code> argument registers (4 bits each)
+ </td>
<td>Call the indicated method. The result (if any) may be stored
with an appropriate <code>move-result*</code> variant as the immediately
subsequent instruction.
@@ -749,7 +797,7 @@
78: invoke-interface/range
</td>
<td><code>A:</code> argument word count (8 bits)<br/>
- <code>B:</code> method index (16 bits)<br/>
+ <code>B:</code> method reference index (16 bits)<br/>
<code>C:</code> first argument register (16 bits)<br/>
<code>N = A + C - 1</code></td>
<td>Call the indicated method. See first <code>invoke-<i>kind</i></code>
@@ -935,7 +983,7 @@
</tbody>
</table>
-<h2><code>packed-switch</code> Format</h2>
+<h2><code>packed-switch-payload</code> Format</h2>
<table class="supplement">
<thead>
@@ -974,7 +1022,7 @@
<p><b>Note:</b> The total number of code units for an instance of this
table is <code>(size * 2) + 4</code>.</p>
-<h2><code>sparse-switch</code> Format</h2>
+<h2><code>sparse-switch-payload</code> Format</h2>
<table class="supplement">
<thead>
@@ -1014,7 +1062,7 @@
<p><b>Note:</b> The total number of code units for an instance of this
table is <code>(size * 4) + 2</code>.</p>
-<h2><code>fill-array-data</code> Format</h2>
+<h2><code>fill-array-data-payload</code> Format</h2>
<table class="supplement">
<thead>