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/instruction-formats.html b/src/tech/dalvik/instruction-formats.html
index d7bf690..f81b595 100644
--- a/src/tech/dalvik/instruction-formats.html
+++ b/src/tech/dalvik/instruction-formats.html
@@ -27,10 +27,17 @@
("<code>|</code>") interspersed to aid in reading. Uppercase letters
in sequence from "<code>A</code>" are used to indicate fields within
the format (which then get defined further by the syntax column). The term
-"<code>op</code>" is used to indicate the position of the eight-bit
-opcode within the format. A slashed zero ("<code>Ø</code>") is
-used to indicate that all bits should be zero in the indicated
-position.</p>
+"<code>op</code>" is used to indicate the position of an eight-bit
+opcode within the format. A slashed zero
+("<code>Ø</code>") is used to indicate that all bits must be
+zero in the indicated position.</p>
+
+<p>For the most part, lettering proceeds from earlier code units to
+later code units, and low-order to high-order within a code unit.
+However, there are a few exceptions to this general rule, which are
+done in order to make the naming of similar-meaning parts be the same
+across different instruction formats. These cases are noted explicitly
+in the format descriptions.</p>
<p>For example, the format "<code>B|A|<i>op</i> CCCC</code>" indicates
that the format consists of two 16-bit code units. The first word
@@ -44,7 +51,7 @@
for the format, which is used in other documents and in code to identify
the format.</p>
-<p>Format IDs consist of three characters, two digits followed by a
+<p>Most format IDs consist of three characters, two digits followed by a
letter. The first digit indicates the number of 16-bit code units in the
format. The second digit indicates the maximum number of registers that the
format contains (maximum, since some formats can accomodate a variable
@@ -54,8 +61,14 @@
format "<code>21t</code>" is of length two, contains one register reference,
and additionally contains a branch target.</p>
-<p>Suggested static linking formats have an additional "<code>s</code>" suffix,
-making them four characters total.</p>
+<p>Suggested static linking formats have an additional
+"<code>s</code>" suffix, making them four characters total. Similarly,
+suggested "inline" linking formats have an additional "<code>i</code>"
+suffix. (In this context, inline linking is like static linking,
+except with more direct ties into a virtual machine's implementation.)
+Finally, a couple oddball suggested formats (e.g.,
+"<code>20bc</code>") include two pieces of data which are both
+represented in its format ID.</p>
<p>The full list of typecode letters are as follows. Note that some
forms have different sizes, depending on the format:</p>
@@ -171,13 +184,13 @@
<p>Similar to the representation of constant pool indices, there are
also suggested (optional) forms that indicate prelinked offsets or
-indices. These prelinked values include "<code>vtaboff</code>"
-(vtable offset), "<code>fieldoff</code>" (field offset), and
-"<code>iface</code>" (interface pool index).</p>
+indices. There are two types of suggested prelinked value: vtable offsets
+(indicated as "<code>vtaboff</code>") and field offsets (indicated as
+"<code>fieldoff</code>").</p>
<p>In the cases where a format value isn't explictly part of the syntax
but instead picks a variant, each variant is listed with the prefix
-"<code>[<i>X</i>=<i>N</i>]</code>" (e.g., "<code>[B=2]</code>") to indicate
+"<code>[<i>X</i>=<i>N</i>]</code>" (e.g., "<code>[A=2]</code>") to indicate
the correspondence.</p>
<h2>The Formats</h2>
@@ -193,6 +206,13 @@
</thead>
<tbody>
<tr>
+ <td><i>N/A</i></td>
+ <td>00x</td>
+ <td><i><code>N/A</code></i></td>
+ <td><i>pseudo-format used for unused opcodes; suggested for use as the
+ nominal format for a breakpoint opcode</i></td>
+</tr>
+<tr>
<td>ØØ|<i>op</i></td>
<td>10x</td>
<td><i><code>op</code></i></td>
@@ -227,6 +247,14 @@
<td>goto/16</td>
</tr>
<tr>
+ <td>AA|<i>op</i> BBBB</td></td>
+ <td>20bc</td>
+ <td><i><code>op</code></i> AA, kind@BBBB</td>
+ <td><i>suggested format for statically determined verification errors;
+ A is the type of error and B is an index into a type-appropriate
+ table (e.g. method references for a no-such-method error)</i></td>
+</tr>
+<tr>
<td rowspan="5">AA|<i>op</i> BBBB</td>
<td>22x</td>
<td><i><code>op</code></i> vAA, vBBBB</td>
@@ -292,8 +320,8 @@
<tr>
<td>22cs</td>
<td><i><code>op</code></i> vA, vB, fieldoff@CCCC</td>
- <td><i>(suggested format for statically linked field access instructions of
- format 22c)</i>
+ <td><i>suggested format for statically linked field access instructions of
+ format 22c</i>
</td>
</tr>
<tr>
@@ -325,96 +353,99 @@
<td>const-string/jumbo</td>
</tr>
<tr>
- <td>B|A|<i>op</i> CCCC G|F|E|D</td>
+ <td rowspan="3">A|G|<i>op</i> BBBB F|E|D|C</td>
<td>35c</td>
- <td><i>[<code>B=5</code>] <code>op</code></i> {vD, vE, vF, vG, vA},
- meth@CCCC<br/>
- <i>[<code>B=5</code>] <code>op</code></i> {vD, vE, vF, vG, vA},
- type@CCCC<br/>
- <i>[<code>B=4</code>] <code>op</code></i> {vD, vE, vF, vG},
- <i><code>kind</code></i>@CCCC<br/>
- <i>[<code>B=3</code>] <code>op</code></i> {vD, vE, vF},
- <i><code>kind</code></i>@CCCC<br/>
- <i>[<code>B=2</code>] <code>op</code></i> {vD, vE},
- <i><code>kind</code></i>@CCCC<br/>
- <i>[<code>B=1</code>] <code>op</code></i> {vD},
- <i><code>kind</code></i>@CCCC<br/>
- <i>[<code>B=0</code>] <code>op</code></i> {},
- <i><code>kind</code></i>@CCCC
+ <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},
+ type@BBBB<br/>
+ <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF},
+ <i><code>kind</code></i>@BBBB<br/>
+ <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE},
+ <i><code>kind</code></i>@BBBB<br/>
+ <i>[<code>A=2</code>] <code>op</code></i> {vC, vD},
+ <i><code>kind</code></i>@BBBB<br/>
+ <i>[<code>A=1</code>] <code>op</code></i> {vC},
+ <i><code>kind</code></i>@BBBB<br/>
+ <i>[<code>A=0</code>] <code>op</code></i> {},
+ <i><code>kind</code></i>@BBBB<br/>
+ <p><i>The unusual choice in lettering here reflects a desire to make
+ the count and the reference index have the same label as in format
+ 3rc.</i></p>
</td>
<td> </td>
</tr>
<tr>
- <td>B|A|<i>op</i> CCCC G|F|E|D</td>
<td>35ms</td>
-
- <td><i>[<code>B=5</code>] <code>op</code></i> {vD, vE, vF, vG, vA},
- vtaboff@CCCC<br/>
- <i>[<code>B=4</code>] <code>op</code></i> {vD, vE, vF, vG},
- vtaboff@CCCC<br/>
- <i>[<code>B=3</code>] <code>op</code></i> {vD, vE, vF},
- vtaboff@CCCC<br/>
- <i>[<code>B=2</code>] <code>op</code></i> {vD, vE},
- vtaboff@CCCC<br/>
- <i>[<code>B=1</code>] <code>op</code></i> {vD},
- vtaboff@CCCC<br/>
+ <td><i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG},
+ vtaboff@BBBB<br/>
+ <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF},
+ vtaboff@BBBB<br/>
+ <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE},
+ vtaboff@BBBB<br/>
+ <i>[<code>A=2</code>] <code>op</code></i> {vC, vD},
+ vtaboff@BBBB<br/>
+ <i>[<code>A=1</code>] <code>op</code></i> {vC},
+ vtaboff@BBBB<br/>
+ <p><i>The unusual choice in lettering here reflects a desire to make
+ the count and the reference index have the same label as in format
+ 3rms.</i></p>
</td>
- <td><i>(suggested format for statically linked <code>invoke-virtual</code>
- and <code>invoke-super</code> instructions of format 35c)</i>
+ <td><i>suggested format for statically linked <code>invoke-virtual</code>
+ and <code>invoke-super</code> instructions of format 35c</i>
</td>
</tr>
<tr>
- <td>B|A|<i>op</i> DDCC H|G|F|E</td>
- <td>35fs</td>
- <td><i>[<code>B=5</code>] <code>op</code></i> {vE, vF, vG, vH, vA},
- vtaboff@CC, iface@DD<br/>
- <i>[<code>B=4</code>] <code>op</code></i> {vE, vF, vG, vH},
- vtaboff@CC, iface@DD<br/>
- <i>[<code>B=3</code>] <code>op</code></i> {vE, vF, vG},
- vtaboff@CC, iface@DD<br/>
- <i>[<code>B=2</code>] <code>op</code></i> {vE, vF},
- vtaboff@CC, iface@DD<br/>
- <i>[<code>B=1</code>] <code>op</code></i> {vE},
- vtaboff@CC, iface@DD<br/>
+ <td>35mi</td>
+ <td><i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG},
+ inline@BBBB<br/>
+ <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF},
+ inline@BBBB<br/>
+ <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE},
+ inline@BBBB<br/>
+ <i>[<code>A=2</code>] <code>op</code></i> {vC, vD},
+ inline@BBBB<br/>
+ <i>[<code>A=1</code>] <code>op</code></i> {vC},
+ inline@BBBB<br/>
+ <p><i>The unusual choice in lettering here reflects a desire to make
+ the count and the reference index have the same label as in format
+ 3rmi.</i></p>
</td>
- <td><i>(suggested format for statically linked <code>invoke-interface</code>
- instructions of format 35c)</i>
+ <td><i>suggested format for inline linked <code>invoke-static</code>
+ and <code>invoke-virtual</code> instructions of format 35c</i>
</td>
</tr>
<tr>
- <td>AA|<i>op</i> BBBB CCCC</td>
+ <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}, type@BBBB<br/>
- <p><i>(where <code>NNNN = CCCC+AA-1</code>, that is <code>A</code>
+ <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>
- determines the first register)</i></p>
+ determines the first register</i></p>
</td>
<td> </td>
</tr>
<tr>
- <td>AA|<i>op</i> BBBB CCCC</td>
<td>3rms</td>
<td><i><code>op</code></i> {vCCCC .. vNNNN}, vtaboff@BBBB<br/>
- <p><i>(where <code>NNNN = CCCC+AA-1</code>, that is <code>A</code>
+ <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>
- determines the first register)</i></p>
+ determines the first register</i></p>
</td>
- <td><i>(suggested format for statically linked <code>invoke-virtual</code>
- and <code>invoke-super</code> instructions of format <code>3rc</code>)</i>
+ <td><i>suggested format for statically linked <code>invoke-virtual</code>
+ and <code>invoke-super</code> instructions of format <code>3rc</code></i>
</td>
</tr>
<tr>
- <td>AA|<i>op</i> CCBB DDDD</td>
- <td>3rfs</td>
- <td><i><code>op</code></i> {vDDDD .. vNNNN}, vtaboff@BB,
- iface@CC<br/>
- <p><i>(where <code>NNNN = DDDD+AA-1</code>, that is <code>A</code>
- determines the count <code>0..255</code>, and <code>D</code>
- determines the first register)</i></p>
+ <td>3rmi</td>
+ <td><i><code>op</code></i> {vCCCC .. vNNNN}, inline@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>
+ determines the first register</i></p>
</td>
- <td><i>(suggested format for statically linked <code>invoke-interface</code>
- instructions of format <code>3rc</code>)</i>
+ <td><i>suggested format for inline linked <code>invoke-static</code>
+ and <code>invoke-virtual</code> instructions of format 3rc</i>
</td>
</tr>
<tr>