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。(請參閱「Bytecode 集合摘要」表格，瞭解各個集合的說明。)在 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 月至 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 中開啟。

修改過的 UTF-8 編碼

為了讓舊版支援更容易，.dex 格式會以實際標準的修改版 UTF-8 格式編碼字串資料，以下稱為 MUTF-8。這份表單與標準 UTF-8 相同，但有以下差異：

• 只使用一、二和三位元組編碼。
• 範圍為 U+10000 … U+10ffff 的碼點會編碼為替代字元組，每個組合都會以三個位元組的編碼值表示。
• 程式碼點 U+0000 是以兩位元組形式編碼。
• 標準的空值位元組 (值 0) 表示字串結尾，這也是標準的 C 語言解讀方式。

上述前兩項內容可歸納為：MUTF-8 是 UTF-16 的編碼格式，而非萬國碼字元的直接編碼格式。

上述最後兩項項目可讓您同時在字串中加入程式碼點 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) 本身不視為有效的名稱字元，但萬國碼輔助字元「是」有效 (由 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

顯示在資料部分

由 header_item 參照

對齊方式：4 個位元組

這是檔案的完整內容清單，並按順序排列。它與 header_item 相比含有部分重複內容，但其目的是提供簡單的形式，以便對整個檔案進行迴迭。特定類型在地圖中最多只能出現一次，但除了格式其餘部分暗示的限制外，不限制類型出現的順序。舉例來說，header 區段必須先出現，接著才是 string_ids 區段，以此類推。此外，地圖項目必須依初始偏移量排序，且不得重疊。

map_item 格式

類型代碼

string_id_item

會顯示在 string_ids 區段

對齊方式：4 個位元組

string_data_item

顯示在資料部分

對齊方式：無 (位元組對齊)

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) 相對應的方法類型。

任何額外引數都是傳遞至 Bootstrap 連結器方法的常數值。這些引數會依序傳遞，且不會進行任何類型轉換。

代表引導程式連結器方法的方法句柄，必須具有 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 參照

顯示在資料部分

對齊方式：無 (位元組對齊)

注意：所有元素的 field_id 和 method_id 例項都必須參照相同的定義類別。

encoded_field 格式

encoded_method 格式

type_list

由 class_def_item 和 proto_id_item 參照

顯示在資料部分

對齊方式：4 個位元組

type_item 格式

code_item

參照自 encoded_method

顯示在資料部分

對齊方式：4 個位元組

try_item 格式

encoded_catch_handler_list 格式

encoded_catch_handler 格式

encoded_type_addr_pair 格式

debug_info_item

參照自 code_item

顯示在資料部分

對齊方式：無 (位元組對齊)

每個 debug_info_item 都會定義 DWARF3 風格的位元組編碼狀態機器，在解譯時會為 code_item 發出位置表和 (可能的) 本機變數資訊。這個序列以可變長度的標頭 (長度取決於方法參數數量) 開頭，後面接著狀態機器 bytecode，最後以 DBG_END_SEQUENCE 位元組結尾。

狀態機器由五個暫存器組成。address 登錄器代表 16 位元程式碼單位中相關 insns_item 的指令偏移量。address 登錄會從每個 debug_info 序列開頭的 0 開始，且只能單調遞增。line 註冊代表應與狀態機器所發出的下一個位置表格項目相關聯的來源行號。這項值會在序列標頭中初始化，且可能會在正向或負向方向變更，但絕對不能低於 1。source_file 註冊表代表行號項目參照的來源檔案。系統會將其初始化為 class_def_item 中的 source_file_idx 值。其他兩個變數 prologue_end 和 epilogue_begin 是布林值標記 (初始化為 false)，用於指出下一個產生的位址應視為方法序言還是序尾。狀態機器人也必須追蹤 DBG_RESTART_LOCAL 程式碼中每個暫存器中最後一個本機變數的名稱和類型。

標頭如下：

位元組碼值如下：

特殊 Opcode

值介於 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 參照

顯示在資料部分

對齊方式：4 個位元組

注意：所有元素的 field_id 和 method_id 例項都必須參照相同的定義類別。

field_annotation 格式

method_annotation 格式

parameter_annotation 格式

annotation_set_ref_list

參照自 parameter_annotations_item

顯示在資料部分

對齊方式：4 個位元組

annotation_set_ref_item 格式

annotation_set_item

參照自 annotations_directory_item、field_annotations_item、method_annotations_item 和 annotation_set_ref_item

顯示在資料部分

對齊方式：4 個位元組

annotation_off_item 格式

annotation_item

參照自 annotation_set_item

顯示在資料部分

對齊方式：無 (位元組對齊)

瀏覽權限值

以下是 annotation_item 中 visibility 欄位的選項：

encoded_array_item

由 class_def_item 參照

顯示在資料部分

對齊方式：無 (位元組對齊)

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 註解，這些方法會宣告擲回一或多個例外狀況類型。