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. 與要解析的方法名稱的類型（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.