Dalvik 可执行文件格式

本文档介绍了 .dex 文件的版式和内容，这类文件用于保存一系列类定义及其关联的辅助数据。

类型指南

LEB128

LEB128（“Little-Endian Base 128”）表示任意有符号或无符号整数的可变长度编码。该格式借鉴了 DWARF3 规范。在 .dex 文件中，LEB128 仅用于对 32 位数字进行编码。

每个 LEB128 编码值均由 1-5 个字节组成，共同表示一个 32 位的值。每个字节均已设置其最高有效位（序列中的最后一个字节除外，其最高有效位已清除）。每个字节的剩余 7 位均为载荷，即第一个字节中有 7 个最低有效位，第二个字节中也是 7 个，依此类推。对于有符号 LEB128 (sleb128)，序列中最后一个字节的最高有效载荷位会进行符号扩展，以生成最终值。在无符号情况 (uleb128) 下，任何未明确表示的位都会被解译为 0。

变体 uleb128p1 用于表示一个有符号值，其表示法是编码为 uleb128 的值加 1。这使得 -1 的编码（或被视为无符号值 0xffffffff）成为一个单字节（但没有任何其他负数），并且该编码在下面这些情况下非常实用：所表示的数值必须为非负数或 -1（或 0xffffffff）；不允许任何其他负值（或不太可能需要使用较大的无符号值）。

以下是这类格式的一些示例：

文件版式

容器格式

41 版中为 DEX 数据引入了一种新的容器格式，目的是节省空间。这种容器格式允许将多个逻辑 DEX 文件合并到单个实体文件中。新格式主要是对采用以前格式的文件进行简单的串联，不过有一些不同之处：

• file_size 是逻辑文件的大小，而不是物理文件的大小。它可用于迭代容器中的所有逻辑文件。
• 逻辑 dex 文件可以引用容器中的任何后续数据（但不能引用早期数据）。这样，dex 文件就可以在它们之间共享数据（例如字符串）。
• 所有偏移量均相对于物理文件。没有相对于标头的偏移量。这可确保能够在逻辑文件之间共享具有偏移量的部分。
• 标头添加了两个新字段来描述容器的边界。这是一种额外的一致性检查，有助于更轻松地将代码移植到新格式。
• data_size 和 data_off 现已被弃用。数据可以分布在多个逻辑文件中，并且可以不连续。

位字段、字符串和常量定义

DEX_FILE_MAGIC

嵌在 header_item 中

常量数组/字符串 DEX_FILE_MAGIC 是字节列表，这类字节必须出现在 .dex 文件的开头，以便系统将其原样识别。该值会特意包含一个换行符（"\n" 或 0x0a）和空字节（"\0" 或 0x00），以便协助检测某些形式的损坏问题。该值还可以将格式版本号编码为 3 个十进制数字；随着格式的演变，预计该值会单调递增。

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

注意：Android 10.0 版本中增加了对 040 版格式的支持，该格式扩展了 SimpleNames 中允许使用的字符集。

注意：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 版本已用于 M3 版 Android 平台（2007 年 11 月至 12 月），013 版本已用于 M5 版 Android 平台（2008 年 2 月至 3 月）。在有些方面，这些早期版本的格式与本文档中所述的版本存在很大差异。

ENDIAN_CONSTANT 和 REVERSE_ENDIAN_CONSTANT

嵌在 header_item 中

常量 ENDIAN_CONSTANT 用于表示在文件中发现的字节序。虽然标准的 .dex 格式采用小端字节序，但具体实现可能会选择执行字节交换。如果实现遇到其 endian_tag 为 ENDIAN_CONSTANT（而非 REVERSE_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 中使用。

修改了 UTF-8 编码

考虑到继续对旧版提供支持，.dex 格式会采用按实际标准修改后的 UTF-8 形式（下文称为 MUTF-8）对其字符串数据进行编码。除以下几点以外，此形式与标准 UTF-8 形式是完全相同的：

• 仅使用单字节、双字节和三字节编码。
• U+10000 … U+10ffff 范围中的码位被编码为代理对，其中每个码位均表示为一个三字节编码值。
• 码位 U+0000 采用双字节格式形式编码。
• 纯 null 字节（值 0）表示字符串的末尾，这是标准的 C 语言解释。

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

后两项说明，MUTF-8 既可在字符串中包含代码点 U+0000，同时仍可将其作为 C 样式的 Null 终止字符串进行操作。

不过，特殊编码 U+0000 意味着，与一般 UTF-8 不同的是，针对一对 MUTF-8 字符串调用标准 C 函数 strcmp() 的结果并不一定表示不相等字符串的带正确符号的比较结果。当需要考虑排序问题（而不仅仅是相等问题）时，用于比较 MUTF-8 字符串的最简单方法是对其字符进行逐个解码，然后比较解码后的值。（不过，也许会有更智能的实现方式。）

如需详细了解字符编码，请参阅 Unicode 标准。实际上，MUTF-8 比 UTF-8 本身更接近相对而言不太为人熟知的编码 CESU-8。

encoded_value 编码

嵌在 annotation_element 和 encoded_array_item 中

encoded_value 是（几乎）任意层次结构数据的编码片。这种编码非常精简，易于解析。

值格式

encoded_array 格式

encoded_annotation 格式

annotation_element 格式

字符串语法

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

SimpleName

SimpleName 是其他内容的名称语法的基础。SimpleName.dex 格式在这方面具有相当大的宽容度（比大多数常见源语言更大）。简而言之，一个简单的名称包含任意低 ASCII 范围的字母字符或数字、几个特定的低 ASCII 范围的符号，以及不属于控件、空格或特殊字符的大多数非 ASCII 码位。从 040 版开始，该格式额外允许使用空格字符（Unicode Zs 类别）。请注意，代理码位（位于 U+d800 … U+dfff 范围内）本身不会被视为有效名称字符，但 Unicode 补充字符会被视为有效字符（由 SimpleNameChar 规则的最终替代方案表示），它们应在文件中表示为 MUTF-8 编码中的代理码位对。

MemberName

由 field_id_item 和 method_id_item 使用

MemberNameMemberName 是某个类的成员的名称，成员是指字段、方法和内部类。

FullClassName

FullClassNameFullClassName 是完全限定的类名称，包含一个可选的软件包说明符，后跟一个必需名称。

TypeDescriptor

由 type_id_item 使用

TypeDescriptor 是任何类型的表示形式，包括基元、类、数组和 void。TypeDescriptor请参阅下文，了解各版本的含义。

ShortyDescriptor

由 proto_id_item 使用

ShortyDescriptor 是方法原型的简写形式，包括返回类型和参数类型，只不过各种引用（类或数组）类型之间没有区别，ShortyDescriptor而是所有引用类型均由一个 'L' 字符表示。

TypeDescriptor 语义

以下是 TypeDescriptor 各个变体的含义。TypeDescriptor

项和相关结构

本部分包含可能在 .dex 文件中出现的各个顶级项的定义。

header_item

出现在 header 区段中

对齐：4 个字节

map_list

出现在 data 区段中

引用自 header_item

对齐：4 个字节

这是文件全部内容（依序显示）的列表。该列表包含关于 header_item 的一些冗余信息，但这些冗余信息存在的目的是提供一种用于遍历整个文件的简单方式。指定类型在映射中最多只能出现一次，但除了格式其余部分所隐含的限制条件（例如，header 区段必须先显示，随后是 string_ids 区段等等）之外，对于类型可以什么顺序显示，则没有任何限制。此外，映射条目必须按初始偏移量进行排序，不得重叠。

map_item 格式

类型代码

string_id_item

出现在 string_ids 区段中

对齐：4 个字节

string_data_item

出现在 data 区段中

对齐：无（字节对齐）

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

出现在 data 区段中

对齐：无（字节对齐）

call_site_item 是一个 encoded_array_item，其元素与提供给引导程序链接器方法的参数相对应。前 3 个参数为：

1. 表示引导程序链接器方法的方法句柄 (VALUE_METHOD_HANDLE)。
2. 引导程序链接器应解析的方法名称 (VALUE_STRING)。
3. 与要解析的方法名称类型相对应的方法类型 (VALUE_METHOD_TYPE)。

任何附加参数均为传递给引导程序链接器方法的常量值。这些参数会按顺序传递，而不进行任何类型转换。

表示引导程序链接器方法的方法句柄必须具有返回类型 java.lang.invoke.CallSite。前 3 个参数类型为：

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

任何附加参数的参数类型均由其常量值确定。

method_handle_item

出现在 method_handles 区段中

对齐：4 个字节

方法句柄类型代码

class_data_item

引用自 class_def_item

出现在 data 区段中

对齐：无（字节对齐）

注意：所有元素的 field_id 和 method_id 实例都必须引用相同的定义类。

encoded_field 格式

encoded_method 格式

type_list

引用自 class_def_item 和 proto_id_item

出现在 data 区段中

对齐：4 个字节

type_item 格式

code_item

引用自 encoded_method

出现在 data 区段中

对齐：4 个字节

try_item 格式

encoded_catch_handler_list 格式

encoded_catch_handler 格式

encoded_type_addr_pair 格式

debug_info_item

引用自 code_item

出现在 data 区段中

对齐：无（字节对齐）

每个 debug_info_item 都会定义一个基于 DWARF3 的字节码状态机，在解译时，该状态机会发出 code_item 的位置表，并可能会发出其局部变量信息。该序列的开头是一个可变长度的头文件（其长度取决于方法参数的数量），后跟状态机字节码，最后以 DBG_END_SEQUENCE 字节结尾。

该状态机由 5 个寄存器组成。address 寄存器表示关联的 insns_item 中的指令偏移量（以 16 位代码单元为单位）。address 寄存器在每个 debug_info 序列的开头处都是从 0 开始，而且只能单调递增。line 寄存器表示应与状态机发出的下一个位置表条目相关联的源行号。它在序列头文件中进行初始化，并可能会正向或负向发生更改，但绝不能小于 1。source_file 寄存器表示行号条目引用的源文件。它在 class_def_item 中被初始化为 source_file_idx 的值。另外两个变量（prologue_end 和 epilogue_begin）是布尔值标志（已初始化为 false），它们表示所发出的下一个位置是否应视为方法前序或结尾。此外，该状态机还必须跟踪用于 DBG_RESTART_LOCAL 代码的每个寄存器中最后一个局部变量的名称和类型。

标头如下所示：

字节码值如下：

特殊运算码

值在 0x0a 和 0xff（含）之间的操作码会将 line 和 address 寄存器移动一小部分，然后发出一个新的位置表条目。这些增量的公式如下所示：

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

引用自 class_def_item

出现在 data 区段中

对齐：4 个字节

注意：所有元素的 field_id 和 method_id 实例都必须引用相同的定义类。

field_annotation 格式

method_annotation 格式

parameter_annotation 格式

annotation_set_ref_list

引用自 parameter_annotations_item

出现在 data 区段中

对齐：4 个字节

annotation_set_ref_item 格式

annotation_set_item

引用自 annotations_directory_item、field_annotations_item、method_annotations_item 和 annotation_set_ref_item

出现在 data 区段中

对齐：4 个字节

annotation_off_item 格式

annotation_item

引用自 annotation_set_item

出现在 data 区段中

对齐：无（字节对齐）

visibility 值

以下是 annotation_item 中 visibility 字段的选项：

encoded_array_item

引用自 class_def_item

出现在 data 区段中

对齐：无（字节对齐）

hiddenapi_class_data_item

此部分包含每个类使用的受限接口的数据。

注意：隐藏的 API 功能是在 Android 10.0 中引入的，这些功能仅适用于启动类路径中类的 DEX 文件。未来版本的 Android 中可能会扩展下述标志列表。如需了解详情，请参阅针对非 SDK 接口的限制。

限制标记类型：

系统注释

系统注解用于表示关于类（以及方法和字段）的各种反射信息。这类信息通常只能通过客户端（非系统）代码来间接获取。

系统注解在 .dex 文件中表示为注解，可见性设为 VISIBILITY_SYSTEM。

dalvik.annotation.AnnotationDefault

出现在注解接口的方法中

AnnotationDefault 注解会附加到各个注解接口，用于表示默认绑定。

dalvik.annotation.EnclosingClass

出现在类中

EnclosingClass 注解会附加到各个类，这些类会被定义为其他类本身的成员，或者匿名显示但不在方法正文中定义（例如，合成的内部类）。具有此注解的各个类还必须具有 InnerClass 注解。此外，一个类不得同时具有 EnclosingClass 和 EnclosingMethod 注释。

dalvik.annotation.EnclosingMethod

出现在类中

EnclosingMethod 注解会附加到已在方法正文中定义的各个类。具有此注解的各个类还必须具有 InnerClass 注解。 此外，一个类不得同时具有 EnclosingClass 和 EnclosingMethod 注释。

dalvik.annotation.InnerClass

出现在类中

InnerClass 注解会附加到已在其他类定义的词法作用域中定义的各个类。具有此注解的所有类还必须具有 EnclosingClass 注解或 EnclosingMethod 注解。

dalvik.annotation.MemberClasses

出现在类中

MemberClasses 注解会附加到声明成员类（成员类是指具有名称的直接内部类）的各个类。

dalvik.annotation.MethodParameters

出现在方法中

注意：此注释在 Android 7.1 之后的版本中添加。早期 Android 版本中存在的这类注释将被忽略。

MethodParameters 注解是可选项，并可用于提供参数元数据（例如参数名称和修饰符）。

当运行时不需要参数元数据时，可在方法或构造函数中放心地省略这项注解。java.lang.reflect.Parameter.isNamePresent() 可用于检查某个参数中是否存在元数据；如果不存在这种信息，关联的反射方法（例如 java.lang.reflect.Parameter.getName()）将在运行时回退到默认行为。

如果编译器包含参数元数据，则必须包含已生成类（如枚举）的信息，因为参数元数据会指明参数是合成参数还是强制参数。

MethodParameters 注释仅用于描述单个方法的参数。因此，为了权衡代码大小和运行时效率，编译器可能会完全省略不含参数的构造函数和方法的注解。

下面记录的数组必须与该方法所关联的 method_id_item dex 结构具有相同的大小，否则运行时会抛出 java.lang.reflect.MalformedParametersException。

即：method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size 必须与 names().length 和 accessFlags().length 相同。

由于 MethodParameters 说明了所有形式化方法参数，甚至包括源代码中没有明确声明或隐式声明的参数，因此数组的大小可能不同于签名或其他元数据信息（仅基于源代码中声明的显式参数）的大小。此外，MethodParameters 也不包含任何关于实际方法签名中不存在的类型注释接收器参数的信息。

dalvik.annotation.Signature

出现在类、字段和方法中

Signature 注解会附加到各个类、字段或方法（按照比 type_id_item 所表示的类型更复杂的类型进行定义）。.dex 格式不定义签名的格式；它仅仅能够表示源语言成功实现该语言的语义所需要的任何签名。因此，签名通常不会通过虚拟机实现进行解析（或验证）。这些签名只会传递给更高级别的 API 和工具（如调试程序）。因此，每次使用签名时都应该记录下来，以免就只接收有效签名作出任何假设，从而明确防止出现句法无效的签名。

由于签名字符串往往包含很多重复内容，因此 Signature 注解会被定义为字符串数组，其中的重复元素会自然地引用相同的基本数据，而签名则被视为该数组中所有字符串的串联。对于如何将签名分割成单独的字符串，没有相关规定；这完全取决于生成 .dex 文件的工具。

dalvik.annotation.Throws

出现在方法中

Throws 注释会附加到已声明要抛出一个或多个异常类型的各个方法。