Dalvik 可执行格式

本文档描述了.dex文件的布局和内容，这些文件用于保存一组类定义及其相关的附属数据。

类型指南

LEB128

LEB128（“ L ittle- E ndian Base 128 ”）是用于任意有符号或无符号整数的可变长度编码。该格式是从DWARF3规范中借用的。在.dex文件中，LEB128 仅用于编码 32 位数量。

每个 LEB128 编码值由一到五个字节组成，它们共同代表一个 32 位值。每个字节都有其最高有效位设置，除了序列中的最后一个字节，它的最高有效位被清除。每个字节的其余七位是有效载荷，第一个字节中数量的最低七位，第二个字节中接下来的七位，依此类推。在有符号 LEB128 ( sleb128 ) 的情况下，序列中最后一个字节的最高有效载荷位被符号扩展以产生最终值。在无符号情况下（ uleb128 ），任何未明确表示的位都被解释为0 。

变体uleb128p1用于表示有符号值，其中表示是值加一编码为uleb128 。这使得-1的编码（或者被认为是无符号值0xffffffff ） - 但没有其他负数 - 单个字节，并且在表示的数字必须是非负数或-1 （或0xffffffff ），并且不允许其他负值（或者不太可能需要大的无符号值）。

以下是一些格式示例：

文件布局

位域、字符串和常量定义

DEX_FILE_MAGIC

嵌入 header_item

常量数组/字符串DEX_FILE_MAGIC是必须出现在.dex文件开头的字节列表，以便被识别。该值有意包含换行符（ "\n"或0x0a ）和空字节（ "\0"或0x00 ），以帮助检测某些形式的损坏。该值还将格式版本号编码为三个十进制数字，预计随着格式的发展随着时间的推移单调增加。

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

注意： Android 9.0 版本中添加了对039版格式的支持，该版本引入了两个新字节码const-method-handle和const-method-type 。 （这些都在字节码集摘要表中进行了描述。）在 Android 10 中，版本039扩展了 DEX 文件格式，以包含仅适用于引导类路径上的 DEX 文件的隐藏 API 信息。

注意： Android 8.0 版本中添加了对038版格式的支持。 038版添加了新的字节码（ invoke-polymorphic和invoke-custom ）和方法句柄的数据。

注意： Android 7.0 版本中添加了对037版格式的支持。在037版之前，大多数 Android 版本都使用035版格式。 035和037版本的唯一区别是添加了默认方法和invoke的调整。

注意：至少有几个早期版本的格式已在广泛可用的公共软件版本中使用。例如， 009版用于 Android 平台的 M3 版本（2007 年 11 月至 2007 年 12 月），而013版用于 Android 平台的 M5 版本（2008 年 2 月至 3 月）。在几个方面，这些早期版本的格式与本文档中描述的版本有很大不同。

ENDIAN_CONSTANT 和 REVERSE_ENDIAN_CONSTANT

嵌入 header_item

常量ENDIAN_CONSTANT用于指示找到它的文件的字节序。尽管标准的.dex格式是小端的，但实现可以选择执行字节交换。如果实现遇到endian_tag是REVERSE_ENDIAN_CONSTANT而不是ENDIAN_CONSTANT的标头，它将知道该文件已从预期形式进行字节交换。

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

NO_INDEX

嵌入在 class_def_item 和 debug_info_item

常量NO_INDEX用于指示索引值不存在。

注意：此值未定义为0 ，因为这实际上通常是一个有效索引。

NO_INDEX的选定值可表示为uleb128p1编码中的单个字节。

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

access_flags 定义

嵌入在 class_def_item、encoded_field、encoded_method 和 InnerClass 中

这些标志的位域用于指示类和类成员的可访问性和整体属性。

*只允许在InnerClass注释中使用，并且不能在class_def_item中使用。

MUTF-8（修改的 UTF-8）编码

作为对遗留支持的让步， .dex格式将其字符串数据编码为事实上的标准修改 UTF-8 格式，以下称为 MUTF-8。这种形式与标准 UTF-8 相同，除了：

• 仅使用一、二和三字节编码。
• U+10000 … U+10ffff范围内的代码点被编码为代理对，每个代理对都表示为一个三字节编码值。
• 代码点U+0000以两字节形式编码。
• 一个普通的空字节（值0 ）表示字符串的结尾，标准 C 语言解释也是如此。

上面的前两项可以概括为： MUTF-8 是 UTF-16 的编码格式，而不是 Unicode 字符更直接的编码格式。

上面的最后两项可以同时将代码点U+0000包含在字符串中，并且仍然将其作为 C 风格的以空字符结尾的字符串进行操作。

但是， U+0000的特殊编码意味着，与普通的 UTF-8 不同，在一对 MUTF-8 字符串上调用标准 C 函数strcmp()的结果并不总是表明比较不相等字符串的正确签名结果.当排序（不仅仅是相等）是一个问题时，比较 MUTF-8 字符串最直接的方法是逐个字符地解码它们，然后比较解码后的值。 （然而，更聪明的实现也是可能的。）

有关字符编码的更多信息，请参阅Unicode 标准。 MUTF-8 实际上更接近（相对不太知名的）编码CESU-8 ，而不是 UTF-8 本身。

编码值编码

嵌入 annotation_element 和 encoded_array_item

encoded_value值是（几乎）任意分层结构化数据的编码片段。编码意味着既紧凑又易于解析。

值格式

编码数组格式

编码注释格式

annotation_element 格式

字符串语法

.dex文件中有几种最终引用字符串的项目。以下 BNF 样式定义指示这些字符串的可接受语法。

简单名称

SimpleName是其他事物名称语法的基础。 .dex格式在这里允许相当大的自由度（比大多数常见的源语言要多得多）。简而言之，一个简单的名称由任何低 ASCII 字母字符或数字、一些特定的低 ASCII 符号和大多数非控制、空格或特殊字符的非 ASCII 代码点组成。从版本040开始，该格式还允许使用空格字符（Unicode Zs类别）。请注意，代理代码点（在U+d800 ... U+dfff范围内）本身不被视为有效的名称字符，但 Unicode 补充字符是有效的（由SimpleNameChar规则的最终替代方案表示），并且它们应在文件中表示为 MUTF-8 编码中的代理代码点对。

成员名字

由 field_id_item 和 method_id_item 使用

MemberName是类成员的名称，成员是字段、方法和内部类。

全类名

FullClassName是一个完全限定的类名，包括一个可选的包说明符，后跟一个必需的名称。

类型描述符

由 type_id_item 使用

TypeDescriptor是任何类型的表示，包括基元、类、数组和void 。各种版本的含义见下文。

ShortyDescriptor

由 proto_id_item 使用

ShortyDescriptor是方法原型的简写形式，包括返回类型和参数类型，除了各种引用（类或数组）类型之间没有区别。相反，所有引用类型都由单个'L'字符表示。

类型描述符语义

这是TypeDescriptor的每个变体的含义。

项目和相关结构

本节包括可能出现在.dex文件中的每个顶级项目的定义。

header_item

出现在标题部分

对齐：4字节

地图列表

出现在数据部分

从 header_item 引用

对齐：4字节

这是按顺序列出的文件全部内容的列表。它包含与header_item相关的一些冗余，但旨在成为一种用于迭代整个文件的简单形式。给定类型在映射中最多只能出现一次，但除了格式的其余部分隐含的限制（例如， header部分必须首先出现，然后是string_ids节等）。此外，映射条目必须按初始偏移量排序，并且不得重叠。

map_item 格式

类型代码

string_id_item

出现在 string_ids 部分

对齐：4字节

字符串数据项

出现在数据部分

对齐方式：无（字节对齐）

type_id_item

出现在 type_ids 部分

对齐：4字节

proto_id_item

出现在 proto_ids 部分

对齐：4字节

field_id_item

出现在 field_ids 部分

对齐：4字节

method_id_item

出现在 method_ids 部分

对齐：4字节

class_def_item

出现在 class_defs 部分

对齐：4字节

call_site_id_item

出现在 call_site_ids 部分

对齐：4字节

call_site_item

出现在数据部分

对齐：无（字节对齐）

call_site_item 是一个 encoded_array_item，其元素对应于提供给引导链接器方法的参数。前三个参数是：

1. 表示引导链接器方法 (VALUE_METHOD_HANDLE) 的方法句柄。
2. 引导链接器应解析的方法名称 (VALUE_STRING)。
3. A method type corresponding to the type of the method name to be resolved (VALUE_METHOD_TYPE).

Any additional arguments are constant values passed to the bootstrap linker method. These arguments are passed in order and without any type conversions.

The method handle representing the bootstrap linker method must have return type java.lang.invoke.CallSite . The first three parameter types are:

1. java.lang.invoke.Lookup
2. java.lang.String
3. java.lang.invoke.MethodType

The parameter types of any additional arguments are determined from their constant values.

method_handle_item

appears in the method_handles section

alignment: 4 bytes

Method Handle Type Codes

class_data_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

Note: All elements' field_id s and method_id s must refer to the same defining class.

encoded_field format

encoded_method format

type_list

referenced from class_def_item and proto_id_item

appears in the data section

alignment: 4 bytes

type_item format

code_item

referenced from encoded_method

appears in the data section

alignment: 4 bytes

try_item format

encoded_catch_handler_list format

encoded_catch_handler format

encoded_type_addr_pair format

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 associated insns_item in 16-bit code units. The address register starts at 0 at the beginning of each debug_info sequence and must 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:

The byte code values are as follows:

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

Note: All elements' field_id s and method_id s must refer to the same defining class.

field_annotation format

method_annotation format

parameter_annotation format

annotation_set_ref_list

referenced from parameter_annotations_item

appears in the data section

alignment: 4 bytes

annotation_set_ref_item format

annotation_set_item

referenced from annotations_directory_item, field_annotations_item, method_annotations_item, and annotation_set_ref_item

appears in the data section

alignment: 4 bytes

annotation_off_item format

annotation_item

referenced from annotation_set_item

appears in the data section

alignment: none (byte-aligned)

Visibility values

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

encoded_array_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

hiddenapi_class_data_item

This section contains data on restricted interfaces used by each class.

Note: The hidden API feature was introduced in Android 10.0 and is only applicable to the DEX files of classes in the boot class path. The list of flags described below may be extended in the future releases of Android. For more information, see restrictions on non-SDK interfaces .

Restriction flag types:

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.

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 (eg, a synthetic inner class). Every class that has this annotation must also have an InnerClass annotation. Additionally, a class must not have both an EnclosingClass and an EnclosingMethod annotation.

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 must not have both an EnclosingClass and an EnclosingMethod annotation.

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.

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.)

dalvik.annotation.MethodParameters

appears on methods

Note: This annotation was added after Android 7.1. Its presence on earlier Android releases will be ignored.

A MethodParameters annotation is optional and can be used to provide parameter metadata such as parameter names and modifiers.

The annotation can be omitted from a method or constructor safely when the parameter metadata is not required at runtime. java.lang.reflect.Parameter.isNamePresent() can be used to check whether metadata is present for a parameter, and the associated reflection methods such as java.lang.reflect.Parameter.getName() will fall back to default behavior at runtime if the information is not present.

When including parameter metadata, compilers must include information for generated classes such as enums, since the parameter metadata includes whether or not a parameter is synthetic or mandated.

A MethodParameters annotation describes only individual method parameters. Therefore, compilers may omit the annotation entirely for constructors and methods that have no parameters, for the sake of code-size and runtime efficiency.

The arrays documented below must be the same size as for the method_id_item dex structure associated with the method, otherwise a java.lang.reflect.MalformedParametersException will be thrown at runtime.

That is: method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size must be the same as names().length and accessFlags().length .

Because MethodParameters describes all formal method parameters, even those not explicitly or implicitly declared in source code, the size of the arrays may differ from the Signature or other metadata information that is based only on explicit parameters declared in source code. MethodParameters will also not include any information about type annotation receiver parameters that do not exist in the actual method signature.

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.

dalvik.annotation.Throws

appears on methods

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