.

dex — Dalvik Executable Format

Copyright © 2007 Google Inc. All rights reserved.

This document describes the layout and contents of .dex files, which are used to hold a set of class
definitions and their associated adjunct data.

Guide To Types

Name Description
byte 8-bit signed int
ubyte 8-bit unsigned int
short 16-bit signed int, little-endian
ushort 16-bit unsigned int, little-endian
int 32-bit signed int, little-endian
uint 32-bit unsigned int, little-endian
long 64-bit signed int, little-endian
ulong 64-bit unsigned int, little-endian
sleb128 signed LEB128, variable-length (see below)
uleb128 unsigned LEB128, variable-length (see below)
uleb128p1 unsigned LEB128 plus 1, variable-length (see below)

LEB128
LEB128 ("Little-Endian Base 128") is a variable-length encoding for arbitrary signed or unsigned integer
quantities. The format was borrowed from the DWARF3 specification. In a .dex file, LEB128 is only ever
used to encode 32-bit quantities.

Each LEB128 encoded value consists of one to five bytes, which together represent a single 32-bit value.
Each byte has its most significant bit set except for the final byte in the sequence, which has its most
significant bit clear. The remaining seven bits of each byte are payload, with the least significant seven bits
of the quantity in the first byte, the next seven in the second byte and so on. In the case of a signed
LEB128 (sleb128), the most significant payload bit of the final byte in the sequence is sign-extended to
produce the final value. In the unsigned case (uleb128), any bits not explicitly represented are interpreted
as 0.

1
 Bitwise diagram of a two-byte LEB128 value
First byte Second byte
1 bit6 bit5 bit4 bit3 bit2 bit1 bit0 0 bit13 bit12 bit11 bit10 bit9 bit8 bit7

The variant uleb128p1 is used to represent a signed value, where the representation is of the value plus one
encoded as a uleb128. This makes the encoding of -1 (alternatively thought of as the unsigned value
0xffffffff) — but no other negative number — a single byte, and is useful in exactly those cases where
the represented number must either be non-negative or -1 (or 0xffffffff), and where no other negative
values are allowed (or where large unsigned values are unlikely to be needed).

Here are some examples of the formats:

Encoded Sequence As sleb128 As uleb128 As uleb128p1

00 0 0 -1
01 1 1 0
7f -1 127 126
80 7f -128 16256 16255

Overall File Layout

Name Format Description

header header_item the header
string identifiers list. These are identifiers for all the strings used by
this file, either for internal naming (e.g., type descriptors) or as
string_ids string_id_item[] constant objects referred to by code. This list must be sorted by string
contents, using UTF-16 code point values (not in a locale-sensitive
manner).

type identifiers list. These are identifiers for all types (classes,
type_ids type_id_item[] arrays, or primitive types) referred to by this file, whether defined in
the file or not. This list must be sorted by string_id index.
method prototype identifiers list. These are identifiers for all
prototypes referred to by this file. This list must be sorted in
proto_ids proto_id_item[] return-type (by type_id index) major order, and then by arguments
(also by type_id index).
field identifiers list. These are identifiers for all fields referred to by
this file, whether defined in the file or not. This list must be sorted,
field_ids field_id_item[] where the defining type (by type_id index) is the major order, field
name (by string_id index) is the intermediate order, and type (by
type_id index) is the minor order.

method identifiers list. These are identifiers for all methods referred
method_id_item[] to by this file, whether defined in the file or not. This list must be
method_ids sorted, where the defining type (by type_id index) is the major
order, method name (by string_id index) is the intermediate

2
 Name Format Description
order, and method prototype (by proto_id index) is the minor
order.
class definitions list. The classes must be ordered such that a given
class_defs class_def_item[] class's superclass and implemented interfaces appear in the list
earlier than the referring class.
data area, containing all the support data for the tables listed above.
Different items have different alignment requirements, and padding
data ubyte[] bytes are inserted before each item if necessary to achieve proper
alignment.
data used in statically linked files. The format of the data in this
link_data ubyte[] section is left unspecified by this document; this section is empty in
unlinked files, and runtime implementations may use it as they see fit.

Bitfield, String, and Constant Definitions

DEX_FILE_MAGIC
embedded in header_item

The constant array/string DEX_FILE_MAGIC is the list of bytes that must appear at the beginning of a .dex file
in order for it to be recognized as such. The value intentionally contains a newline ("\n" or 0x0a) and a
null byte ("\0" or 0x00) in order to help in the detection of certain forms of corruption. The value also
encodes a format version number as three decimal digits, which is expected to increase monotonically
over time as the format evolves.

ubyte[8] DEX_FILE_MAGIC = { 0x64 0x65 0x78 0x0a 0x30 0x33 0x35 0x00 }
= "dex\n035\0"

Note: At least a couple earlier versions of the format have been used in widely-available public software
releases. For example, version 009 was used for the M3 releases of the Android platform
(November-December 2007), and version 013 was used for the M5 releases of the Android platform
(February-March 2008). In several respects, these earlier versions of the format differ significantly from
the version described in this document.

ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT

embedded in header_item

The constant ENDIAN_CONSTANT is used to indicate the endianness of the file in which it is found. Although
the standard .dex format is little-endian, implementations may choose to perform byte-swapping. Should
an implementation come across a header whose endian_tag is REVERSE_ENDIAN_CONSTANT instead of
ENDIAN_CONSTANT, it would know that the file has been byte-swapped from the expected form.

3
 uint ENDIAN_CONSTANT = 0x12345678;
uint REVERSE_ENDIAN_CONSTANT = 0x78563412;

NO_INDEX
embedded in class_def_item and debug_info_item

The constant NO_INDEX is used to indicate that an index value is absent.

Note: This value isn't defined to be 0, because that is in fact typically a valid index.

Also Note: The chosen value for NO_INDEX is representable as a single byte in the uleb128p1 encoding.

uint NO_INDEX = 0xffffffff; // == -1 if treated as a signed int

access_flags Definitions
embedded in class_def_item , field_item , method_item , and InnerClass

Bitfields of these flags are used to indicate the accessibility and overall properties of classes and class
members.

For Classes (and

Name Value InnerClass For Fields For Methods
annotations)
public: visible public: visible public: visible
ACC_PUBLIC 0x1 everywhere everywhere everywhere

* private: only visible private: only visible to private: only visible to

ACC_PRIVATE 0x2 to defining class defining class defining class

* protected: visible to protected: visible to protected: visible to

ACC_PROTECTED 0x4 package and subclasses package and subclasses package and subclasses

* static: is not static: global to static: does not take a

ACC_STATIC 0x8 constructed with an outer defining class this argument
this reference
final: immutable after
ACC_FINAL 0x10 final: not subclassable final: not overridable
construction

(unused) 0x20
volatile: special
ACC_VOLATILE 0x40 access rules to help with
thread safety
bridge method, added
ACC_BRIDGE 0x40 automatically by compiler
as a type-safe bridge
transient: not to be
ACC_TRANSIENT 0x80 saved by default
serialization

4
 For Classes (and
Name Value InnerClass For Fields For Methods
annotations)
last argument should be
ACC_VARARGS 0x80 treated as a "rest"
argument by compiler
native: implemented in
ACC_NATIVE 0x100 native code

interface:
ACC_INTERFACE 0x200 multiply-implementable
abstract class
abstract:
abstract: not directly
ACC_ABSTRACT 0x400 unimplemented by this
instantiable class
strictfp: strict rules
ACC_STRICT 0x800 for floating-point
arithmetic
not directly defined in not directly defined in not directly defined in
ACC_SYNTHETIC 0x1000 source code source code source code

declared as an annotation
ACC_ANNOTATION 0x2000 class

declared as an declared as an
ACC_ENUM 0x4000 enumerated type enumerated value

(unused) 0x8000
constructor method (class
ACC_CONSTRUCTOR 0x10000 or instance initializer)

* Only allowed on for InnerClass annotations, and must not ever be on in a class_def_item.

MUTF-8 (Modified UTF-8) Encoding

As a concession to easier legacy support, the .dex format encodes its string data in a de facto standard
modified UTF-8 form, hereafter referred to as MUTF-8. This form is identical to standard UTF-8, except:

Only the one-, two-, and three-byte encodings are used.

Code points in the range U+10000 … U+10ffff are encoded as a surrogate pair, each of which is
represented as a three-byte encoded value.
The code point U+0000 is encoded in two-byte form.
A plain null byte (value 0) indicates the end of a string, as is the standard C language interpretation.

The first two items above can be summarized as: MUTF-8 is an encoding format for UTF-16, instead of
being a more direct encoding format for Unicode characters.

The final two items above make it simultaneously possible to include the code point U+0000 in a string and
still manipulate it as a C-style null-terminated string.

However, the special encoding of U+0000 means that, unlike normal UTF-8, the result of calling the
standard C function strcmp() on a pair of MUTF-8 strings does not always indicate the properly signed
result of comparison of unequal strings. When ordering (not just equality) is a concern, the most
straightforward way to compare MUTF-8 strings is to decode them character by character, and compare
the decoded values. (However, more clever implementations are also possible.)

5
Please refer to The Unicode Standard for further information about character encoding. MUTF-8 is
actually closer to the (relatively less well-known) encoding CESU-8 than to UTF-8 per se.

encoded_value Encoding
embedded in annotation_element and encoded_array_item

An encoded_value is an encoded piece of (nearly) arbitrary hierarchically structured data. The encoding is
meant to be both compact and straightforward to parse.

Name Format Description

byte indicating the type of the immediately subsequent value along
with an optional clarifying argument in the high-order three bits. See
(value_arg << below for the various value definitions. In most cases, value_arg
5) | value_type ubyte encodes the length of the immediately-subsequent value in bytes, as
(size - 1), e.g., 0 means that the value requires one byte, and 7
means it requires eight bytes; however, there are exceptions as noted
below.
bytes representing the value, variable in length and interpreted
value ubyte[] differently for different value_type bytes, though always
little-endian. See the various value definitions below for details.

Value Formats

Type Name value_type value_arg value Format Description

Format

VALUE_BYTE 0x00 (none; ubyte[1] signed one-byte integer value

must be 0)
size - signed two-byte integer value,
VALUE_SHORT 0x02 ubyte[size]
1 (0…1) sign-extended

size - unsigned two-byte integer value,

VALUE_CHAR 0x03 ubyte[size]
1 (0…1) zero-extended

size - signed four-byte integer value,

VALUE_INT 0x04 ubyte[size]
1 (0…3) sign-extended

size - signed eight-byte integer value,

VALUE_LONG 0x06 ubyte[size]
1 (0…7) sign-extended

four-byte bit pattern, zero-extended

VALUE_FLOAT 0x10 size - ubyte[size]
1 (0…3) to the right, and interpreted as an
IEEE754 32-bit floating point value
eight-byte bit pattern, zero-extended
VALUE_DOUBLE 0x11 size - ubyte[size]
1 (0…7) to the right, and interpreted as an
IEEE754 64-bit floating point value
unsigned (zero-extended) four-byte
size - integer value, interpreted as an
VALUE_STRING 0x17 1 (0…3) ubyte[size] index into the string_ids section
and representing a string value
unsigned (zero-extended) four-byte
integer value, interpreted as an
size -
VALUE_TYPE 0x18 ubyte[size] index into the type_ids section
1 (0…3) and representing a reflective
type/class value

6
 Type Name value_type value_arg value Format Description
Format
unsigned (zero-extended) four-byte
integer value, interpreted as an
size -
VALUE_FIELD 0x19 ubyte[size] index into the field_ids section
1 (0…3) and representing a reflective field
value

unsigned (zero-extended) four-byte

integer value, interpreted as an
size -
VALUE_METHOD 0x1a ubyte[size] index into the method_ids section
1 (0…3) and representing a reflective method
value

unsigned (zero-extended) four-byte

integer value, interpreted as an
size -
VALUE_ENUM 0x1b ubyte[size] index into the field_ids section
1 (0…3) and representing the value of an
enumerated type constant

an array of values, in the format

VALUE_ARRAY 0x1c (none; encoded_array specified by "encoded_array
must be 0) Format" below. The size of the
value is implicit in the encoding.
a sub-annotation, in the format
specified by
(none; "encoded_annotation
VALUE_ANNOTATION 0x1d must be 0) encoded_annotation
Format" below. The size of the
value is implicit in the encoding.

(none;
VALUE_NULL 0x1e must be 0) (none) null reference value

one-bit value; 0 for false and 1 for

boolean
VALUE_BOOLEAN 0x1f (0…1) (none) true. The bit is represented in the
value_arg.

encoded_array Format

Name Format Description

size uleb128 number of elements in the array
a series of size encoded_value byte sequences in the format
values encoded_value[size] specified by this section, concatenated sequentially.

encoded_annotation Format

Name Format Description

type of the annotation. This must be a class (not array or
type_idx uleb128 primitive) type.

size uleb128 number of name-value mappings in this annotation

elements of the annotataion, represented directly in-line (not
elements annotation_element[size] as offsets). Elements must be sorted in increasing order by
string_id index.

annotation_element Format

7
 Name Format Description
element name, represented as an index into the string_ids
name_idx uleb128 section. The string must conform to the syntax for MemberName,
defined above.
value encoded_value element value

String Syntax
There are several kinds of item in a .dex file which ultimately refer to a string. The following BNF-style
definitions indicate the acceptable syntax for these strings.

SimpleName
A SimpleName is the basis for the syntax of the names of other things. The .dex format allows a fair
amount of latitude here (much more than most common source languages). In brief, a simple name may
consist of any low-ASCII alphabetic character or digit, a few specific low-ASCII symbols, and most
non-ASCII code points that are not control, space, or special characters. Note that surrogate code points
(in the range U+d800 … U+dfff) are not considered valid name characters, per se, but Unicode
supplemental characters are valid (which are represented by the final alternative of the rule for
SimpleNameChar), and they should be represented in a file as pairs of surrogate code points in the
MUTF-8 encoding.

SimpleName →
SimpleNameChar (SimpleNameChar)*
SimpleNameChar →
'A' … 'Z'
| 'a' … 'z'
| '0' … '9'
| '$'
| '-'
| '_'
| U+00a1 … U+1fff
| U+2010 … U+2027
| U+2030 … U+d7ff
| U+e000 … U+ffef
| U+10000 … U+10ffff

MemberName
used by field_id_item and method_id_item

A MemberName is the name of a member of a class, members being fields, methods, and inner classes.

MemberName →
SimpleName
| '<' SimpleName '>'

8
FullClassName
A FullClassName is a fully-qualified class name, including an optional package specifier followed by a
required name.

FullClassName →
OptionalPackagePrefix SimpleName
OptionalPackagePrefix →
(SimpleName '/')*

TypeDescriptor
used by type_id_item

A TypeDescriptor is the representation of any type, including primitives, classes, arrays, and void. See
below for the meaning of the various versions.

TypeDescriptor →
'V'
| FieldTypeDescriptor

FieldTypeDescriptor →
NonArrayFieldTypeDescriptor
| ('[' * 1…255) NonArrayFieldTypeDescriptor

NonArrayFieldTypeDescriptor→
'Z'
| 'B'
| 'S'
| 'C'
| 'I'
| 'J'
| 'F'
| 'D'
| 'L' FullClassName ';'

ShortyDescriptor
used by proto_id_item

A ShortyDescriptor is the short form representation of a method prototype, including return and
parameter types, except that there is no distinction between various reference (class or array) types.
Instead, all reference types are represented by a single 'L' character.

ShortyDescriptor →
ShortyReturnType (ShortyFieldType)*
ShortyReturnType →
'V'
| ShortyFieldType

ShortyFieldType →
'Z'
| 'B'
| 'S'
| 'C'

9
 | 'I'
| 'J'
| 'F'
| 'D'
| 'L'

TypeDescriptor Semantics
This is the meaning of each of the variants of TypeDescriptor.

Syntax Meaning
V void; only valid for return types
Z boolean
B byte
S short
C char
I int
J long
F float
D double
Lfully/qualified/Name; the class fully.qualified.Name
array of descriptor, usable recursively for arrays-of-arrays, though it is invalid to
[descriptor have more than 255 dimensions.

Items and Related Structures

This section includes definitions for each of the top-level items that may appear in a .dex file.

header_item
appears in the header section
alignment: 4 bytes

Name Format Description

ubyte[8] = magic value. See discussion above under "DEX_FILE_MAGIC" for
magic DEX_FILE_MAGIC more details.

adler32 checksum of the rest of the file (everything but magic and
checksum uint this field); used to detect file corruption

10
map_list
appears in the data section
referenced from header_item
alignment: 4 bytes

This is a list of the entire contents of a file, in order. It contains some redundancy with respect to the
header_item but is intended to be an easy form to use to iterate over an entire file. A given type may
appear at most once in a map, but there is no restriction on what order types may appear in, other than the
restrictions implied by the rest of the format (e.g., a header section must appear first, followed by a
string_ids section, etc.). Additionally, the map entries must be ordered by initial offset and must not
overlap.

Name Format Description

size uint size of the list, in entries
list map_item[size] elements of the list

map_item Format

Name Format Description

type ushort type of the items; see table below
unused ushort (unused)
count of the number of items to be found at the indicated
size uint offset

offset uint offset from the start of the file to the items in question

Type Codes

Item Type Constant Value Item Size In Bytes

header_item TYPE_HEADER_ITEM 0x0000 0x70
string_id_item TYPE_STRING_ID_ITEM 0x0001 0x04
type_id_item TYPE_TYPE_ID_ITEM 0x0002 0x04
proto_id_item TYPE_PROTO_ID_ITEM 0x0003 0x0c
field_id_item TYPE_FIELD_ID_ITEM 0x0004 0x08
method_id_item TYPE_METHOD_ID_ITEM 0x0005 0x08
class_def_item TYPE_CLASS_DEF_ITEM 0x0006 0x20
4 +
map_list TYPE_MAP_LIST 0x1000 (item.size *
12)
4 +
type_list TYPE_TYPE_LIST 0x1001 (item.size *
2)

11
 Item Type Constant Value Item Size In Bytes
4 +
annotation_set_ref_list TYPE_ANNOTATION_SET_REF_LIST 0x1002 (item.size *
4)
4 +
annotation_set_item TYPE_ANNOTATION_SET_ITEM 0x1003 (item.size *
4)
class_data_item TYPE_CLASS_DATA_ITEM 0x2000 implicit; must parse
code_item TYPE_CODE_ITEM 0x2001 implicit; must parse
string_data_item TYPE_STRING_DATA_ITEM 0x2002 implicit; must parse
debug_info_item TYPE_DEBUG_INFO_ITEM 0x2003 implicit; must parse
annotation_item TYPE_ANNOTATION_ITEM 0x2004 implicit; must parse
encoded_array_item TYPE_ENCODED_ARRAY_ITEM 0x2005 implicit; must parse
annotations_directory_item TYPE_ANNOTATIONS_DIRECTORY_ITEM 0x2006 implicit; must parse

string_id_item
appears in the string_ids section
alignment: 4 bytes

Name Format Description

offset from the start of the file to the string data for this item. The offset
should be to a location in the data section, and the data should be in
string_data_off uint the format specified by "string_data_item" below. There is no
alignment requirement for the offset.

string_data_item
appears in the data section
alignment: none (byte-aligned)

Name Format Description

size of this string, in UTF-16 code units (which is the "string length" in
utf16_size uleb128 many systems). That is, this is the decoded length of the string. (The
encoded length is implied by the position of the 0 byte.)
a series of MUTF-8 code units (a.k.a. octets, a.k.a. bytes) followed by
a byte of value 0. See "MUTF-8 (Modified UTF-8) Encoding" above
for details and discussion about the data format.
data ubyte[] Note: It is acceptable to have a string which includes (the encoded
form of) UTF-16 surrogate code units (that is, U+d800 … U+dfff)
either in isolation or out-of-order with respect to the usual encoding of
Unicode into UTF-16. It is up to higher-level uses of strings to reject
such invalid encodings, if appropriate.

12
type_id_item
appears in the type_ids section
alignment: 4 bytes

Name Format Description

index into the string_ids list for the descriptor string of this type.
descriptor_idx uint The string must conform to the syntax for TypeDescriptor, defined
above.

proto_id_item
appears in the proto_ids section
alignment: 4 bytes

Name Format Description

index into the string_ids list for the short-form descriptor string of
this prototype. The string must conform to the syntax for
shorty_idx uint ShortyDescriptor, defined above, and must correspond to the return
type and parameters of this item.
return_type_idx uint index into the type_ids list for the return type of this prototype
offset from the start of the file to the list of parameter types for this
prototype, or 0 if this prototype has no parameters. This offset, if
parameters_off uint non-zero, should be in the data section, and the data there should be
in the format specified by "type_list" below. Additionally, there
should be no reference to the type void in the list.

field_id_item
appears in the field_ids section
alignment: 4 bytes

Name Format Description

index into the type_ids list for the definer of this field. This must be
class_idx ushort a class type, and not an array or primitive type.

type_idx ushort index into the type_ids list for the type of this field
index into the string_ids list for the name of this field. The string
name_idx uint must conform to the syntax for MemberName, defined above.

13
method_id_item
appears in the method_ids section
alignment: 4 bytes

Name Format Description

index into the type_ids list for the definer of this method. This must
class_idx ushort be a class or array type, and not a primitive type.

proto_idx ushort index into the proto_ids list for the prototype of this method
index into the string_ids list for the name of this method. The
name_idx uint string must conform to the syntax for MemberName, defined above.

class_def_item
appears in the class_defs section
alignment: 4 bytes

Name Format Description

index into the type_ids list for this class. This must be a class
class_idx uint type, and not an array or primitive type.

access flags for the class (public, final, etc.). See

access_flags uint "access_flags Definitions" for details.

index into the type_ids list for the superclass, or the constant
value NO_INDEX if this class has no superclass (i.e., it is a root
superclass_idx uint class such as Object). If present, this must be a class type, and
not an array or primitive type.
offset from the start of the file to the list of interfaces, or 0 if there are
none. This offset should be in the data section, and the data there
interfaces_off uint should be in the format specified by "type_list" below. Each of
the elements of the list must be a class type (not an array or
primitive type), and there must not be any duplicates.

index into the string_ids list for the name of the file containing
the original source for (at least most of) this class, or the special
source_file_idx uint value NO_INDEX to represent a lack of this information. The
debug_info_item of any given method may override this
source file, but the expectation is that most classes will only come
from one source file.
offset from the start of the file to the annotations structure for this
class, or 0 if there are no annotations on this class. This offset, if
annotations_off uint non-zero, should be in the data section, and the data there should
be in the format specified by
"annotations_directory_item" below, with all items
referring to this class as the definer.
offset from the start of the file to the associated class data for this
item, or 0 if there is no class data for this class. (This may be the
class_data_off uint case, for example, if this class is a marker interface.) The offset, if
non-zero, should be in the data section, and the data there should
be in the format specified by "class_data_item" below, with all
items referring to this class as the definer.
offset from the start of the file to the list of initial values for static
fields, or 0 if there are none (and all static fields are to be
static_values_off uint initialized with 0 or null). This offset should be in the data
section, and the data there should be in the format specified by

14
 Name Format Description
"encoded_array_item" below. The size of the array must be
no larger than the number of static fields declared by this class,
and the elements correspond to the static fields in the same
order as declared in the corresponding field_list. The type of
each array element must match the declared type of its
corresponding field. If there are fewer elements in the array than
there are static fields, then the leftover fields are initialized with a
type-appropriate 0 or null.

class_data_item
referenced from class_def_item
appears in the data section
alignment: none (byte-aligned)

Name Format Description

the number of static fields
static_fields_size uleb128 defined in this item

the number of instance fields

instance_fields_size uleb128 defined in this item

the number of direct methods

direct_methods_size uleb128 defined in this item

the number of virtual methods

virtual_methods_size uleb128 defined in this item

the defined static fields,

represented as a sequence of
static_fields encoded_field[static_fields_size] encoded elements. The fields
must be sorted by field_idx
in increasing order.

the defined instance fields,

represented as a sequence of
instance_fields encoded_field[instance_fields_size] encoded elements. The fields
must be sorted by field_idx
in increasing order.

the defined direct (any of

static, private, or
constructor) methods,
represented as a sequence of
direct_methods encoded_method[direct_methods_size] encoded elements. The methods
must be sorted by
method_idx in increasing
order.

the defined virtual (none of

static, private, or
constructor) methods,
represented as a sequence of
encoded elements. This list
virtual_methods encoded_method[virtual_methods_size] should not include inherited
methods unless overridden by
the class that this item
represents. The methods must
be sorted by method_idx in
increasing order.

15
Note: All elements' field_ids and method_ids must refer to the same defining class.

encoded_field Format

Name Format Description

index into the field_ids list for the identity of this field (includes the
name and descriptor), represented as a difference from the index of
field_idx_diff uleb128 previous element in the list. The index of the first element in a list is
represented directly.
access flags for the field (public, final, etc.). See
access_flags uleb128 "access_flags Definitions" for details.

encoded_method Format

Name Format Description

index into the method_ids list for the identity of this method
(includes the name and descriptor), represented as a difference from
method_idx_diff uleb128 the index of previous element in the list. The index of the first element
in a list is represented directly.
access flags for the method (public, final, etc.). See
access_flags uleb128 "access_flags Definitions" for details.

offset from the start of the file to the code structure for this method, or
0 if this method is either abstract or native. The offset should be
code_off uleb128 to a location in the data section. The format of the data is specified by
"code_item" below.

type_list
referenced from class_def_item and proto_id_item
appears in the data section
alignment: 4 bytes

Name Format Description

size uint size of the list, in entries
list type_item[size] elements of the list

type_item Format

Name Format Description

type_idx ushort index into the type_ids list

16
code_item
referenced from method_item
appears in the data section
alignment: 4 bytes

Name Format Description

registers_size ushort the number of registers used by this code
the number of words of incoming arguments to the
ins_size ushort method that this code is for

the number of words of outgoing argument space

outs_size ushort required by this code for method invocation

the number of try_items for this instance. If non-zero,

tries_size ushort then these appear as the tries array just after the
insns in this instance.
offset from the start of the file to the debug info (line
numbers + local variable info) sequence for this code, or
0 if there simply is no information. The offset, if
debug_info_off uint non-zero, should be to a location in the data section.
The format of the data is specified by
"debug_info_item" below.
insns_size uint size of the instructions list, in 16-bit code units
actual array of bytecode. The format of code in an
insns array is specified by the companion document
"Bytecode for the Dalvik VM". Note that though this is
defined as an array of ushort, there are some internal
insns ushort[insns_size] structures that prefer four-byte alignment. Also, if this
happens to be in an endian-swapped file, then the
swapping is only done on individual ushorts and not on
the larger internal structures.

two bytes of padding to make tries four-byte aligned.

padding ushort (optional) = 0 This element is only present if tries_size is
non-zero and insns_size is odd.
array indicating where in the code exceptions may be
caught and how to handle them. Elements of the array
try_item[tries_size]
tries must be non-overlapping in range and in order from low
(optional) to high address. This element is only present if
tries_size is non-zero.

bytes representing a list of lists of catch types and

encoded_catch_handler_list associated handler addresses. Each try_item has a
handlers (optional) byte-wise offset into this structure. This element is only
present if tries_size is non-zero.

try_item Format

Name Format Description

start address of the block of code covered by this entry. The address
start_addr uint is a count of 16-bit code units to the start of the first covered
instruction.
number of 16-bit code units covered by this entry. The last code unit
insn_count ushort covered (inclusive) is start_addr + insn_count - 1.

offset in bytes from the start of the associated encoded handler data to
handler_off ushort the catch_handler_item for this entry

17
encoded_catch_handler_list Format

Name Format Description

size uleb128 size of this list, in entries
actual list of handler lists, represented directly
list encoded_catch_handler[handlers_size] (not as offsets), and concatenated sequentially

encoded_catch_handler Format

Name Format Description

number of catch types in this list. If
non-positive, then this is the negative of the
number of catch types, and the catches are
followed by a catch-all handler. For example:
A size of 0 means that there is a catch-all
size sleb128 but no explicitly typed catches. A size of 2
means that there are two explicitly typed
catches and no catch-all. And a size of -1
means that there is one typed catch along with
a catch-all.
stream of abs(size) encoded items, one
handlers encoded_type_addr_pair[abs(size)] for each caught type, in the order that the types
should be tested.
bytecode address of the catch-all handler.
catch_all_addr uleb128 (optional) This element is only present if size is
non-positive.

encoded_type_addr_pair Format

Name Format Description

index into the type_ids list for the type of the exception to
type_idx uleb128 catch

addr uleb128 bytecode address of the associated exception handler

debug_info_item
referenced from code_item
appears in the data section
alignment: none (byte-aligned)

Each debug_info_item defines a DWARF3-inspired byte-coded state machine that, when interpreted, emits
the positions table and (potentially) the local variable information for a code_item. The sequence begins
with a variable-length header (the length of which depends on the number of method parameters), is
followed by the state machine bytecodes, and ends with an DBG_END_SEQUENCE byte.

The state machine consists of five registers. The address register represents the instruction offset in the

18
associated insns_item in 16-bit code units. The address register starts at 0 at the beginning of each
debug_info sequence and may only monotonically increase. The line register represents what source line
number should be associated with the next positions table entry emitted by the state machine. It is
initialized in the sequence header, and may change in positive or negative directions but must never be
less than 1. The source_file register represents the source file that the line number entries refer to. It is
initialized to the value of source_file_idx in class_def_item. The other two variables, prologue_end and
epilogue_begin, are boolean flags (initialized to false) that indicate whether the next position emitted
should be considered a method prologue or epilogue. The state machine must also track the name and
type of the last local variable live in each register for the DBG_RESTART_LOCAL code.

The header is as follows:

Name Format Description

the initial value for the state machine's line register.
line_start uleb128 Does not represent an actual positions entry.

the number of parameter names that are encoded.

parameters_size uleb128 There should be one per method parameter, excluding
an instance method's this, if any.
string index of the method parameter name. An
encoded value of NO_INDEX indicates that no name is
parameter_names uleb128p1[parameters_size] available for the associated parameter. The type
descriptor and signature are implied from the method
descriptor and signature.

The byte code values are as follows:

Name Value Format Arguments Description

terminates a debug info sequence for a
DBG_END_SEQUENCE 0x00 (none) code_item

addr_diff:
DBG_ADVANCE_PC 0x01 uleb128 addr_diff advances the address register without
amount to add to emitting a positions entry
address register
line_diff:
DBG_ADVANCE_LINE 0x02 sleb128 line_diff advances the line register without emitting
amount to change a positions entry
line register by
register_num:
register that will
uleb128 register_num contain local introduces a local variable at the current
name_idx: address. Either name_idx or
DBG_START_LOCAL 0x03 uleb128p1 name_idx string index of the type_idx may be NO_INDEX
uleb128p1 type_idx name indicate that that value is unknown.
type_idx: type
index of the type

introduces a local with a type signature at

register_num: the current address. Any of name_idx
register that will type_idx, or sig_idx may be
contain local NO_INDEX to indicate that that value is
name_idx: unknown. (If sig_idx is -1, though, the
uleb128 register_num string index of the same data could be represented more
uleb128p1 name_idx name
DBG_START_LOCAL_EXTENDED 0x04 efficiently using the opcode
uleb128p1 type_idx type_idx: type DBG_START_LOCAL.)
uleb128p1 sig_idx index of the type
sig_idx: string Note: See the discussion under
index of the type "dalvik.annotation.Signature
signature below for caveats about handling
signatures.

19
 Name Value Format Arguments Description
register_num: marks a currently-live local variable as
DBG_END_LOCAL 0x05 uleb128 register_num register that out of scope at the current address
contained local
re-introduces a local variable at the
current address. The name and type are
DBG_RESTART_LOCAL 0x06 uleb128 register_num register_num:
register to restart the same as the last local that was live in
the specified register.
sets the prologue_end state machine
register, indicating that the next position
entry that is added should be considered
the end of a method prologue (an
DBG_SET_PROLOGUE_END 0x07 (none) appropriate place for a method
breakpoint). The prologue_end
register is cleared by any special (
0x0a) opcode.

sets the epilogue_begin state

machine register, indicating that the next
position entry that is added should be
considered the beginning of a method
DBG_SET_EPILOGUE_BEGIN 0x08 (none) epilogue (an appropriate place to suspend
execution before method exit). The
epilogue_begin register is cleared
by any special (>= 0x0a) opcode.

name_idx:
string index of indicates that all subsequent line number
source file name; entries make reference to this source file
DBG_SET_FILE 0x09 uleb128p1 name_idx
NO_INDEX if name, instead of the default name
unknown specified in code_item

advances the line and address

registers, emits a position entry, and
Special Opcodes 0x0a…0xff (none) clears prologue_end and
epilogue_begin. See below for
description.

Special Opcodes
Opcodes with values between 0x0a and 0xff (inclusive) move both the line and address registers by a
small amount and then emit a new position table entry. The formula for the increments are as follows:

DBG_FIRST_SPECIAL = 0x0a // the smallest special opcode

DBG_LINE_BASE = -4 // the smallest line number increment
DBG_LINE_RANGE = 15 // the number of line increments represented

adjusted_opcode = opcode - DBG_FIRST_SPECIAL

line += DBG_LINE_BASE + (adjusted_opcode % DBG_LINE_RANGE)

address += (adjusted_opcode / DBG_LINE_RANGE)

annotations_directory_item
referenced from class_def_item
appears in the data section
alignment: 4 bytes

20
 Name Format Description
offset from the start of the file
to the annotations made
directly on the class, or 0 if
the class has no direct
annotations. The offset, if
class_annotations_off uint non-zero, should be to a
location in the data section.
The format of the data is
specified by
"annotation_set_item"
below.

count of fields annotated by

fields_size uint this item

count of methods annotated by

annotated_methods_off uint this item

count of method parameter

annotated_parameters_off uint lists annotated by this item

list of associated field

annotations. The elements of
field_annotations field_annotation[fields_size] (optional) the list must be sorted in
increasing order, by
field_idx.

list of associated method

annotations. The elements of
method_annotation[methods_size]
method_annotations the list must be sorted in
(optional) increasing order, by
method_idx.

list of associated method

parameter annotations. The
parameter_annotation[parameters_size]
parameter_annotations elements of the list must be
(optional) sorted in increasing order, by
method_idx.

Note: All elements' field_ids and method_ids must refer to the same defining class.

field_annotation Format

Name Format Description

index into the field_ids list for the identity of the field being
field_idx uint annotated

offset from the start of the file to the list of annotations for the field. The
annotations_off uint offset should be to a location in the data section. The format of the
data is specified by "annotation_set_item" below.

method_annotation Format

Name Format Description

index into the method_ids list for the identity of the method being
method_idx uint annotated

21
 Name Format Description
offset from the start of the file to the list of annotations for the method.
annotations_off uint The offset should be to a location in the data section. The format of
the data is specified by "annotation_set_item" below.

parameter_annotation Format

Name Format Description

index into the method_ids list for the identity of the method whose
method_idx uint parameters are being annotated

offset from the start of the file to the list of annotations for the method
parameters. The offset should be to a location in the data section.
annotations_off uint The format of the data is specified by
"annotation_set_ref_list" below.

annotation_set_ref_list
referenced from parameter_annotations_item
appears in the data section
alignment: 4 bytes

Name Format Description

size uint size of the list, in entries
list annotation_set_ref_item[size] elements of the list

annotation_set_ref_item Format

Name Format Description

offset from the start of the file to the referenced annotation set or 0 if
there are no annotations for this element. The offset, if non-zero,
annotations_off uint should be to a location in the data section. The format of the data is
specified by "annotation_set_item" below.

annotation_set_item
referenced from annotations_directory_item , field_annotations_item ,
method_annotations_item , and annotation_set_ref_item
appears in the data section

22
alignment: 4 bytes

Name Format Description

size uint size of the set, in entries
elements of the set. The elements must be sorted in
entries annotation_off_item[size] increasing order, by type_idx.

annotation_off_item Format

Name Format Description

offset from the start of the file to an annotation. The offset should be to
annotation_off uint a location in the data section, and the format of the data at that
location is specified by "annotation_item" below.

annotation_item
referenced from annotation_set_item
appears in the data section
alignment: none (byte-aligned)

Name Format Description

visibility ubyte intended visibility of this annotation (see below)
encoded annotation contents, in the format described by
annotation encoded_annotation "encoded_annotation Format" under "encoded_value
Encoding" above.

Visibility values
These are the options for the visibility field in an annotation_item:

Name Value Description

intended only to be visible at build time (e.g., during compilation of
VISIBILITY_BUILD 0x00 other code)

VISIBILITY_RUNTIME 0x01 intended to visible at runtime

intended to visible at runtime, but only to the underlying system
VISIBILITY_SYSTEM 0x02 (and not to regular user code)

23
encoded_array_item
referenced from class_def_item
appears in the data section
alignment: none (byte-aligned)

Name Format Description

bytes representing the encoded array value, in the format specified by
value encoded_array "encoded_array Format" under "encoded_value Encoding"
above.

System Annotations
System annotations are used to represent various pieces of reflective information about classes (and
methods and fields). This information is generally only accessed indirectly by client (non-system) code.

System annotations are represented in .dex files as annotations with visibility set to VISIBILITY_SYSTEM.

dalvik.annotation.AnnotationDefault
appears on methods in annotation interfaces

An AnnotationDefault annotation is attached to each annotation interface which wishes to indicate default
bindings.

Name Format Description

the default bindings for this annotation, represented as an annotation of
value Annotation this type. The annotation need not include all names defined by the
annotation; missing names simply do not have defaults.

dalvik.annotation.EnclosingClass
appears on classes

An EnclosingClass annotation is attached to each class which is either defined as a member of another
class, per se, or is anonymous but not defined within a method body (e.g., a synthetic inner class). Every
class that has this annotation must also have an InnerClass annotation. Additionally, a class may not have
both an EnclosingClass and an EnclosingMethod annotation.

24
 Name Format Description
the class which most closely lexically scopes this
value Class class

dalvik.annotation.EnclosingMethod
appears on classes

An EnclosingMethod annotation is attached to each class which is defined inside a method body. Every
class that has this annotation must also have an InnerClass annotation. Additionally, a class may not have
both an EnclosingClass and an EnclosingMethod annotation.

Name Format Description

the method which most closely lexically scopes this
value Method class

dalvik.annotation.InnerClass
appears on classes

An InnerClass annotation is attached to each class which is defined in the lexical scope of another class's
definition. Any class which has this annotation must also have either an EnclosingClass annotation or an
EnclosingMethod annotation.

Name Format Description

the originally declared simple name of this class (not including any
name String package prefix). If this class is anonymous, then the name is null.

the originally declared access flags of the class (which may differ
accessFlags int from the effective flags because of a mismatch between the execution
models of the source language and target virtual machine)

dalvik.annotation.MemberClasses
appears on classes

A MemberClasses annotation is attached to each class which declares member classes. (A member class is a
direct inner class that has a name.)

25
 Name Format Description
value Class[] array of the member classes

dalvik.annotation.Signature
appears on classes, fields, and methods

A Signature annotation is attached to each class, field, or method which is defined in terms of a more
complicated type than is representable by a type_id_item. The .dex format does not define the format for
signatures; it is merely meant to be able to represent whatever signatures a source language requires for
successful implementation of that language's semantics. As such, signatures are not generally parsed (or
verified) by virtual machine implementations. The signatures simply get handed off to higher-level APIs
and tools (such as debuggers). Any use of a signature, therefore, should be written so as not to make any
assumptions about only receiving valid signatures, explicitly guarding itself against the possibility of
coming across a syntactically invalid signature.

Because signature strings tend to have a lot of duplicated content, a Signature annotation is defined as an
array of strings, where duplicated elements naturally refer to the same underlying data, and the signature
is taken to be the concatenation of all the strings in the array. There are no rules about how to pull apart a
signature into separate strings; that is entirely up to the tools that generate .dex files.

Name Format Description

the signature of this class or member, as an array of strings that is to
value String[] be concatenated together

dalvik.annotation.Throws
appears on methods

A Throws annotation is attached to each method which is declared to throw one or more exception types.

Name Format Description

the array of exception types
value Class[] thrown

26