DEX file format: values and annotations

Constant values (static field initial values, call-site arguments and annotation contents) are written as encoded_values. Annotations on classes, fields, methods and parameters are reached through an annotations directory. Source: the Dalvik executable format.

encoded_value

One byte, then a payload. The byte holds value_arg in its top three bits and value_type in its low five: (value_arg << 5) | value_type. For the numeric and index types, value_arg is the payload size in bytes minus one, and the payload is little-endian with only as many bytes as needed.

value_type	Name	value_arg	Payload
`0x00`	`VALUE_BYTE`	0	1 byte, signed.
`0x02`	`VALUE_SHORT`	size − 1 (0–1)	Signed 16-bit, sign-extended from the bytes given.
`0x03`	`VALUE_CHAR`	size − 1 (0–1)	Unsigned 16-bit, zero-extended.
`0x04`	`VALUE_INT`	size − 1 (0–3)	Signed 32-bit, sign-extended.
`0x06`	`VALUE_LONG`	size − 1 (0–7)	Signed 64-bit, sign-extended.
`0x10`	`VALUE_FLOAT`	size − 1 (0–3)	IEEE 754 32-bit bit pattern, extended to the right with zero bytes (the bytes given are the high-order ones).
`0x11`	`VALUE_DOUBLE`	size − 1 (0–7)	IEEE 754 64-bit bit pattern, extended to the right with zeros.
`0x15`	`VALUE_METHOD_TYPE`	size − 1 (0–3)	Index into `proto_ids`, zero-extended.
`0x16`	`VALUE_METHOD_HANDLE`	size − 1 (0–3)	Index into `method_handles`.
`0x17`	`VALUE_STRING`	size − 1 (0–3)	Index into `string_ids`.
`0x18`	`VALUE_TYPE`	size − 1 (0–3)	Index into `type_ids`.
`0x19`	`VALUE_FIELD`	size − 1 (0–3)	Index into `field_ids`.
`0x1A`	`VALUE_METHOD`	size − 1 (0–3)	Index into `method_ids`.
`0x1B`	`VALUE_ENUM`	size − 1 (0–3)	Index into `field_ids` of an enum constant.
`0x1C`	`VALUE_ARRAY`	0	An `encoded_array`.
`0x1D`	`VALUE_ANNOTATION`	0	An `encoded_annotation`.
`0x1E`	`VALUE_NULL`	0	None: a `null` reference.
`0x1F`	`VALUE_BOOLEAN`	0 or 1	None: the value is `value_arg`, 0 for false, 1 for true.

Other value_type values are not defined. Example: the int 300 is 24 2C 01: 0x24 is value_arg 1 (two bytes) and type 0x04, then 0x012C little-endian.

encoded_array and encoded_array_item

Type and name	Meaning
`uleb128 size`	Number of elements.
`encoded_value values[size]`	The elements, one after another.

An encoded_array_item (no alignment) is just one encoded_array; it holds static field values and call sites.

encoded_annotation

Type and name	Meaning
`uleb128 type_idx`	Index into `type_ids` of the annotation type (a class type).
`uleb128 size`	Number of name–value pairs.
`annotation_element elements[size]`	The pairs, sorted by `name_idx`.

annotation_element

Type and name	Meaning
`uleb128 name_idx`	Index into `string_ids` of the element name (a MemberName).
`encoded_value value`	The element’s value.

annotations_directory_item (aligned to 4)

Offset	Size	Type and name	Meaning
`0`	4	`uint class_annotations_off`	Offset of the annotation set on the class itself, or 0.
`4`	4	`uint fields_size`	Number of annotated fields.
`8`	4	`uint annotated_methods_size`	Number of annotated methods.
`12`	4	`uint annotated_parameters_size`	Number of methods with annotated parameters.
`16`	8 × fields_size	`field_annotation field_annotations[]`	Sorted by `field_idx`.
	8 × annotated_methods_size	`method_annotation method_annotations[]`	Sorted by `method_idx`.
	8 × annotated_parameters_size	`parameter_annotation parameter_annotations[]`	Sorted by `method_idx`.

Item (8 bytes each)	Offset 0: uint	Offset 4: uint
`field_annotation`	`field_idx`, into `field_ids`	`annotations_off`: an `annotation_set_item`
`method_annotation`	`method_idx`, into `method_ids`	`annotations_off`: an `annotation_set_item`
`parameter_annotation`	`method_idx`, into `method_ids`	`annotations_off`: an `annotation_set_ref_list`

Annotation sets

annotation_set_ref_list (aligned to 4)

Offset	Size	Type and name	Meaning
`0`	4	`uint size`	Number of entries: one per parameter.
`4`	4 × size	`annotation_set_ref_item list[]`	Each a `uint annotations_off`: offset of that parameter’s `annotation_set_item`, or 0.

annotation_set_item (aligned to 4)

Offset	Size	Type and name	Meaning
`0`	4	`uint size`	Number of annotations.
`4`	4 × size	`annotation_off_item entries[]`	Each a `uint annotation_off`: offset of an `annotation_item`. In increasing order of the annotations’ `type_idx`.

annotation_item (no alignment)

Type and name	Meaning
`ubyte visibility`	Visibility, below.
`encoded_annotation annotation`	The annotation.

Value	Name	Meaning
`0x00`	`VISIBILITY_BUILD`	Visible only at build time, such as to other compiled code.
`0x01`	`VISIBILITY_RUNTIME`	Visible at run time through reflection.
`0x02`	`VISIBILITY_SYSTEM`	Visible at run time to the system only: the system annotations below.

System annotations

The specification defines these annotations, all with system visibility.

Annotation	On	Elements and meaning
`dalvik.annotation.AnnotationDefault`	annotation interfaces	`value` (Annotation): the default bindings of the interface’s elements.
`dalvik.annotation.EnclosingClass`	classes	`value` (Class): the class that most closely lexically encloses this one.
`dalvik.annotation.EnclosingMethod`	classes	`value` (Method): the enclosing method.
`dalvik.annotation.InnerClass`	classes	`name` (String, or null if anonymous) and `accessFlags` (int).
`dalvik.annotation.MemberClasses`	classes	`value` (Class[]): the member classes.
`dalvik.annotation.MethodParameters`	methods	`names` (String[]) and `accessFlags` (int[]), one entry per parameter.
`dalvik.annotation.Signature`	classes, fields, methods	`value` (String[]): pieces that are concatenated to form the generic signature.
`dalvik.annotation.Throws`	methods	`value` (Class[]): the declared exceptions.

Sources

The Android Open Source Project’s Dalvik executable format: “encoded_value encoding”, “Value formats”, “encoded_array”, “encoded_annotation”, “annotation_element”, “annotations_directory_item” and the items after it, “Visibility values” and “System annotations”. The int 300 example applies the encoding rules.

.DEX File Format – Values and annotations