blob: f018fa31fd8f60084d106046fb8c42a459014017 [file] [log] [blame]
Clay Murphye4edda62014-10-16 19:00:15 -07001page.title=Dalvik bytecode
Robert Ly35f2fda2013-01-29 16:27:05 -08002@jd:body
Dan Bornstein25705bc2011-04-12 16:23:13 -07003
Robert Ly35f2fda2013-01-29 16:27:05 -08004<!--
Clay Murphye4edda62014-10-16 19:00:15 -07005 Copyright 2014 The Android Open Source Project
Dan Bornstein25705bc2011-04-12 16:23:13 -07006
Robert Ly35f2fda2013-01-29 16:27:05 -08007 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
Dan Bornstein25705bc2011-04-12 16:23:13 -070010
Robert Ly35f2fda2013-01-29 16:27:05 -080011 http://www.apache.org/licenses/LICENSE-2.0
Dan Bornstein25705bc2011-04-12 16:23:13 -070012
Robert Ly35f2fda2013-01-29 16:27:05 -080013 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18-->
Clay Murphye4edda62014-10-16 19:00:15 -070019<div id="qv-wrapper">
20 <div id="qv">
21 <h2>In this document</h2>
22 <ol id="auto-toc">
23 </ol>
24 </div>
25</div>
26
27<h2 id="design">General design</h2>
Dan Bornstein25705bc2011-04-12 16:23:13 -070028
29<ul>
30<li>The machine model and calling conventions are meant to approximately
31 imitate common real architectures and C-style calling conventions:
32 <ul>
Clay Murphye4edda62014-10-16 19:00:15 -070033 <li>The machine is register-based, and frames are fixed in size upon creation.
Dan Bornstein25705bc2011-04-12 16:23:13 -070034 Each frame consists of a particular number of registers (specified by
35 the method) as well as any adjunct data needed to execute the method,
36 such as (but not limited to) the program counter and a reference to the
37 <code>.dex</code> file that contains the method.
38 </li>
Elliott Hughes8d777942012-01-05 17:27:02 -080039 <li>When used for bit values (such as integers and floating point
40 numbers), registers are considered 32 bits wide. Adjacent register
41 pairs are used for 64-bit values. There is no alignment requirement
42 for register pairs.
43 </li>
44 <li>When used for object references, registers are considered wide enough
45 to hold exactly one such reference.
Dan Bornstein25705bc2011-04-12 16:23:13 -070046 </li>
47 <li>In terms of bitwise representation, <code>(Object) null == (int)
48 0</code>.
49 </li>
50 <li>The <i>N</i> arguments to a method land in the last <i>N</i> registers
51 of the method's invocation frame, in order. Wide arguments consume
52 two registers. Instance methods are passed a <code>this</code> reference
53 as their first argument.
54 </li>
55 </ul>
56<li>The storage unit in the instruction stream is a 16-bit unsigned quantity.
57 Some bits in some instructions are ignored / must-be-zero.
58</li>
59<li>Instructions aren't gratuitously limited to a particular type. For
60 example, instructions that move 32-bit register values without interpretation
61 don't have to specify whether they are moving ints or floats.
62</li>
63<li>There are separately enumerated and indexed constant pools for
64 references to strings, types, fields, and methods.
65</li>
66<li>Bitwise literal data is represented in-line in the instruction stream.</li>
67<li>Because, in practice, it is uncommon for a method to need more than
68 16 registers, and because needing more than eight registers <i>is</i>
69 reasonably common, many instructions are limited to only addressing
70 the first 16
71 registers. When reasonably possible, instructions allow references to
Elliott Hughes8d777942012-01-05 17:27:02 -080072 up to the first 256 registers. In addition, some instructions have variants
73 that allow for much larger register counts, including a pair of catch-all
74 <code>move</code> instructions that can address registers in the range
75 <code>v0</code> &ndash; <code>v65535</code>.
76 In cases where an instruction variant isn't
Dan Bornstein25705bc2011-04-12 16:23:13 -070077 available to address a desired register, it is expected that the register
78 contents get moved from the original register to a low register (before the
79 operation) and/or moved from a low result register to a high register
80 (after the operation).
81</li>
82<li>There are several "pseudo-instructions" that are used to hold
Elliott Hughes8d777942012-01-05 17:27:02 -080083 variable-length data payloads, which are referred to by regular
84 instructions (for example,
Dan Bornstein25705bc2011-04-12 16:23:13 -070085 <code>fill-array-data</code>). Such instructions must never be
86 encountered during the normal flow of execution. In addition, the
87 instructions must be located on even-numbered bytecode offsets (that is,
88 4-byte aligned). In order to meet this requirement, dex generation tools
Elliott Hughes8d777942012-01-05 17:27:02 -080089 must emit an extra <code>nop</code> instruction as a spacer if such an
Dan Bornstein25705bc2011-04-12 16:23:13 -070090 instruction would otherwise be unaligned. Finally, though not required,
91 it is expected that most tools will choose to emit these instructions at
92 the ends of methods, since otherwise it would likely be the case that
93 additional instructions would be needed to branch around them.
94</li>
95<li>When installed on a running system, some instructions may be altered,
96 changing their format, as an install-time static linking optimization.
97 This is to allow for faster execution once linkage is known.
98 See the associated
99 <a href="instruction-formats.html">instruction formats document</a>
100 for the suggested variants. The word "suggested" is used advisedly;
101 it is not mandatory to implement these.
102</li>
103<li>Human-syntax and mnemonics:
104 <ul>
105 <li>Dest-then-source ordering for arguments.</li>
Elliott Hughes8d777942012-01-05 17:27:02 -0800106 <li>Some opcodes have a disambiguating name suffix to indicate the type(s)
107 they operate on:
108 <ul>
109 <li>Type-general 32-bit opcodes are unmarked.</li>
110 <li>Type-general 64-bit opcodes are suffixed with <code>-wide</code>.</li>
111 <li>Type-specific opcodes are suffixed with their type (or a
Dan Bornstein25705bc2011-04-12 16:23:13 -0700112 straightforward abbreviation), one of: <code>-boolean</code>
113 <code>-byte</code> <code>-char</code> <code>-short</code>
114 <code>-int</code> <code>-long</code> <code>-float</code>
115 <code>-double</code> <code>-object</code> <code>-string</code>
Elliott Hughes8d777942012-01-05 17:27:02 -0800116 <code>-class</code> <code>-void</code>.</li>
117 </ul>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700118 </li>
119 <li>Some opcodes have a disambiguating suffix to distinguish
120 otherwise-identical operations that have different instruction layouts
121 or options. These suffixes are separated from the main names with a slash
122 ("<code>/</code>") and mainly exist at all to make there be a one-to-one
123 mapping with static constants in the code that generates and interprets
124 executables (that is, to reduce ambiguity for humans).
125 </li>
Elliott Hughes8d777942012-01-05 17:27:02 -0800126 <li>In the descriptions here, the width of a value (indicating, e.g., the
127 range of a constant or the number of registers possibly addressed) is
128 emphasized by the use of a character per four bits of width.
129 </li>
130 <li>For example, in the instruction
131 "<code>move-wide/from16 vAA, vBBBB</code>":
132 <ul>
133 <li>"<code>move</code>" is the base opcode, indicating the base operation
134 (move a register's value).</li>
135 <li>"<code>wide</code>" is the name suffix, indicating that it operates
136 on wide (64 bit) data.</li>
137 <li>"<code>from16</code>" is the opcode suffix, indicating a variant
138 that has a 16-bit register reference as a source.</li>
139 <li>"<code>vAA</code>" is the destination register (implied by the
140 operation; again, the rule is that destination arguments always come
141 first), which must be in the range <code>v0</code> &ndash;
142 <code>v255</code>.</li>
143 <li>"<code>vBBBB</code>" is the source register, which must be in the
144 range <code>v0</code> &ndash; <code>v65535</code>.</li>
145 </ul>
146 </li>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700147 </ul>
148</li>
149<li>See the <a href="instruction-formats.html">instruction formats
150 document</a> for more details about the various instruction formats
151 (listed under "Op &amp; Format") as well as details about the opcode
152 syntax.
153</li>
Elliott Hughes8d777942012-01-05 17:27:02 -0800154<li>See the <a href="dex-format.html"><code>.dex</code> file format
155 document</a> for more details about where the bytecode fits into
156 the bigger picture.
157</li>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700158</ul>
159
Clay Murphye4edda62014-10-16 19:00:15 -0700160<h2 id="instructions">Summary of bytecode set</h2>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700161
162<table class="instruc">
163<thead>
164<tr>
165 <th>Op &amp; Format</th>
166 <th>Mnemonic / Syntax</th>
167 <th>Arguments</th>
168 <th>Description</th>
169</tr>
170</thead>
171<tbody>
172<tr>
173 <td>00 10x</td>
174 <td>nop</td>
175 <td>&nbsp;</td>
Elliott Hughes8d777942012-01-05 17:27:02 -0800176 <td>Waste cycles.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700177 <p class="note"><strong>Note:</strong>
Elliott Hughes8d777942012-01-05 17:27:02 -0800178 Data-bearing pseudo-instructions are tagged with this opcode, in which
179 case the high-order byte of the opcode unit indicates the nature of
180 the data. See "<code>packed-switch-payload</code> Format",
181 "<code>sparse-switch-payload</code> Format", and
182 "<code>fill-array-data-payload</code> Format" below.</p>
183 </td>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700184</tr>
185<tr>
186 <td>01 12x</td>
187 <td>move vA, vB</td>
188 <td><code>A:</code> destination register (4 bits)<br/>
189 <code>B:</code> source register (4 bits)</td>
190 <td>Move the contents of one non-object register to another.</td>
191</tr>
192<tr>
193 <td>02 22x</td>
194 <td>move/from16 vAA, vBBBB</td>
195 <td><code>A:</code> destination register (8 bits)<br/>
196 <code>B:</code> source register (16 bits)</td>
197 <td>Move the contents of one non-object register to another.</td>
198</tr>
199<tr>
200 <td>03 32x</td>
201 <td>move/16 vAAAA, vBBBB</td>
202 <td><code>A:</code> destination register (16 bits)<br/>
203 <code>B:</code> source register (16 bits)</td>
204 <td>Move the contents of one non-object register to another.</td>
205</tr>
206<tr>
207 <td>04 12x</td>
208 <td>move-wide vA, vB</td>
209 <td><code>A:</code> destination register pair (4 bits)<br/>
210 <code>B:</code> source register pair (4 bits)</td>
211 <td>Move the contents of one register-pair to another.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700212 <p class="note"><strong>Note:</strong>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700213 It is legal to move from <code>v<i>N</i></code> to either
214 <code>v<i>N-1</i></code> or <code>v<i>N+1</i></code>, so implementations
215 must arrange for both halves of a register pair to be read before
216 anything is written.</p>
217 </td>
218</tr>
219<tr>
220 <td>05 22x</td>
221 <td>move-wide/from16 vAA, vBBBB</td>
222 <td><code>A:</code> destination register pair (8 bits)<br/>
223 <code>B:</code> source register pair (16 bits)</td>
224 <td>Move the contents of one register-pair to another.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700225 <p class="note"><strong>Note:</strong>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700226 Implementation considerations are the same as <code>move-wide</code>,
227 above.</p>
228 </td>
229</tr>
230<tr>
231 <td>06 32x</td>
232 <td>move-wide/16 vAAAA, vBBBB</td>
233 <td><code>A:</code> destination register pair (16 bits)<br/>
234 <code>B:</code> source register pair (16 bits)</td>
235 <td>Move the contents of one register-pair to another.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700236 <p class="note"><strong>Note:</strong>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700237 Implementation considerations are the same as <code>move-wide</code>,
238 above.</p>
239 </td>
240</tr>
241<tr>
242 <td>07 12x</td>
243 <td>move-object vA, vB</td>
244 <td><code>A:</code> destination register (4 bits)<br/>
245 <code>B:</code> source register (4 bits)</td>
246 <td>Move the contents of one object-bearing register to another.</td>
247</tr>
248<tr>
249 <td>08 22x</td>
250 <td>move-object/from16 vAA, vBBBB</td>
251 <td><code>A:</code> destination register (8 bits)<br/>
252 <code>B:</code> source register (16 bits)</td>
253 <td>Move the contents of one object-bearing register to another.</td>
254</tr>
255<tr>
256 <td>09 32x</td>
257 <td>move-object/16 vAAAA, vBBBB</td>
258 <td><code>A:</code> destination register (16 bits)<br/>
259 <code>B:</code> source register (16 bits)</td>
260 <td>Move the contents of one object-bearing register to another.</td>
261</tr>
262<tr>
263 <td>0a 11x</td>
264 <td>move-result vAA</td>
265 <td><code>A:</code> destination register (8 bits)</td>
266 <td>Move the single-word non-object result of the most recent
267 <code>invoke-<i>kind</i></code> into the indicated register.
268 This must be done as the instruction immediately after an
269 <code>invoke-<i>kind</i></code> whose (single-word, non-object) result
270 is not to be ignored; anywhere else is invalid.</td>
271</tr>
272<tr>
273 <td>0b 11x</td>
274 <td>move-result-wide vAA</td>
275 <td><code>A:</code> destination register pair (8 bits)</td>
276 <td>Move the double-word result of the most recent
277 <code>invoke-<i>kind</i></code> into the indicated register pair.
278 This must be done as the instruction immediately after an
279 <code>invoke-<i>kind</i></code> whose (double-word) result
280 is not to be ignored; anywhere else is invalid.</td>
281</tr>
282<tr>
283 <td>0c 11x</td>
284 <td>move-result-object vAA</td>
285 <td><code>A:</code> destination register (8 bits)</td>
286 <td>Move the object result of the most recent <code>invoke-<i>kind</i></code>
287 into the indicated register. This must be done as the instruction
288 immediately after an <code>invoke-<i>kind</i></code> or
289 <code>filled-new-array</code>
290 whose (object) result is not to be ignored; anywhere else is invalid.</td>
291</tr>
292<tr>
293 <td>0d 11x</td>
294 <td>move-exception vAA</td>
295 <td><code>A:</code> destination register (8 bits)</td>
Elliott Hughes8d777942012-01-05 17:27:02 -0800296 <td>Save a just-caught exception into the given register. This must
Dan Bornstein25705bc2011-04-12 16:23:13 -0700297 be the first instruction of any exception handler whose caught
298 exception is not to be ignored, and this instruction must <i>only</i>
299 ever occur as the first instruction of an exception handler; anywhere
300 else is invalid.</td>
301</tr>
302<tr>
303 <td>0e 10x</td>
304 <td>return-void</td>
305 <td>&nbsp;</td>
306 <td>Return from a <code>void</code> method.</td>
307</tr>
308<tr>
309 <td>0f 11x</td>
310 <td>return vAA</td>
311 <td><code>A:</code> return value register (8 bits)</td>
312 <td>Return from a single-width (32-bit) non-object value-returning
313 method.
314 </td>
315</tr>
316<tr>
317 <td>10 11x</td>
318 <td>return-wide vAA</td>
319 <td><code>A:</code> return value register-pair (8 bits)</td>
320 <td>Return from a double-width (64-bit) value-returning method.</td>
321</tr>
322<tr>
323 <td>11 11x</td>
324 <td>return-object vAA</td>
325 <td><code>A:</code> return value register (8 bits)</td>
326 <td>Return from an object-returning method.</td>
327</tr>
328<tr>
329 <td>12 11n</td>
330 <td>const/4 vA, #+B</td>
331 <td><code>A:</code> destination register (4 bits)<br/>
332 <code>B:</code> signed int (4 bits)</td>
333 <td>Move the given literal value (sign-extended to 32 bits) into
334 the specified register.</td>
335</tr>
336<tr>
337 <td>13 21s</td>
338 <td>const/16 vAA, #+BBBB</td>
339 <td><code>A:</code> destination register (8 bits)<br/>
340 <code>B:</code> signed int (16 bits)</td>
341 <td>Move the given literal value (sign-extended to 32 bits) into
342 the specified register.</td>
343</tr>
344<tr>
345 <td>14 31i</td>
346 <td>const vAA, #+BBBBBBBB</td>
347 <td><code>A:</code> destination register (8 bits)<br/>
348 <code>B:</code> arbitrary 32-bit constant</td>
349 <td>Move the given literal value into the specified register.</td>
350</tr>
351<tr>
352 <td>15 21h</td>
353 <td>const/high16 vAA, #+BBBB0000</td>
354 <td><code>A:</code> destination register (8 bits)<br/>
355 <code>B:</code> signed int (16 bits)</td>
356 <td>Move the given literal value (right-zero-extended to 32 bits) into
357 the specified register.</td>
358</tr>
359<tr>
360 <td>16 21s</td>
361 <td>const-wide/16 vAA, #+BBBB</td>
362 <td><code>A:</code> destination register (8 bits)<br/>
363 <code>B:</code> signed int (16 bits)</td>
364 <td>Move the given literal value (sign-extended to 64 bits) into
365 the specified register-pair.</td>
366</tr>
367<tr>
368 <td>17 31i</td>
369 <td>const-wide/32 vAA, #+BBBBBBBB</td>
370 <td><code>A:</code> destination register (8 bits)<br/>
371 <code>B:</code> signed int (32 bits)</td>
372 <td>Move the given literal value (sign-extended to 64 bits) into
373 the specified register-pair.</td>
374</tr>
375<tr>
376 <td>18 51l</td>
377 <td>const-wide vAA, #+BBBBBBBBBBBBBBBB</td>
378 <td><code>A:</code> destination register (8 bits)<br/>
379 <code>B:</code> arbitrary double-width (64-bit) constant</td>
380 <td>Move the given literal value into
381 the specified register-pair.</td>
382</tr>
383<tr>
384 <td>19 21h</td>
385 <td>const-wide/high16 vAA, #+BBBB000000000000</td>
386 <td><code>A:</code> destination register (8 bits)<br/>
387 <code>B:</code> signed int (16 bits)</td>
388 <td>Move the given literal value (right-zero-extended to 64 bits) into
389 the specified register-pair.</td>
390</tr>
391<tr>
392 <td>1a 21c</td>
393 <td>const-string vAA, string@BBBB</td>
394 <td><code>A:</code> destination register (8 bits)<br/>
395 <code>B:</code> string index</td>
396 <td>Move a reference to the string specified by the given index into the
397 specified register.</td>
398</tr>
399<tr>
400 <td>1b 31c</td>
401 <td>const-string/jumbo vAA, string@BBBBBBBB</td>
402 <td><code>A:</code> destination register (8 bits)<br/>
403 <code>B:</code> string index</td>
404 <td>Move a reference to the string specified by the given index into the
405 specified register.</td>
406</tr>
407<tr>
408 <td>1c 21c</td>
409 <td>const-class vAA, type@BBBB</td>
410 <td><code>A:</code> destination register (8 bits)<br/>
411 <code>B:</code> type index</td>
412 <td>Move a reference to the class specified by the given index into the
413 specified register. In the case where the indicated type is primitive,
414 this will store a reference to the primitive type's degenerate
415 class.</td>
416</tr>
417<tr>
418 <td>1d 11x</td>
419 <td>monitor-enter vAA</td>
420 <td><code>A:</code> reference-bearing register (8 bits)</td>
421 <td>Acquire the monitor for the indicated object.</td>
422</tr>
423<tr>
424 <td>1e 11x</td>
425 <td>monitor-exit vAA</td>
426 <td><code>A:</code> reference-bearing register (8 bits)</td>
427 <td>Release the monitor for the indicated object.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700428 <p class="note"><strong>Note:</strong>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700429 If this instruction needs to throw an exception, it must do
430 so as if the pc has already advanced past the instruction.
431 It may be useful to think of this as the instruction successfully
432 executing (in a sense), and the exception getting thrown <i>after</i>
433 the instruction but <i>before</i> the next one gets a chance to
434 run. This definition makes it possible for a method to use
435 a monitor cleanup catch-all (e.g., <code>finally</code>) block as
436 the monitor cleanup for that block itself, as a way to handle the
437 arbitrary exceptions that might get thrown due to the historical
438 implementation of <code>Thread.stop()</code>, while still managing
439 to have proper monitor hygiene.</p>
440 </td>
441</tr>
442<tr>
443 <td>1f 21c</td>
444 <td>check-cast vAA, type@BBBB</td>
445 <td><code>A:</code> reference-bearing register (8 bits)<br/>
446 <code>B:</code> type index (16 bits)</td>
447 <td>Throw a <code>ClassCastException</code> if the reference in the
448 given register cannot be cast to the indicated type.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700449 <p class="note"><strong>Note:</strong> Since <code>A</code> must always be a reference
Dan Bornstein25705bc2011-04-12 16:23:13 -0700450 (and not a primitive value), this will necessarily fail at runtime
451 (that is, it will throw an exception) if <code>B</code> refers to a
452 primitive type.</p>
453 </td>
454</tr>
455<tr>
456 <td>20 22c</td>
457 <td>instance-of vA, vB, type@CCCC</td>
458 <td><code>A:</code> destination register (4 bits)<br/>
459 <code>B:</code> reference-bearing register (4 bits)<br/>
460 <code>C:</code> type index (16 bits)</td>
461 <td>Store in the given destination register <code>1</code>
462 if the indicated reference is an instance of the given type,
463 or <code>0</code> if not.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700464 <p class="note"><strong>Note:</strong> Since <code>B</code> must always be a reference
Dan Bornstein25705bc2011-04-12 16:23:13 -0700465 (and not a primitive value), this will always result
466 in <code>0</code> being stored if <code>C</code> refers to a primitive
467 type.</td>
468</tr>
469<tr>
470 <td>21 12x</td>
471 <td>array-length vA, vB</td>
472 <td><code>A:</code> destination register (4 bits)<br/>
473 <code>B:</code> array reference-bearing register (4 bits)</td>
474 <td>Store in the given destination register the length of the indicated
475 array, in entries</td>
476</tr>
477<tr>
478 <td>22 21c</td>
479 <td>new-instance vAA, type@BBBB</td>
480 <td><code>A:</code> destination register (8 bits)<br/>
481 <code>B:</code> type index</td>
482 <td>Construct a new instance of the indicated type, storing a
483 reference to it in the destination. The type must refer to a
484 non-array class.</td>
485</tr>
486<tr>
487 <td>23 22c</td>
488 <td>new-array vA, vB, type@CCCC</td>
489 <td><code>A:</code> destination register (8 bits)<br/>
490 <code>B:</code> size register<br/>
491 <code>C:</code> type index</td>
492 <td>Construct a new array of the indicated type and size. The type
493 must be an array type.</td>
494</tr>
495<tr>
496 <td>24 35c</td>
Elliott Hughes8d777942012-01-05 17:27:02 -0800497 <td>filled-new-array {vC, vD, vE, vF, vG}, type@BBBB</td>
498 <td>
499 <code>A:</code> array size and argument word count (4 bits)<br/>
500 <code>B:</code> type index (16 bits)<br/>
501 <code>C..G:</code> argument registers (4 bits each)
502 </td>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700503 <td>Construct an array of the given type and size, filling it with the
504 supplied contents. The type must be an array type. The array's
505 contents must be single-word (that is,
506 no arrays of <code>long</code> or <code>double</code>, but reference
507 types are acceptable). The constructed
508 instance is stored as a "result" in the same way that the method invocation
509 instructions store their results, so the constructed instance must
510 be moved to a register with an immediately subsequent
511 <code>move-result-object</code> instruction (if it is to be used).</td>
512</tr>
513<tr>
514 <td>25 3rc</td>
515 <td>filled-new-array/range {vCCCC .. vNNNN}, type@BBBB</td>
516 <td><code>A:</code> array size and argument word count (8 bits)<br/>
517 <code>B:</code> type index (16 bits)<br/>
518 <code>C:</code> first argument register (16 bits)<br/>
519 <code>N = A + C - 1</code></td>
520 <td>Construct an array of the given type and size, filling it with
521 the supplied contents. Clarifications and restrictions are the same
522 as <code>filled-new-array</code>, described above.</td>
523</tr>
524<tr>
525 <td>26 31t</td>
526 <td>fill-array-data vAA, +BBBBBBBB <i>(with supplemental data as specified
Elliott Hughes8d777942012-01-05 17:27:02 -0800527 below in "<code>fill-array-data-payload</code> Format")</i></td>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700528 <td><code>A:</code> array reference (8 bits)<br/>
529 <code>B:</code> signed "branch" offset to table data pseudo-instruction
530 (32 bits)
531 </td>
532 <td>Fill the given array with the indicated data. The reference must be
533 to an array of primitives, and the data table must match it in type and
534 must contain no more elements than will fit in the array. That is,
535 the array may be larger than the table, and if so, only the initial
536 elements of the array are set, leaving the remainder alone.
537 </td>
538</tr>
539<tr>
540 <td>27 11x</td>
541 <td>throw vAA</td>
542 <td><code>A:</code> exception-bearing register (8 bits)<br/></td>
543 <td>Throw the indicated exception.</td>
544</tr>
545<tr>
546 <td>28 10t</td>
547 <td>goto +AA</td>
548 <td><code>A:</code> signed branch offset (8 bits)</td>
549 <td>Unconditionally jump to the indicated instruction.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700550 <p class="note"><strong>Note:</strong>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700551 The branch offset must not be <code>0</code>. (A spin
552 loop may be legally constructed either with <code>goto/32</code> or
553 by including a <code>nop</code> as a target before the branch.)</p>
554 </td>
555</tr>
556<tr>
557 <td>29 20t</td>
558 <td>goto/16 +AAAA</td>
559 <td><code>A:</code> signed branch offset (16 bits)<br/></td>
560 <td>Unconditionally jump to the indicated instruction.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700561 <p class="note"><strong>Note:</strong>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700562 The branch offset must not be <code>0</code>. (A spin
563 loop may be legally constructed either with <code>goto/32</code> or
564 by including a <code>nop</code> as a target before the branch.)</p>
565 </td>
566</tr>
567<tr>
568 <td>2a 30t</td>
569 <td>goto/32 +AAAAAAAA</td>
570 <td><code>A:</code> signed branch offset (32 bits)<br/></td>
571 <td>Unconditionally jump to the indicated instruction.</td>
572</tr>
573<tr>
574 <td>2b 31t</td>
575 <td>packed-switch vAA, +BBBBBBBB <i>(with supplemental data as
Elliott Hughes8d777942012-01-05 17:27:02 -0800576 specified below in "<code>packed-switch-payload</code> Format")</i></td>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700577 <td><code>A:</code> register to test<br/>
578 <code>B:</code> signed "branch" offset to table data pseudo-instruction
579 (32 bits)
580 </td>
581 <td>Jump to a new instruction based on the value in the
582 given register, using a table of offsets corresponding to each value
583 in a particular integral range, or fall through to the next
584 instruction if there is no match.
585 </td>
586</tr>
587<tr>
588 <td>2c 31t</td>
589 <td>sparse-switch vAA, +BBBBBBBB <i>(with supplemental data as
Elliott Hughes8d777942012-01-05 17:27:02 -0800590 specified below in "<code>sparse-switch-payload</code> Format")</i></td>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700591 <td><code>A:</code> register to test<br/>
592 <code>B:</code> signed "branch" offset to table data pseudo-instruction
593 (32 bits)
594 </td>
595 <td>Jump to a new instruction based on the value in the given
596 register, using an ordered table of value-offset pairs, or fall
597 through to the next instruction if there is no match.
598 </td>
599</tr>
600<tr>
601 <td>2d..31 23x</td>
602 <td>cmp<i>kind</i> vAA, vBB, vCC<br/>
603 2d: cmpl-float <i>(lt bias)</i><br/>
604 2e: cmpg-float <i>(gt bias)</i><br/>
605 2f: cmpl-double <i>(lt bias)</i><br/>
606 30: cmpg-double <i>(gt bias)</i><br/>
607 31: cmp-long
608 </td>
609 <td><code>A:</code> destination register (8 bits)<br/>
610 <code>B:</code> first source register or pair<br/>
611 <code>C:</code> second source register or pair</td>
612 <td>Perform the indicated floating point or <code>long</code> comparison,
Elliott Hughes3e381e32012-07-30 16:05:39 -0700613 setting <code>a</code> to <code>0</code> if <code>b == c</code>,
614 <code>1</code> if <code>b &gt; c</code>,
615 or <code>-1</code> if <code>b &lt; c</code>.
616 The "bias" listed for the floating point operations
617 indicates how <code>NaN</code> comparisons are treated: "gt bias"
Dan Bornstein25705bc2011-04-12 16:23:13 -0700618 instructions return <code>1</code> for <code>NaN</code> comparisons,
Elliott Hughes3e381e32012-07-30 16:05:39 -0700619 and "lt bias" instructions return <code>-1</code>.
Dan Bornstein25705bc2011-04-12 16:23:13 -0700620 <p>For example, to check to see if floating point
Elliott Hughes3e381e32012-07-30 16:05:39 -0700621 <code>x &lt; y</code> it is advisable to use
Dan Bornstein25705bc2011-04-12 16:23:13 -0700622 <code>cmpg-float</code>; a result of <code>-1</code> indicates that
623 the test was true, and the other values indicate it was false either
Elliott Hughes3e381e32012-07-30 16:05:39 -0700624 due to a valid comparison or because one of the values was
Dan Bornstein25705bc2011-04-12 16:23:13 -0700625 <code>NaN</code>.</p>
626 </td>
627</tr>
628<tr>
629 <td>32..37 22t</td>
630 <td>if-<i>test</i> vA, vB, +CCCC<br/>
631 32: if-eq<br/>
632 33: if-ne<br/>
633 34: if-lt<br/>
634 35: if-ge<br/>
635 36: if-gt<br/>
636 37: if-le<br/>
637 </td>
638 <td><code>A:</code> first register to test (4 bits)<br/>
639 <code>B:</code> second register to test (4 bits)<br/>
640 <code>C:</code> signed branch offset (16 bits)</td>
641 <td>Branch to the given destination if the given two registers' values
642 compare as specified.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700643 <p class="note"><strong>Note:</strong>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700644 The branch offset must not be <code>0</code>. (A spin
645 loop may be legally constructed either by branching around a
646 backward <code>goto</code> or by including a <code>nop</code> as
647 a target before the branch.)</p>
648 </td>
649</tr>
650<tr>
651 <td>38..3d 21t</td>
652 <td>if-<i>test</i>z vAA, +BBBB<br/>
653 38: if-eqz<br/>
654 39: if-nez<br/>
655 3a: if-ltz<br/>
656 3b: if-gez<br/>
657 3c: if-gtz<br/>
658 3d: if-lez<br/>
659 </td>
660 <td><code>A:</code> register to test (8 bits)<br/>
661 <code>B:</code> signed branch offset (16 bits)</td>
662 <td>Branch to the given destination if the given register's value compares
663 with 0 as specified.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700664 <p class="note"><strong>Note:</strong>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700665 The branch offset must not be <code>0</code>. (A spin
666 loop may be legally constructed either by branching around a
667 backward <code>goto</code> or by including a <code>nop</code> as
668 a target before the branch.)</p>
669 </td>
670</tr>
671<tr>
672 <td>3e..43 10x</td>
673 <td><i>(unused)</i></td>
674 <td>&nbsp;</td>
675 <td><i>(unused)</i></td>
676</tr>
677<tr>
678 <td>44..51 23x</td>
679 <td><i>arrayop</i> vAA, vBB, vCC<br/>
680 44: aget<br/>
681 45: aget-wide<br/>
682 46: aget-object<br/>
683 47: aget-boolean<br/>
684 48: aget-byte<br/>
685 49: aget-char<br/>
686 4a: aget-short<br/>
687 4b: aput<br/>
688 4c: aput-wide<br/>
689 4d: aput-object<br/>
690 4e: aput-boolean<br/>
691 4f: aput-byte<br/>
692 50: aput-char<br/>
693 51: aput-short
694 </td>
695 <td><code>A:</code> value register or pair; may be source or dest
696 (8 bits)<br/>
697 <code>B:</code> array register (8 bits)<br/>
698 <code>C:</code> index register (8 bits)</td>
699 <td>Perform the identified array operation at the identified index of
700 the given array, loading or storing into the value register.</td>
701</tr>
702<tr>
703 <td>52..5f 22c</td>
704 <td>i<i>instanceop</i> vA, vB, field@CCCC<br/>
705 52: iget<br/>
706 53: iget-wide<br/>
707 54: iget-object<br/>
708 55: iget-boolean<br/>
709 56: iget-byte<br/>
710 57: iget-char<br/>
711 58: iget-short<br/>
712 59: iput<br/>
713 5a: iput-wide<br/>
714 5b: iput-object<br/>
715 5c: iput-boolean<br/>
716 5d: iput-byte<br/>
717 5e: iput-char<br/>
718 5f: iput-short
719 </td>
720 <td><code>A:</code> value register or pair; may be source or dest
721 (4 bits)<br/>
722 <code>B:</code> object register (4 bits)<br/>
723 <code>C:</code> instance field reference index (16 bits)</td>
724 <td>Perform the identified object instance field operation with
725 the identified field, loading or storing into the value register.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700726 <p class="note"><strong>Note:</strong> These opcodes are reasonable candidates for static linking,
Dan Bornstein25705bc2011-04-12 16:23:13 -0700727 altering the field argument to be a more direct offset.</p>
728 </td>
729</tr>
730<tr>
731 <td>60..6d 21c</td>
732 <td>s<i>staticop</i> vAA, field@BBBB<br/>
733 60: sget<br/>
734 61: sget-wide<br/>
735 62: sget-object<br/>
736 63: sget-boolean<br/>
737 64: sget-byte<br/>
738 65: sget-char<br/>
739 66: sget-short<br/>
740 67: sput<br/>
741 68: sput-wide<br/>
742 69: sput-object<br/>
743 6a: sput-boolean<br/>
744 6b: sput-byte<br/>
745 6c: sput-char<br/>
746 6d: sput-short
747 </td>
748 <td><code>A:</code> value register or pair; may be source or dest
749 (8 bits)<br/>
750 <code>B:</code> static field reference index (16 bits)</td>
751 <td>Perform the identified object static field operation with the identified
752 static field, loading or storing into the value register.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700753 <p class="note"><strong>Note:</strong> These opcodes are reasonable candidates for static linking,
Dan Bornstein25705bc2011-04-12 16:23:13 -0700754 altering the field argument to be a more direct offset.</p>
755 </td>
756</tr>
757<tr>
758 <td>6e..72 35c</td>
Elliott Hughes8d777942012-01-05 17:27:02 -0800759 <td>invoke-<i>kind</i> {vC, vD, vE, vF, vG}, meth@BBBB<br/>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700760 6e: invoke-virtual<br/>
761 6f: invoke-super<br/>
762 70: invoke-direct<br/>
763 71: invoke-static<br/>
764 72: invoke-interface
765 </td>
Elliott Hughes8d777942012-01-05 17:27:02 -0800766 <td>
767 <code>A:</code> argument word count (4 bits)<br/>
768 <code>B:</code> method reference index (16 bits)<br/>
769 <code>C..G:</code> argument registers (4 bits each)
770 </td>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700771 <td>Call the indicated method. The result (if any) may be stored
772 with an appropriate <code>move-result*</code> variant as the immediately
773 subsequent instruction.
774 <p><code>invoke-virtual</code> is used to invoke a normal virtual
775 method (a method that is not <code>private</code>, <code>static</code>,
776 or <code>final</code>, and is also not a constructor).</p>
Alex Lightc9aa50c2016-02-01 13:24:23 -0800777 <p>When the <code>method_id</code> references a method of a non-interface
778 class, <code>invoke-super</code> is used to invoke the closest superclass's
Dan Bornstein25705bc2011-04-12 16:23:13 -0700779 virtual method (as opposed to the one with the same <code>method_id</code>
780 in the calling class). The same method restrictions hold as for
781 <code>invoke-virtual</code>.</p>
Alex Lightc9aa50c2016-02-01 13:24:23 -0800782 <p>In Dex files version <code>037</code> or later, if the
783 <code>method_id</code> refers to an interface method,
784 <code>invoke-super</code> is used to invoke the most specific,
785 non-overridden version of that method defined on that interface. The same
786 method restrictions hold as for <code>invoke-virtual</code>. In Dex files
787 prior to version <code>037</code>, having an interface
788 <code>method_id</code> is illegal and undefined.</p>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700789 <p><code>invoke-direct</code> is used to invoke a non-<code>static</code>
790 direct method (that is, an instance method that is by its nature
Alex Lightc9aa50c2016-02-01 13:24:23 -0800791 non-overridable, namely either a <code>private</code> instance method or a
792 constructor).</p>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700793 <p><code>invoke-static</code> is used to invoke a <code>static</code>
794 method (which is always considered a direct method).</p>
795 <p><code>invoke-interface</code> is used to invoke an
796 <code>interface</code> method, that is, on an object whose concrete
797 class isn't known, using a <code>method_id</code> that refers to
798 an <code>interface</code>.</p>
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700799 <p class="note"><strong>Note:</strong> These opcodes are reasonable candidates for static linking,
Dan Bornstein25705bc2011-04-12 16:23:13 -0700800 altering the method argument to be a more direct offset
801 (or pair thereof).</p>
802 </td>
803</tr>
804<tr>
805 <td>73 10x</td>
806 <td><i>(unused)</i></td>
807 <td>&nbsp;</td>
808 <td><i>(unused)</i></td>
809</tr>
810<tr>
811 <td>74..78 3rc</td>
812 <td>invoke-<i>kind</i>/range {vCCCC .. vNNNN}, meth@BBBB<br/>
813 74: invoke-virtual/range<br/>
814 75: invoke-super/range<br/>
815 76: invoke-direct/range<br/>
816 77: invoke-static/range<br/>
817 78: invoke-interface/range
818 </td>
819 <td><code>A:</code> argument word count (8 bits)<br/>
Elliott Hughes8d777942012-01-05 17:27:02 -0800820 <code>B:</code> method reference index (16 bits)<br/>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700821 <code>C:</code> first argument register (16 bits)<br/>
822 <code>N = A + C - 1</code></td>
823 <td>Call the indicated method. See first <code>invoke-<i>kind</i></code>
824 description above for details, caveats, and suggestions.
825 </td>
826</tr>
827<tr>
828 <td>79..7a 10x</td>
829 <td><i>(unused)</i></td>
830 <td>&nbsp;</td>
831 <td><i>(unused)</i></td>
832</tr>
833<tr>
834 <td>7b..8f 12x</td>
835 <td><i>unop</i> vA, vB<br/>
836 7b: neg-int<br/>
837 7c: not-int<br/>
838 7d: neg-long<br/>
839 7e: not-long<br/>
840 7f: neg-float<br/>
841 80: neg-double<br/>
842 81: int-to-long<br/>
843 82: int-to-float<br/>
844 83: int-to-double<br/>
845 84: long-to-int<br/>
846 85: long-to-float<br/>
847 86: long-to-double<br/>
848 87: float-to-int<br/>
849 88: float-to-long<br/>
850 89: float-to-double<br/>
851 8a: double-to-int<br/>
852 8b: double-to-long<br/>
853 8c: double-to-float<br/>
854 8d: int-to-byte<br/>
855 8e: int-to-char<br/>
856 8f: int-to-short
857 </td>
858 <td><code>A:</code> destination register or pair (4 bits)<br/>
859 <code>B:</code> source register or pair (4 bits)</td>
860 <td>Perform the identified unary operation on the source register,
861 storing the result in the destination register.</td>
862</tr>
863
864<tr>
865 <td>90..af 23x</td>
866 <td><i>binop</i> vAA, vBB, vCC<br/>
867 90: add-int<br/>
868 91: sub-int<br/>
869 92: mul-int<br/>
870 93: div-int<br/>
871 94: rem-int<br/>
872 95: and-int<br/>
873 96: or-int<br/>
874 97: xor-int<br/>
875 98: shl-int<br/>
876 99: shr-int<br/>
877 9a: ushr-int<br/>
878 9b: add-long<br/>
879 9c: sub-long<br/>
880 9d: mul-long<br/>
881 9e: div-long<br/>
882 9f: rem-long<br/>
883 a0: and-long<br/>
884 a1: or-long<br/>
885 a2: xor-long<br/>
886 a3: shl-long<br/>
887 a4: shr-long<br/>
888 a5: ushr-long<br/>
889 a6: add-float<br/>
890 a7: sub-float<br/>
891 a8: mul-float<br/>
892 a9: div-float<br/>
893 aa: rem-float<br/>
894 ab: add-double<br/>
895 ac: sub-double<br/>
896 ad: mul-double<br/>
897 ae: div-double<br/>
898 af: rem-double
899 </td>
900 <td><code>A:</code> destination register or pair (8 bits)<br/>
901 <code>B:</code> first source register or pair (8 bits)<br/>
902 <code>C:</code> second source register or pair (8 bits)</td>
903 <td>Perform the identified binary operation on the two source registers,
Clay Murphyd11708c2015-03-05 11:35:26 -0800904 storing the result in the destination register.</td>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700905</tr>
906<tr>
907 <td>b0..cf 12x</td>
908 <td><i>binop</i>/2addr vA, vB<br/>
909 b0: add-int/2addr<br/>
910 b1: sub-int/2addr<br/>
911 b2: mul-int/2addr<br/>
912 b3: div-int/2addr<br/>
913 b4: rem-int/2addr<br/>
914 b5: and-int/2addr<br/>
915 b6: or-int/2addr<br/>
916 b7: xor-int/2addr<br/>
917 b8: shl-int/2addr<br/>
918 b9: shr-int/2addr<br/>
919 ba: ushr-int/2addr<br/>
920 bb: add-long/2addr<br/>
921 bc: sub-long/2addr<br/>
922 bd: mul-long/2addr<br/>
923 be: div-long/2addr<br/>
924 bf: rem-long/2addr<br/>
925 c0: and-long/2addr<br/>
926 c1: or-long/2addr<br/>
927 c2: xor-long/2addr<br/>
928 c3: shl-long/2addr<br/>
929 c4: shr-long/2addr<br/>
930 c5: ushr-long/2addr<br/>
931 c6: add-float/2addr<br/>
932 c7: sub-float/2addr<br/>
933 c8: mul-float/2addr<br/>
934 c9: div-float/2addr<br/>
935 ca: rem-float/2addr<br/>
936 cb: add-double/2addr<br/>
937 cc: sub-double/2addr<br/>
938 cd: mul-double/2addr<br/>
939 ce: div-double/2addr<br/>
940 cf: rem-double/2addr
941 </td>
942 <td><code>A:</code> destination and first source register or pair
943 (4 bits)<br/>
944 <code>B:</code> second source register or pair (4 bits)</td>
945 <td>Perform the identified binary operation on the two source registers,
946 storing the result in the first source register.</td>
947</tr>
948<tr>
949 <td>d0..d7 22s</td>
950 <td><i>binop</i>/lit16 vA, vB, #+CCCC<br/>
951 d0: add-int/lit16<br/>
952 d1: rsub-int (reverse subtract)<br/>
953 d2: mul-int/lit16<br/>
954 d3: div-int/lit16<br/>
955 d4: rem-int/lit16<br/>
956 d5: and-int/lit16<br/>
957 d6: or-int/lit16<br/>
958 d7: xor-int/lit16
959 </td>
960 <td><code>A:</code> destination register (4 bits)<br/>
961 <code>B:</code> source register (4 bits)<br/>
962 <code>C:</code> signed int constant (16 bits)</td>
963 <td>Perform the indicated binary op on the indicated register (first
964 argument) and literal value (second argument), storing the result in
965 the destination register.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700966 <p class="note"><strong>Note:</strong>
Dan Bornstein25705bc2011-04-12 16:23:13 -0700967 <code>rsub-int</code> does not have a suffix since this version is the
968 main opcode of its family. Also, see below for details on its semantics.
969 </p>
970 </td>
971</tr>
972<tr>
973 <td>d8..e2 22b</td>
974 <td><i>binop</i>/lit8 vAA, vBB, #+CC<br/>
975 d8: add-int/lit8<br/>
976 d9: rsub-int/lit8<br/>
977 da: mul-int/lit8<br/>
978 db: div-int/lit8<br/>
979 dc: rem-int/lit8<br/>
980 dd: and-int/lit8<br/>
981 de: or-int/lit8<br/>
982 df: xor-int/lit8<br/>
983 e0: shl-int/lit8<br/>
984 e1: shr-int/lit8<br/>
985 e2: ushr-int/lit8
986 </td>
987 <td><code>A:</code> destination register (8 bits)<br/>
988 <code>B:</code> source register (8 bits)<br/>
989 <code>C:</code> signed int constant (8 bits)</td>
990 <td>Perform the indicated binary op on the indicated register (first
991 argument) and literal value (second argument), storing the result
992 in the destination register.
Bert McMeen3bb4b8f2015-05-06 17:21:27 -0700993 <p class="note"><strong>Note:</strong> See below for details on the semantics of
Dan Bornstein25705bc2011-04-12 16:23:13 -0700994 <code>rsub-int</code>.</p>
995 </td>
996</tr>
997<tr>
998 <td>e3..ff 10x</td>
999 <td><i>(unused)</i></td>
1000 <td>&nbsp;</td>
1001 <td><i>(unused)</i></td>
1002</tr>
1003</tbody>
1004</table>
1005
Clay Murphye4edda62014-10-16 19:00:15 -07001006<h2 id="packed-switch">packed-switch-payload format</h2>
Dan Bornstein25705bc2011-04-12 16:23:13 -07001007
1008<table class="supplement">
1009<thead>
1010<tr>
1011 <th>Name</th>
1012 <th>Format</th>
1013 <th>Description</th>
1014</tr>
1015</thead>
1016<tbody>
1017<tr>
1018 <td>ident</td>
1019 <td>ushort = 0x0100</td>
1020 <td>identifying pseudo-opcode</td>
1021</tr>
1022<tr>
1023 <td>size</td>
1024 <td>ushort</td>
1025 <td>number of entries in the table</td>
1026</tr>
1027<tr>
1028 <td>first_key</td>
1029 <td>int</td>
1030 <td>first (and lowest) switch case value</td>
1031</tr>
1032<tr>
1033 <td>targets</td>
1034 <td>int[]</td>
1035 <td>list of <code>size</code> relative branch targets. The targets are
1036 relative to the address of the switch opcode, not of this table.
1037 </td>
1038</tr>
1039</tbody>
1040</table>
1041
Bert McMeen3bb4b8f2015-05-06 17:21:27 -07001042<p class="note"><strong>Note:</strong> The total number of code units for an instance of this
Dan Bornstein25705bc2011-04-12 16:23:13 -07001043table is <code>(size * 2) + 4</code>.</p>
1044
Clay Murphye4edda62014-10-16 19:00:15 -07001045<h2 id="sparse-switch">sparse-switch-payload format</h2>
Dan Bornstein25705bc2011-04-12 16:23:13 -07001046
1047<table class="supplement">
1048<thead>
1049<tr>
1050 <th>Name</th>
1051 <th>Format</th>
1052 <th>Description</th>
1053</tr>
1054</thead>
1055<tbody>
1056<tr>
1057 <td>ident</td>
1058 <td>ushort = 0x0200</td>
1059 <td>identifying pseudo-opcode</td>
1060</tr>
1061<tr>
1062 <td>size</td>
1063 <td>ushort</td>
1064 <td>number of entries in the table</td>
1065</tr>
1066<tr>
1067 <td>keys</td>
1068 <td>int[]</td>
1069 <td>list of <code>size</code> key values, sorted low-to-high</td>
1070</tr>
1071<tr>
1072 <td>targets</td>
1073 <td>int[]</td>
1074 <td>list of <code>size</code> relative branch targets, each corresponding
1075 to the key value at the same index. The targets are
1076 relative to the address of the switch opcode, not of this table.
1077 </td>
1078</tr>
1079</tbody>
1080</table>
1081
Bert McMeen3bb4b8f2015-05-06 17:21:27 -07001082<p class="note"><strong>Note:</strong> The total number of code units for an instance of this
Dan Bornstein25705bc2011-04-12 16:23:13 -07001083table is <code>(size * 4) + 2</code>.</p>
1084
Clay Murphye4edda62014-10-16 19:00:15 -07001085<h2 id="fill-array">fill-array-data-payload format</h2>
Dan Bornstein25705bc2011-04-12 16:23:13 -07001086
1087<table class="supplement">
1088<thead>
1089<tr>
1090 <th>Name</th>
1091 <th>Format</th>
1092 <th>Description</th>
1093</tr>
1094</thead>
1095<tbody>
1096<tr>
1097 <td>ident</td>
1098 <td>ushort = 0x0300</td>
1099 <td>identifying pseudo-opcode</td>
1100</tr>
1101<tr>
1102 <td>element_width</td>
1103 <td>ushort</td>
1104 <td>number of bytes in each element</td>
1105</tr>
1106<tr>
1107 <td>size</td>
1108 <td>uint</td>
1109 <td>number of elements in the table</td>
1110</tr>
1111<tr>
1112 <td>data</td>
1113 <td>ubyte[]</td>
1114 <td>data values</td>
1115</tr>
1116</tbody>
1117</table>
1118
Bert McMeen3bb4b8f2015-05-06 17:21:27 -07001119<p class="note"><strong>Note:</strong> The total number of code units for an instance of this
Dan Bornstein25705bc2011-04-12 16:23:13 -07001120table is <code>(size * element_width + 1) / 2 + 4</code>.</p>
1121
1122
Clay Murphye4edda62014-10-16 19:00:15 -07001123<h2 id="math">Mathematical operation details</h2>
Dan Bornstein25705bc2011-04-12 16:23:13 -07001124
Bert McMeen3bb4b8f2015-05-06 17:21:27 -07001125<p class="note"><strong>Note:</strong> Floating point operations must follow IEEE 754 rules, using
Dan Bornstein25705bc2011-04-12 16:23:13 -07001126round-to-nearest and gradual underflow, except where stated otherwise.</p>
1127
1128<table class="math">
1129<thead>
1130<tr>
1131 <th>Opcode</th>
1132 <th>C Semantics</th>
1133 <th>Notes</th>
1134</tr>
1135</thead>
1136<tbody>
1137<tr>
1138 <td>neg-int</td>
1139 <td>int32 a;<br/>
1140 int32 result = -a;
1141 </td>
1142 <td>Unary twos-complement.</td>
1143</tr>
1144<tr>
1145 <td>not-int</td>
1146 <td>int32 a;<br/>
1147 int32 result = ~a;
1148 </td>
1149 <td>Unary ones-complement.</td>
1150</tr>
1151<tr>
1152 <td>neg-long</td>
1153 <td>int64 a;<br/>
1154 int64 result = -a;
1155 </td>
1156 <td>Unary twos-complement.</td>
1157</tr>
1158<tr>
1159 <td>not-long</td>
1160 <td>int64 a;<br/>
1161 int64 result = ~a;
1162 </td>
1163 <td>Unary ones-complement.</td>
1164</tr>
1165<tr>
1166 <td>neg-float</td>
1167 <td>float a;<br/>
1168 float result = -a;
1169 </td>
1170 <td>Floating point negation.</td>
1171</tr>
1172<tr>
1173 <td>neg-double</td>
1174 <td>double a;<br/>
1175 double result = -a;
1176 </td>
1177 <td>Floating point negation.</td>
1178</tr>
1179<tr>
1180 <td>int-to-long</td>
1181 <td>int32 a;<br/>
1182 int64 result = (int64) a;
1183 </td>
1184 <td>Sign extension of <code>int32</code> into <code>int64</code>.</td>
1185</tr>
1186<tr>
1187 <td>int-to-float</td>
1188 <td>int32 a;<br/>
1189 float result = (float) a;
1190 </td>
1191 <td>Conversion of <code>int32</code> to <code>float</code>, using
1192 round-to-nearest. This loses precision for some values.
1193 </td>
1194</tr>
1195<tr>
1196 <td>int-to-double</td>
1197 <td>int32 a;<br/>
1198 double result = (double) a;
1199 </td>
1200 <td>Conversion of <code>int32</code> to <code>double</code>.</td>
1201</tr>
1202<tr>
1203 <td>long-to-int</td>
1204 <td>int64 a;<br/>
1205 int32 result = (int32) a;
1206 </td>
1207 <td>Truncation of <code>int64</code> into <code>int32</code>.</td>
1208</tr>
1209<tr>
1210 <td>long-to-float</td>
1211 <td>int64 a;<br/>
1212 float result = (float) a;
1213 </td>
1214 <td>Conversion of <code>int64</code> to <code>float</code>, using
1215 round-to-nearest. This loses precision for some values.
1216 </td>
1217</tr>
1218<tr>
1219 <td>long-to-double</td>
1220 <td>int64 a;<br/>
1221 double result = (double) a;
1222 </td>
1223 <td>Conversion of <code>int64</code> to <code>double</code>, using
1224 round-to-nearest. This loses precision for some values.
1225 </td>
1226</tr>
1227<tr>
1228 <td>float-to-int</td>
1229 <td>float a;<br/>
1230 int32 result = (int32) a;
1231 </td>
1232 <td>Conversion of <code>float</code> to <code>int32</code>, using
1233 round-toward-zero. <code>NaN</code> and <code>-0.0</code> (negative zero)
1234 convert to the integer <code>0</code>. Infinities and values with
1235 too large a magnitude to be represented get converted to either
1236 <code>0x7fffffff</code> or <code>-0x80000000</code> depending on sign.
1237 </td>
1238</tr>
1239<tr>
1240 <td>float-to-long</td>
1241 <td>float a;<br/>
1242 int64 result = (int64) a;
1243 </td>
1244 <td>Conversion of <code>float</code> to <code>int64</code>, using
1245 round-toward-zero. The same special case rules as for
1246 <code>float-to-int</code> apply here, except that out-of-range values
1247 get converted to either <code>0x7fffffffffffffff</code> or
1248 <code>-0x8000000000000000</code> depending on sign.
1249 </td>
1250</tr>
1251<tr>
1252 <td>float-to-double</td>
1253 <td>float a;<br/>
1254 double result = (double) a;
1255 </td>
1256 <td>Conversion of <code>float</code> to <code>double</code>, preserving
1257 the value exactly.
1258 </td>
1259</tr>
1260<tr>
1261 <td>double-to-int</td>
1262 <td>double a;<br/>
1263 int32 result = (int32) a;
1264 </td>
1265 <td>Conversion of <code>double</code> to <code>int32</code>, using
1266 round-toward-zero. The same special case rules as for
1267 <code>float-to-int</code> apply here.
1268 </td>
1269</tr>
1270<tr>
1271 <td>double-to-long</td>
1272 <td>double a;<br/>
1273 int64 result = (int64) a;
1274 </td>
1275 <td>Conversion of <code>double</code> to <code>int64</code>, using
1276 round-toward-zero. The same special case rules as for
1277 <code>float-to-long</code> apply here.
1278 </td>
1279</tr>
1280<tr>
1281 <td>double-to-float</td>
1282 <td>double a;<br/>
1283 float result = (float) a;
1284 </td>
1285 <td>Conversion of <code>double</code> to <code>float</code>, using
1286 round-to-nearest. This loses precision for some values.
1287 </td>
1288</tr>
1289<tr>
1290 <td>int-to-byte</td>
1291 <td>int32 a;<br/>
1292 int32 result = (a &lt;&lt; 24) &gt;&gt; 24;
1293 </td>
1294 <td>Truncation of <code>int32</code> to <code>int8</code>, sign
1295 extending the result.
1296 </td>
1297</tr>
1298<tr>
1299 <td>int-to-char</td>
1300 <td>int32 a;<br/>
1301 int32 result = a &amp; 0xffff;
1302 </td>
1303 <td>Truncation of <code>int32</code> to <code>uint16</code>, without
1304 sign extension.
1305 </td>
1306</tr>
1307<tr>
1308 <td>int-to-short</td>
1309 <td>int32 a;<br/>
1310 int32 result = (a &lt;&lt; 16) &gt;&gt; 16;
1311 </td>
1312 <td>Truncation of <code>int32</code> to <code>int16</code>, sign
1313 extending the result.
1314 </td>
1315</tr>
1316<tr>
1317 <td>add-int</td>
1318 <td>int32 a, b;<br/>
1319 int32 result = a + b;
1320 </td>
1321 <td>Twos-complement addition.</td>
1322</tr>
1323<tr>
1324 <td>sub-int</td>
1325 <td>int32 a, b;<br/>
1326 int32 result = a - b;
1327 </td>
1328 <td>Twos-complement subtraction.</td>
1329</tr>
1330<tr>
1331 <td>rsub-int</td>
1332 <td>int32 a, b;<br/>
1333 int32 result = b - a;
1334 </td>
1335 <td>Twos-complement reverse subtraction.</td>
1336</tr>
1337<tr>
1338 <td>mul-int</td>
1339 <td>int32 a, b;<br/>
1340 int32 result = a * b;
1341 </td>
1342 <td>Twos-complement multiplication.</td>
1343</tr>
1344<tr>
1345 <td>div-int</td>
1346 <td>int32 a, b;<br/>
1347 int32 result = a / b;
1348 </td>
1349 <td>Twos-complement division, rounded towards zero (that is, truncated to
1350 integer). This throws <code>ArithmeticException</code> if
1351 <code>b == 0</code>.
1352 </td>
1353</tr>
1354<tr>
1355 <td>rem-int</td>
1356 <td>int32 a, b;<br/>
1357 int32 result = a % b;
1358 </td>
1359 <td>Twos-complement remainder after division. The sign of the result
1360 is the same as that of <code>a</code>, and it is more precisely
1361 defined as <code>result == a - (a / b) * b</code>. This throws
1362 <code>ArithmeticException</code> if <code>b == 0</code>.
1363 </td>
1364</tr>
1365<tr>
1366 <td>and-int</td>
1367 <td>int32 a, b;<br/>
1368 int32 result = a &amp; b;
1369 </td>
1370 <td>Bitwise AND.</td>
1371</tr>
1372<tr>
1373 <td>or-int</td>
1374 <td>int32 a, b;<br/>
1375 int32 result = a | b;
1376 </td>
1377 <td>Bitwise OR.</td>
1378</tr>
1379<tr>
1380 <td>xor-int</td>
1381 <td>int32 a, b;<br/>
1382 int32 result = a ^ b;
1383 </td>
1384 <td>Bitwise XOR.</td>
1385</tr>
1386<tr>
1387 <td>shl-int</td>
1388 <td>int32 a, b;<br/>
1389 int32 result = a &lt;&lt; (b &amp; 0x1f);
1390 </td>
1391 <td>Bitwise shift left (with masked argument).</td>
1392</tr>
1393<tr>
1394 <td>shr-int</td>
1395 <td>int32 a, b;<br/>
1396 int32 result = a &gt;&gt; (b &amp; 0x1f);
1397 </td>
1398 <td>Bitwise signed shift right (with masked argument).</td>
1399</tr>
1400<tr>
1401 <td>ushr-int</td>
1402 <td>uint32 a, b;<br/>
1403 int32 result = a &gt;&gt; (b &amp; 0x1f);
1404 </td>
1405 <td>Bitwise unsigned shift right (with masked argument).</td>
1406</tr>
1407<tr>
1408 <td>add-long</td>
1409 <td>int64 a, b;<br/>
1410 int64 result = a + b;
1411 </td>
1412 <td>Twos-complement addition.</td>
1413</tr>
1414<tr>
1415 <td>sub-long</td>
1416 <td>int64 a, b;<br/>
1417 int64 result = a - b;
1418 </td>
1419 <td>Twos-complement subtraction.</td>
1420</tr>
1421<tr>
1422 <td>mul-long</td>
1423 <td>int64 a, b;<br/>
1424 int64 result = a * b;
1425 </td>
1426 <td>Twos-complement multiplication.</td>
1427</tr>
1428<tr>
1429 <td>div-long</td>
1430 <td>int64 a, b;<br/>
1431 int64 result = a / b;
1432 </td>
1433 <td>Twos-complement division, rounded towards zero (that is, truncated to
1434 integer). This throws <code>ArithmeticException</code> if
1435 <code>b == 0</code>.
1436 </td>
1437</tr>
1438<tr>
1439 <td>rem-long</td>
1440 <td>int64 a, b;<br/>
1441 int64 result = a % b;
1442 </td>
1443 <td>Twos-complement remainder after division. The sign of the result
1444 is the same as that of <code>a</code>, and it is more precisely
1445 defined as <code>result == a - (a / b) * b</code>. This throws
1446 <code>ArithmeticException</code> if <code>b == 0</code>.
1447 </td>
1448</tr>
1449<tr>
1450 <td>and-long</td>
1451 <td>int64 a, b;<br/>
1452 int64 result = a &amp; b;
1453 </td>
1454 <td>Bitwise AND.</td>
1455</tr>
1456<tr>
1457 <td>or-long</td>
1458 <td>int64 a, b;<br/>
1459 int64 result = a | b;
1460 </td>
1461 <td>Bitwise OR.</td>
1462</tr>
1463<tr>
1464 <td>xor-long</td>
1465 <td>int64 a, b;<br/>
1466 int64 result = a ^ b;
1467 </td>
1468 <td>Bitwise XOR.</td>
1469</tr>
1470<tr>
1471 <td>shl-long</td>
1472 <td>int64 a, b;<br/>
1473 int64 result = a &lt;&lt; (b &amp; 0x3f);
1474 </td>
1475 <td>Bitwise shift left (with masked argument).</td>
1476</tr>
1477<tr>
1478 <td>shr-long</td>
1479 <td>int64 a, b;<br/>
1480 int64 result = a &gt;&gt; (b &amp; 0x3f);
1481 </td>
1482 <td>Bitwise signed shift right (with masked argument).</td>
1483</tr>
1484<tr>
1485 <td>ushr-long</td>
1486 <td>uint64 a, b;<br/>
1487 int64 result = a &gt;&gt; (b &amp; 0x3f);
1488 </td>
1489 <td>Bitwise unsigned shift right (with masked argument).</td>
1490</tr>
1491<tr>
1492 <td>add-float</td>
1493 <td>float a, b;<br/>
1494 float result = a + b;
1495 </td>
1496 <td>Floating point addition.</td>
1497</tr>
1498<tr>
1499 <td>sub-float</td>
1500 <td>float a, b;<br/>
1501 float result = a - b;
1502 </td>
1503 <td>Floating point subtraction.</td>
1504</tr>
1505<tr>
1506 <td>mul-float</td>
1507 <td>float a, b;<br/>
1508 float result = a * b;
1509 </td>
1510 <td>Floating point multiplication.</td>
1511</tr>
1512<tr>
1513 <td>div-float</td>
1514 <td>float a, b;<br/>
1515 float result = a / b;
1516 </td>
1517 <td>Floating point division.</td>
1518</tr>
1519<tr>
1520 <td>rem-float</td>
1521 <td>float a, b;<br/>
1522 float result = a % b;
1523 </td>
1524 <td>Floating point remainder after division. This function is different
1525 than IEEE 754 remainder and is defined as
1526 <code>result == a - roundTowardZero(a / b) * b</code>.
1527 </td>
1528</tr>
1529<tr>
1530 <td>add-double</td>
1531 <td>double a, b;<br/>
1532 double result = a + b;
1533 </td>
1534 <td>Floating point addition.</td>
1535</tr>
1536<tr>
1537 <td>sub-double</td>
1538 <td>double a, b;<br/>
1539 double result = a - b;
1540 </td>
1541 <td>Floating point subtraction.</td>
1542</tr>
1543<tr>
1544 <td>mul-double</td>
1545 <td>double a, b;<br/>
1546 double result = a * b;
1547 </td>
1548 <td>Floating point multiplication.</td>
1549</tr>
1550<tr>
1551 <td>div-double</td>
1552 <td>double a, b;<br/>
1553 double result = a / b;
1554 </td>
1555 <td>Floating point division.</td>
1556</tr>
1557<tr>
1558 <td>rem-double</td>
1559 <td>double a, b;<br/>
1560 double result = a % b;
1561 </td>
1562 <td>Floating point remainder after division. This function is different
1563 than IEEE 754 remainder and is defined as
1564 <code>result == a - roundTowardZero(a / b) * b</code>.
1565 </td>
1566</tr>
1567</tbody>
Clay Murphya69844e2013-05-30 17:56:38 -07001568</table>