Dalvik 可执行文件格式

使用合集保持井井有条 根据您的偏好保存内容并对其进行分类。

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

类型指南

LEB128

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

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

变体 uleb128p1 用于表示有符号值，其中表示形式是值加一，编码为 uleb128。这使得 -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)，以帮助检测某些形式的损坏。该值还以三个十进制数字编码格式版本号，随着格式的演变，预计该版本号会单调递增。

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 文件格式，以包含隐藏的 API 信息，该信息仅适用于引导类路径上的 DEX 文件。

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

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

注意： 至少在广泛可用的公共软件版本中使用了几个早期版本的格式。例如，版本 009 用于 Android 平台的 M3 版本（2007 年 11 月至 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 中出现。

Modified UTF-8 编码

作为对更轻松的旧版支持的让步，.dex 格式以事实上的标准 modified 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 本身。

encoded_value 编码

嵌入在 annotation_element 和 encoded_array_item 中

encoded_value 是编码的一段（几乎）任意分层结构化数据。该编码旨在既紧凑又易于解析。

值格式

encoded_array 格式

encoded_annotation 格式

annotation_element 格式

字符串语法

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

SimpleName

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

MemberName

由 field_id_item 和 method_id_item 使用

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

FullClassName

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

TypeDescriptor

由 type_id_item 使用

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

ShortyDescriptor

由 proto_id_item 使用

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

TypeDescriptor 语义

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

项和相关结构

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

header_item

出现在标头部分

对齐：4 字节

map_list

出现在 data 区段中

从 header_item 引用

对齐：4 字节

这是文件中所有内容的列表，按顺序排列。它相对于 header_item 有一些冗余，但旨在成为一种易于使用的形式，用于遍历整个文件。给定类型在一个 map 中最多出现一次，但对类型的出现顺序没有限制，除了格式的其余部分所暗示的限制（例如，header 区段必须首先出现，然后是 string_ids 区段等）。此外，map 条目必须按初始偏移量排序，并且不得重叠。

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，其元素对应于提供给引导链接器方法的参数。前三个参数是

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

任何其他参数都是传递给引导链接器方法的常量值。这些参数按顺序传递，不进行任何类型转换。

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

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 字节结束。

状态机由五个寄存器组成。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 区段中

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

可见性值

以下是 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 描述了所有形式方法参数，甚至包括那些在源代码中未显式或隐式声明的参数，因此数组的大小可能与仅基于源代码中声明的显式参数的 Signature 或其他元数据信息不同。MethodParameters 也不包含关于实际方法签名中不存在的类型注解接收器参数的任何信息。

dalvik.annotation.Signature

出现在类、字段和方法中

Signature 注解附加到每个类、字段或方法，这些类、字段或方法是根据比 type_id_item 可表示的更复杂的类型定义的。.dex 格式未定义签名的格式；它仅仅意味着能够表示源语言实现该语言语义成功所需的任何签名。因此，虚拟机实现通常不解析（或验证）签名。签名只是传递给更高级别的 API 和工具（例如调试器）。因此，签名的任何使用都应编写为不假设仅接收有效的签名，而是显式地保护自身免受遇到语法无效签名的可能性。

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

dalvik.annotation.Throws

出现在方法中

每个声明为抛出一个或多个异常类型的方法都附加有 Throws 注解。