Dalvik 実行形式

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

タイプガイド

LEB128

LEB128 (" L ittle- Endian Base 128 ") は、任意の符号付きまたは符号なし整数量の可変長エンコーディングです。形式はDWARF3仕様から借用されました。 .dexファイルでは、LEB128 は 32 ビット量をエンコードするためにのみ使用されます。

LEB128 でエンコードされた各値は、1 から 5 バイトで構成され、これらを合わせて 1 つの 32 ビット値を表します。各バイトには、最上位ビットがクリアされているシーケンスの最後のバイトを除いて、最上位ビットが設定されています。各バイトの残りの 7 ビットはペイロードであり、量の最下位 7 ビットが最初のバイトに、次の 7 ビットが 2 番目のバイトに、というように続きます。符号付き LEB128 ( sleb128 ) の場合、シーケンスの最終バイトの最上位ペイロード ビットが符号拡張されて、最終値が生成されます。符号なしの場合 ( uleb128 )、明示的に表されていないビットは0として解釈されます。

バリアントuleb128p1は、符号付きの値を表すために使用されます。この表現は、 uleb128としてエンコードされた値に 1 を加えたものです。これにより、 -1 (符号なしの値0xffffffffと考えられる) のエンコーディングが作成されますが、他の負の数は 1 バイトではなく、表現される数値が非負または-1 (または0xffffffff )、およびその他の負の値が許可されていない場所 (または大きな符号なし値が必要になる可能性が低い場所)。

フォーマットの例を次に示します。

ファイルのレイアウト

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

DEX_FILE_MAGIC

header_item に埋め込まれています

定数配列/文字列DEX_FILE_MAGICは、.dex ファイルとして認識されるために、 .dexファイルの先頭に表示される必要があるバイトのリストです。特定の形式の破損の検出に役立つように、値には意図的に改行 ( "\n"または0x0a ) と NULL バイト ( "\0"または0x00 ) が含まれています。この値は、フォーマットのバージョン番号も 3 桁の 10 進数としてエンコードします。これは、フォーマットが進化するにつれて時間の経過とともに単調に増加すると予想されます。

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

注:この形式のバージョン039のサポートは Android 9.0 リリースで追加され、2 つの新しいバイトコードconst-method-handleとconst-method-typeが導入されました。 Android 10 では、バージョン039でDEXファイル形式が拡張され、ブート クラス パス上の DEX ファイルにのみ適用される非表示の API 情報が含まれるようになりました。

注:バージョン038の形式のサポートは、Android 8.0 リリースで追加されました。バージョン038では、新しいバイトコード ( invoke-polymorphicおよびinvoke-custom ) とメソッド ハンドルのデータが追加されました。

注:バージョン037の形式のサポートは、Android 7.0 リリースで追加されました。バージョン037より前の Android のほとんどのバージョンでは、バージョン035の形式が使用されていました。バージョン035と037の唯一の違いは、デフォルト メソッドの追加とinvokeの調整です。

注:この形式の少なくとも 2 つの以前のバージョンは、広く入手可能な公開ソフトウェア リリースで使用されています。たとえば、バージョン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エンコーディングで 1 バイトとして表現できます。

uint NO_INDEX = 0xffffffff;    // == -1 if treated as a signed int

access_flags の定義

class_def_item、encoded_field、encoded_method、および InnerClass に埋め込まれています

これらのフラグのビットフィールドは、クラスとクラス メンバーのアクセシビリティと全体的なプロパティを示すために使用されます。

* InnerClassアノテーションでのみ on が許可され、 class_def_itemで on であってはなりません。

MUTF-8 (修正 UTF-8) エンコーディング

より簡単なレガシー サポートへの譲歩として、 .dex形式はその文字列データを事実上の標準の変更された UTF-8 形式 (以降、MUTF-8 と呼びます) でエンコードします。この形式は、次の点を除いて、標準の UTF-8 と同じです。

• 1、2、および 3 バイトのエンコーディングのみが使用されます。
• U+10000 … U+10ffffの範囲のコード ポイントは、それぞれが 3 バイトのエンコードされた値として表されるサロゲート ペアとしてエンコードされます。
• コード ポイントU+0000は 2 バイト形式でエンコードされます。
• 通常のヌル バイト (値0 ) は、標準の C 言語の解釈と同様に、文字列の末尾を示します。

上記の最初の 2 つの項目は次のように要約できます。MUTF-8 は、Unicode 文字のより直接的なエンコーディング形式ではなく、UTF-16 のエンコーディング形式です。

上記の最後の 2 つの項目により、コード ポイントU+0000を文字列に含め、それを C スタイルのヌル終了文字列として操作することが同時に可能になります。

ただし、 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は、(ほぼ) 任意の階層構造データのエンコードされた断片です。エンコーディングは、コンパクトで簡単に解析できるようにすることを目的としています。

値の形式

エンコードされた配列形式

エンコードされた注釈形式

注釈要素の形式

文字列構文

最終的に文字列を参照する.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

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に関していくらかの冗長性が含まれていますが、ファイル全体を反復処理するために使用する簡単な形式になることを目的としています。与えられたタイプは、マップ内で最大 1 回出現する必要がありますが、形式の残りの部分によって暗示される制限を除いて、タイプが出現する順序に制限はありません (たとえば、 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 です。最初の 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

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.