Dalvik 実行可能ファイルの形式

このドキュメントでは、クラス定義のセットとそれらに関連付けられた付属データを保持するために使用される .dex ファイルのレイアウトと内容について説明します。

型のガイド

LEB128

LEB128（Little-Endian Base 128）は、任意の符号付きまたは符号なし整数値の可変長エンコードです。形式は DWARF3 仕様から借用されたものです。.dex ファイルでは、LEB128 は 32 ビット数値のエンコードにのみ使用されます。

LEB128 でエンコードされた値は 1～5 バイトで構成され、合わせて単一の 32 ビット値を表します。シーケンス内の各バイトでは、最終バイトのみ最上位ビットがクリアされ、それ以外のバイトの最上位ビットはセットされます。各バイトの残りの 7 ビットはペイロードであり、第 1 バイトには数値の最下位 7 ビット、第 2 バイトには次の 7 ビットというように続きます。符号付き LEB128（sleb128）の場合、シーケンスの最終バイトの最上位ペイロード ビットが符号拡張されて最終値が生成されます。符号なし（uleb128）の場合、明示的に表現されていないビットはすべて 0 として解釈されます。

バリアントの uleb128p1 は符号付きの値を表現するために使用され、1 をプラスした値を uleb128 でエンコードして表現されます。これにより、-1 のエンコード（符号なしの値 0xffffffff ともみなされます）は単一バイトになります（ただし、他の負数はそうなりません）。この形式は、表現される数が必ず非負または -1（あるいは 0xffffffff）で、他の負の値が許可されない（または符号なしの大きな値が必要とされる可能性が低い）場合に有用です。

以下に各形式の例を示します。

ファイル レイアウト

コンテナ形式

バージョン 41 では、スペースの節約のため、DEX データの新しいコンテナ形式を導入します。 このコンテナ形式を使用することで、複数の論理 DEX ファイルを 1 つの物理ファイルに結合できます。 この新しい形式はほとんどの場合、以前の形式のファイルを単純に連結するだけですが、以下の点が異なります。

• file_size は物理ファイルではなく、論理ファイルのサイズになります。 コンテナ内のすべての論理ファイルに対して反復処理するのに使用できます。
• 論理 dex ファイルはコンテナに含めたどのデータも参照できます（含める前に参照することはできません）。 それによって、dex ファイル間で文字列などのデータを共有できるようにしています。
• オフセットはすべて物理ファイルを基準とします。ヘッダーを基準にしたオフセットはありません。 それによって、オフセットで指定されるセクションを論理ファイル間で共有できるようにしています。
• ヘッダーにはコンテナの境界を示す 2 つの新しいフィールドを追加します。 これを指定することで、一貫性を確認して、コードを新しい形式に容易に移植できます。
• data_size と data_off は使用されなくなりました。 複数の論理ファイルにわたるようにデータを分割できます。連続している必要はありません。

ビットフィールド、文字列、定数の定義

DEX_FILE_MAGIC

header_item に埋め込み済み

定数の配列または文字列である DEX_FILE_MAGIC は、.dex ファイルとして認識されるためにファイルの先頭に配置する必要があるバイトのリストです。この値には、特定の種類の破損を検出するために、改行（"\n" または 0x0a）と null バイト（"\0" または 0x00）が意図的に含まれています。また、この値は、ファイル形式のバージョン番号を 3 桁の 10 進数としてエンコードします。この番号は、ファイル形式が進化するにつれて単調増加することが想定されています。

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 のサポートが追加され、2 つの新しいバイトコード 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 の調整が行われている点です。

注: 広く普及している公開ソフトウェア リリースで、以前のバージョンのファイル形式が少なくとも 2 つ使用されています。たとえば、Android プラットフォームの M3 リリース（2007 年 11 月～12 月）ではバージョン 009 が使用され、Android プラットフォームの M5 リリース（2008 年 2 月～3 月）ではバージョン 013 が使用されていました。これらの古いファイル形式のバージョンでは、このドキュメントで説明しているバージョンとは大きく異なる点がいくつかあります。

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 形式では、デファクト スタンダードである修正（Modified）UTF-8（以下このドキュメントでは MUTF-8 と呼びます）形式で文字列データをエンコードします。この形式は、次の点を除いて標準の UTF-8 と同じです。

• 1 バイト、2 バイト、3 バイトのエンコードのみが使用されます。
• U+10000～U+10ffff の範囲内のコードポイントはサロゲートペアとしてエンコードされ、それぞれが 3 バイトのエンコード値として表されます。
• コードポイント U+0000 は 2 バイト形式でエンコードされます。
• 単なる null バイト（値 0）は、標準の C 言語の解釈と同様に、文字列の終わりを示します。

前半の 2 つの項目は、次のように要約できます。すなわち、MUTF-8 は Unicode 文字の直接のエンコード形式ではなく、UTF-16 用のエンコード形式です。

後半の文字列に 2 つの項目は、コードポイント 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 は、他のアイテム名の構文に対して基礎となります。.dex 形式では、名前についてかなり（一般的なソース言語のほとんどよりもはるかに）自由度があります。簡単に言うと、SimpleName は、任意の low-ASCII 英数字、いくつかの low-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

header セクションで指定

位置揃え: 4 バイト

map_list

data セクションで指定

header_item から参照

位置揃え: 4 バイト

これは、ファイルの内容全体を順番に並べたリストです。header_item については冗長性が多少含まれますが、ファイル全体を反復処理しやすい形式を意図しています。各型をマップ内で指定できるのは最大 1 回ですが、残りの形式によって暗黙的に規定される制限（たとえば 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 の値に初期化されます。他の 2 つの変数 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

このセクションには、各クラスによって使用される制限付きインターフェースに関するデータが含まれます。

注: Android 10.0 で、非表示 API 機能が導入されました。これは、ブート クラスパス内のクラスの DEX ファイルにのみ適用されます。下記に規定するフラグのリストは、Android の今後のリリースで拡張される可能性があります。詳細については、非 SDK インターフェースの制限をご覧ください。

制限フラグの種類:

システム アノテーション

システム アノテーションは、クラス（およびメソッドとフィールド）に関するさまざまなリフレクティブ情報を表すために使用されます。一般的に、この情報はクライアント コード（システム以外のコード）によって間接的にのみアクセスされます。

システム アノテーションは、.dex ファイル内では、参照可能性を VISIBILITY_SYSTEM に設定したアノテーションとして表現されます。

dalvik.annotation.AnnotationDefault

アノテーション インターフェース内のメソッドで指定

AnnotationDefault アノテーションは、デフォルト バインディングを示す各アノテーション インターフェースに添付されます。

dalvik.annotation.EnclosingClass

クラスで指定

EnclosingClass アノテーションは、本来別のクラスのメンバーとして定義されるクラスか、匿名でもメソッド本体内で定義されないクラス（合成内部クラスなど）ごとに添付されます。このアノテーションが添付されたすべてのクラスには、InnerClass アノテーションも添付されます。また、1 つのクラスに EnclosingClass アノテーションと EnclosingMethod アノテーションの両方を添付することはできません。

dalvik.annotation.EnclosingMethod

クラスで指定

EnclosingMethod アノテーションは、メソッド本体の内部で定義される各クラスに添付されます。このアノテーションが添付されたすべてのクラスには、InnerClass アノテーションも添付されます。また、1 つのクラスに 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() などの関連リフレクション メソッドが失敗すると、代わりにデフォルトの動作が実行されます。

コンパイラがパラメータ メタデータを含める場合は、enum などの生成クラスの情報を含める必要があります。パラメータ メタデータには、パラメータが合成かどうか、また強制かどうかの情報が含まれるためです。

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 アノテーションは、1 つ以上の例外タイプをスローするように宣言された各メソッドに添付されます。