.DEX File Format – Instructions

Machine model

• The machine is register-based. Each method’s frame has a fixed number of 32-bit registers (registers_size), written v0, v1 and so on. A 64-bit value (long, double) uses two adjacent registers, with no alignment needed. An object reference takes one register; null is zero.
• A method’s arguments arrive in its last ins_size registers, in order, with this first for instance methods; wide arguments take two.
• The instruction stream is a sequence of 16-bit code units. The low byte of an instruction’s first unit is its opcode. Addresses and branch offsets are counted in code units. (The specification does not state the base of an if-* or goto offset; for switch tables it says targets are relative to the switch opcode.)
• Many instructions can only name registers v0–v15 or v0–v255; the move forms reach up to v65535.
• Operands are written destination first. Suffixes give the type (-wide, -object, -boolean…) and, after a slash, the format variant (/16, /range, /2addr, /lit8…).

Instruction formats

A format ID has three characters: the number of 16-bit code units, the most registers it names (r for a range), and a letter for the extra data. A fourth character, s or i, marks the suggested formats for statically linked or inlined code. In the layouts, each letter is four bits, read from high to low within each code unit; units are separated by spaces, | separates fields, op is the 8-bit opcode and Ø marks bits that must be zero.

In the 30t, 31x and 51l layouts the first code unit after the opcode holds the low 16 bits (_lo) and the last the high bits (_hi). The suggested formats describe how a running system may rewrite instructions when it statically links them; implementing them is optional.

Opcodes

Data payloads

Switch tables and array data sit in the instruction stream as pseudo-instructions, usually at the end of the method. Each starts at a 4-byte-aligned address (a nop pads if needed), and its first code unit is an identifier whose low byte is 00, the nop opcode. They are never executed.

packed-switch-payload

Length: size × 2 + 4 code units.

sparse-switch-payload

Length: size × 4 + 2 code units.

fill-array-data-payload

Length: (size × element_width + 1) / 2 + 4 code units.

Example

12 01           const/4 v1, #+0         (B=0, A=1, op 12)
1A 00 05 00     const-string v0, string@0005
6E 20 03 00 10 00
                invoke-virtual {v0, v1}, meth@0003   (A=2, G=0; C=0, D=1)
0E 00           return-void

Bytes are as stored: each code unit is a little-endian ushort, so its low byte (the opcode) comes first.

Sources

• Dalvik bytecode – general design, the summary of the bytecode set (every opcode, format and meaning) and the payload formats
• Dalvik executable instruction formats – the format IDs, letters, layouts and syntax
• Dalvik executable format – code_item and the little-endian ushort instruction array