DEX file format: class data and code

A class’s fields and methods, its bytecode, exception tables and line-number information live in the data section, reached from the class_def_item. Source: the Dalvik executable format.

class_data_item (no alignment)

Type and name	Meaning
`uleb128 static_fields_size`	Number of static fields.
`uleb128 instance_fields_size`	Number of instance fields.
`uleb128 direct_methods_size`	Number of direct methods.
`uleb128 virtual_methods_size`	Number of virtual methods.
`encoded_field static_fields[]`	The static fields, in increasing `field_idx` order.
`encoded_field instance_fields[]`	The instance fields, in increasing `field_idx` order.
`encoded_method direct_methods[]`	Static, private and constructor methods, in increasing `method_idx` order.
`encoded_method virtual_methods[]`	All other methods (not static, private or constructors), in increasing `method_idx` order. Inherited methods appear only if this class overrides them.

encoded_field

Type and name	Meaning
`uleb128 field_idx_diff`	Index into `field_ids`, as the difference from the previous entry of the same list. The first entry holds the index itself.
`uleb128 access_flags`	Access flags.

encoded_method

Type and name	Meaning
`uleb128 method_idx_diff`	Index into `method_ids`, as the difference from the previous entry of the same list.
`uleb128 access_flags`	Access flags.
`uleb128 code_off`	Offset of the method’s `code_item`, or 0 for an `abstract` or `native` method.

code_item (aligned to 4)

Offset	Size	Type and name	Meaning
`0`	2	`ushort registers_size`	Number of registers the code uses.
`2`	2	`ushort ins_size`	Words of incoming arguments; they occupy the last registers.
`4`	2	`ushort outs_size`	Words of outgoing argument space the code needs for calls.
`6`	2	`ushort tries_size`	Number of `try_item`s; may be 0.
`8`	4	`uint debug_info_off`	Offset of the `debug_info_item`, or 0.
`12`	4	`uint insns_size`	Length of the instructions in 16-bit code units.
`16`	2 × insns_size	`ushort insns[]`	The bytecode.
	0 or 2	`ushort padding`	Present when `tries_size` is not 0 and `insns_size` is odd, to align the tries to 4.
	8 × tries_size	`try_item tries[]`	Present when `tries_size` is not 0. Sorted by address, not overlapping.
	varies	`encoded_catch_handler_list handlers`	Present when `tries_size` is not 0.

try_item (8 bytes)

Offset	Size	Type and name	Meaning
`0`	4	`uint start_addr`	First instruction covered, in code units from the start of `insns`.
`4`	2	`ushort insn_count`	Number of code units covered. The last covered unit is `start_addr + insn_count − 1`.
`6`	2	`ushort handler_off`	Byte offset from the start of the `encoded_catch_handler_list` to this block’s `encoded_catch_handler`.

encoded_catch_handler_list

Type and name	Meaning
`uleb128 size`	Number of handlers.
`encoded_catch_handler list[]`	The handlers.

encoded_catch_handler

Type and name	Meaning
`sleb128 size`	Number of typed catches. Positive: that many, and no catch-all. Zero or negative: −size typed catches, then a catch-all.
`encoded_type_addr_pair handlers[abs(size)]`	The typed catches, in the order they are tested.
`uleb128 catch_all_addr`	Present only when size ≤ 0: address of the catch-all handler, in code units.

encoded_type_addr_pair

Type and name	Meaning
`uleb128 type_idx`	Index into `type_ids` of the exception type to catch.
`uleb128 addr`	Address of the handler, in code units.

debug_info_item (no alignment)

Line numbers and local variables, written as a byte-coded program for a small state machine. The machine has an address (in code units, starting at 0), a line (starting at line_start), the source_file (starting as the class’s source_file_idx), and prologue_end and epilogue_begin flags (both false). A new position entry is emitted whenever a special opcode runs.

Type and name	Meaning
`uleb128 line_start`	Initial `line`.
`uleb128 parameters_size`	Number of parameter names that follow.
`uleb128p1 parameter_names[]`	String index of each parameter’s name, or `NO_INDEX` for none.
`ubyte[] program`	Opcodes, ending with `DBG_END_SEQUENCE`.

Debug opcodes

Value	Name	Arguments	Action
`0x00`	`DBG_END_SEQUENCE`	—	Ends the program.
`0x01`	`DBG_ADVANCE_PC`	`uleb128 addr_diff`	Adds to `address`; no entry is emitted.
`0x02`	`DBG_ADVANCE_LINE`	`sleb128 line_diff`	Adds to `line`; no entry is emitted.
`0x03`	`DBG_START_LOCAL`	`uleb128 register_num`, `uleb128p1 name_idx`, `uleb128p1 type_idx`	A local variable comes into scope at the current address.
`0x04`	`DBG_START_LOCAL_EXTENDED`	as `DBG_START_LOCAL`, then `uleb128p1 sig_idx`	The same, with a generic type signature string.
`0x05`	`DBG_END_LOCAL`	`uleb128 register_num`	The variable in that register goes out of scope.
`0x06`	`DBG_RESTART_LOCAL`	`uleb128 register_num`	The variable that was last in that register comes back into scope.
`0x07`	`DBG_SET_PROLOGUE_END`	—	Sets `prologue_end` for the next entry.
`0x08`	`DBG_SET_EPILOGUE_BEGIN`	—	Sets `epilogue_begin` for the next entry.
`0x09`	`DBG_SET_FILE`	`uleb128p1 name_idx`	Later entries belong to this source file (or none).
`0x0A`–`0xFF`	special opcodes	—	Advance `line` and `address` together, emit an entry, then clear both flags.

Special opcodes

With DBG_FIRST_SPECIAL = 0x0A, DBG_LINE_BASE = −4 and DBG_LINE_RANGE = 15:

adjusted = opcode − 0x0A
line    += −4 + (adjusted % 15)
address += adjusted / 15        (integer division)

So 0x0E advances the line by 0 and the address by 0, and 0x1E (adjusted 20) advances the line by 1 and the address by 1. Opcode 0x0F adds one line without moving the address.

hiddenapi_class_data_item

Present only in boot class path files (from Android 10). It tells the runtime which fields and methods apps may use.

Type and name	Meaning
`uint size`	Size of the whole section in bytes.
`uint offsets[]`	One per class, indexed by `class_idx`: offset from the start of this section to that class’s flags, or 0 if it has none or they are all 0.
`uleb128 flags[]`	For each class, one value per field and method, in the order they appear in its `class_data_item` (static fields, instance fields, direct methods, virtual methods).

Value	Name	Meaning
`0`	whitelist	Officially documented framework interface; may be used freely.
`1`	greylist	Non-SDK interface usable whatever the app’s target API level.
`2`	blacklist	Non-SDK interface not usable whatever the target API level; access is a run-time error.
`3`	greylist-max-o	Non-SDK interface usable by apps targeting up to Android 8.x, unless restricted.
`4`	greylist-max-p	The same, up to Android 9.x.
`5`	greylist-max-q	The same, up to Android 10.x.
`6`	greylist-max-r	The same, up to Android 11.x.

The specification says the list may be extended in future Android releases.

Sources

The Android Open Source Project’s Dalvik executable format: “class_data_item”, “encoded_field”, “encoded_method”, “code_item”, “try_item”, “encoded_catch_handler_list” and the items after it, “debug_info_item” with its state machine and opcodes, and “hiddenapi_class_data_item”; the argument registers from the general design notes of Dalvik bytecode. The special-opcode examples apply the formula.

.DEX File Format – Class data and code