Ausführbares Dalvik-Format

Dieses Dokument beschreibt das Layout und den Inhalt von .dex Dateien, die verwendet werden, um eine Reihe von Klassendefinitionen und ihre zugehörigen Zusatzdaten zu speichern.

Leitfaden für Typen

LEB128

LEB128 ("Little- E ndian Base 128 ") ist eine Codierung mit variabler Länge für beliebige vorzeichenbehaftete oder vorzeichenlose ganzzahlige Größen. Das Format wurde der DWARF3- Spezifikation entlehnt. In einer .dex Datei wird LEB128 immer nur zum Codieren von 32-Bit-Mengen verwendet.

Jeder LEB128-codierte Wert besteht aus einem bis fünf Bytes, die zusammen einen einzelnen 32-Bit-Wert darstellen. Jedes Byte hat sein höchstwertiges Bit gesetzt, mit Ausnahme des letzten Bytes in der Sequenz, dessen höchstwertiges Bit gelöscht ist. Die verbleibenden sieben Bits jedes Bytes sind Nutzdaten, wobei die niederwertigsten sieben Bits der Menge im ersten Byte, die nächsten sieben im zweiten Byte und so weiter stehen. Im Fall eines vorzeichenbehafteten LEB128 ( sleb128 ) wird das höchstwertige Nutzdatenbit des letzten Bytes in der Sequenz vorzeichenerweitert, um den endgültigen Wert zu erzeugen. Im vorzeichenlosen Fall ( uleb128 ) werden alle nicht explizit dargestellten Bits als 0 interpretiert.

Die Variante uleb128p1 wird verwendet, um einen vorzeichenbehafteten Wert darzustellen, wobei die Darstellung aus dem Wert plus eins besteht, der als uleb128 codiert ist. Dies macht die Codierung von -1 (alternativ als vorzeichenloser Wert 0xffffffff ) – aber keiner anderen negativen Zahl – zu einem einzelnen Byte und ist genau in den Fällen nützlich, in denen die dargestellte Zahl entweder nicht negativ oder -1 (bzw 0xffffffff ) und wo keine anderen negativen Werte erlaubt sind (oder wo wahrscheinlich keine großen vorzeichenlosen Werte benötigt werden).

Hier sind einige Beispiele für die Formate:

Dateilayout

Bitfeld-, String- und Konstantendefinitionen

DEX_FILE_MAGIC

eingebettet in header_item

Die Konstante Array/String DEX_FILE_MAGIC ist die Liste der Bytes, die am Anfang einer .dex Datei stehen müssen, damit sie als solche erkannt wird. Der Wert enthält absichtlich einen Zeilenumbruch ( "\n" oder 0x0a ) und ein Nullbyte ( "\0" oder 0x00 ), um bei der Erkennung bestimmter Formen von Korruption zu helfen. Der Wert codiert auch eine Formatversionsnummer als drei Dezimalziffern, von der erwartet wird, dass sie mit der Zeit monoton zunimmt, wenn sich das Format weiterentwickelt.

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

Hinweis: Die Unterstützung für Version 039 des Formats wurde in der Android 9.0-Version hinzugefügt, die zwei neue Bytecodes eingeführt hat, const-method-handle und const-method-type . (Diese werden jeweils in der Tabelle Zusammenfassung der Bytecodesätze beschrieben.) In Android 10 erweitert Version 039 das DEX-Dateiformat um versteckte API-Informationen, die nur für DEX-Dateien im Startklassenpfad gelten.

Hinweis: Die Unterstützung für Version 038 des Formats wurde in der Android 8.0-Version hinzugefügt. Version 038 fügte neue Bytecodes ( invoke-polymorphic und invoke-custom ) und Daten für Methodenhandles hinzu.

Hinweis: Die Unterstützung für Version 037 des Formats wurde in der Version Android 7.0 hinzugefügt. Vor Version 037 haben die meisten Android-Versionen Version 035 des Formats verwendet. Der einzige Unterschied zwischen den Versionen 035 und 037 ist das Hinzufügen von Standardmethoden und die Anpassung des invoke .

Hinweis: Mindestens ein paar frühere Versionen des Formats wurden in weit verbreiteten öffentlichen Softwareversionen verwendet. Beispielsweise wurde Version 009 für die M3-Versionen der Android-Plattform (November–Dezember 2007) und Version 013 für die M5-Versionen der Android-Plattform (Februar–März 2008) verwendet. Diese früheren Versionen des Formats unterscheiden sich in mehrfacher Hinsicht erheblich von der in diesem Dokument beschriebenen Version.

ENDIAN_CONSTANT und REVERSE_ENDIAN_CONSTANT

eingebettet in header_item

Die Konstante ENDIAN_CONSTANT wird verwendet, um die Endianness der Datei anzugeben, in der sie gefunden wird. Obwohl das standardmäßige .dex -Format Little-Endian ist, können Implementierungen Byte-Swapping durchführen. Sollte eine Implementierung auf einen Header stoßen, dessen endian_tag REVERSE_ENDIAN_CONSTANT statt ENDIAN_CONSTANT ist, würde sie wissen, dass die Datei von der erwarteten Form byte-ausgetauscht wurde.

uint ENDIAN_CONSTANT = 0x12345678;
uint REVERSE_ENDIAN_CONSTANT = 0x78563412;

NO_INDEX

eingebettet in class_def_item und debug_info_item

Die Konstante NO_INDEX wird verwendet, um anzuzeigen, dass ein Indexwert fehlt.

Hinweis: Dieser Wert ist nicht als 0 definiert, da dies normalerweise ein gültiger Index ist.

Der gewählte Wert für NO_INDEX ist als einzelnes Byte in der uleb128p1 Codierung darstellbar.

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

access_flags-Definitionen

eingebettet in class_def_item, encoded_field, encoded_method und InnerClass

Bitfelder dieser Flags werden verwendet, um die Zugänglichkeit und Gesamteigenschaften von Klassen und Klassenmitgliedern anzuzeigen.

* Nur für InnerClass Anmerkungen zulässig und darf niemals in einem class_def_item .

MUTF-8 (modifiziertes UTF-8) Kodierung

Als Zugeständnis an eine einfachere Legacy-Unterstützung codiert das .dex -Format seine Zeichenfolgendaten in einer de facto standardmäßig modifizierten UTF-8-Form, die im Folgenden als MUTF-8 bezeichnet wird. Dieses Formular ist identisch mit Standard-UTF-8, außer:

• Es werden nur die Ein-, Zwei- und Drei-Byte-Codierungen verwendet.
• Codepunkte im Bereich U+10000 … U+10ffff werden als Ersatzpaar codiert, von denen jeder als ein codierter Drei-Byte-Wert dargestellt wird.
• Der Codepunkt U+0000 ist in Zwei-Byte-Form codiert.
• Ein einfaches Null-Byte (Wert 0 ) zeigt das Ende einer Zeichenfolge an, wie dies auch bei der Standardinterpretation der Sprache C der Fall ist.

Die ersten beiden obigen Elemente können wie folgt zusammengefasst werden: MUTF-8 ist ein Codierungsformat für UTF-16, anstatt ein direkteres Codierungsformat für Unicode-Zeichen zu sein.

Die letzten beiden obigen Elemente ermöglichen es gleichzeitig, den Codepunkt U+0000 in einen String aufzunehmen und ihn dennoch als nullterminierten String im C-Stil zu bearbeiten.

Die spezielle Codierung von U+0000 bedeutet jedoch, dass im Gegensatz zu normalem UTF-8 das Ergebnis des Aufrufs der Standard-C-Funktion strcmp() für ein Paar von MUTF-8-Strings nicht immer das ordnungsgemäß signierte Ergebnis des Vergleichs ungleicher Strings anzeigt . Wenn die Reihenfolge (nicht nur die Gleichheit) ein Problem darstellt, besteht die einfachste Methode zum Vergleichen von MUTF-8-Strings darin, sie Zeichen für Zeichen zu decodieren und die decodierten Werte zu vergleichen. (Es sind jedoch auch cleverere Implementierungen möglich.)

Weitere Informationen zur Zeichencodierung finden Sie im Unicode-Standard . MUTF-8 ist eigentlich näher an der (relativ weniger bekannten) Codierung CESU-8 als an UTF-8 per se.

encoded_value Codierung

eingebettet in annotation_element und encoded_array_item

Ein encoded_value ist ein codiertes Stück (fast) beliebiger hierarchisch strukturierter Daten. Die Codierung soll sowohl kompakt als auch einfach zu analysieren sein.

Wertformate

encoded_array-Format

encoded_annotation-Format

annotation_element-Format

String-Syntax

Es gibt mehrere Arten von Elementen in einer .dex -Datei, die letztendlich auf eine Zeichenfolge verweisen. Die folgenden Definitionen im BNF-Stil geben die akzeptable Syntax für diese Zeichenfolgen an.

EinfacherName

Ein SimpleName ist die Grundlage für die Syntax der Namen anderer Dinge. Das .dex Format lässt hier ziemlich viel Spielraum (viel mehr als die meisten gängigen Quellsprachen). Kurz gesagt, ein einfacher Name besteht aus beliebigen Buchstaben oder Ziffern im Low-ASCII-Format, einigen spezifischen Low-ASCII-Symbolen und den meisten Nicht-ASCII-Codepunkten, die keine Steuerzeichen, Leerzeichen oder Sonderzeichen sind. Ab Version 040 erlaubt das Format zusätzlich Leerzeichen (Kategorie Unicode Zs ). Beachten Sie, dass Ersatzcodepunkte (im Bereich U+d800 … U+dfff ) per se nicht als gültige Namenszeichen gelten, aber Unicode-Ergänzungszeichen gültig sind (die durch die letzte Alternative der Regel für SimpleNameChar dargestellt werden ), und sie sollten in einer Datei als Paare von Ersatzcodepunkten in der MUTF-8-Codierung dargestellt werden.

Mitgliedsname

Wird von field_id_item und method_id_item verwendet

Ein MemberName ist der Name eines Members einer Klasse, wobei Member Felder, Methoden und innere Klassen sind.

Vollständiger Klassenname

Ein FullClassName ist ein vollständig qualifizierter Klassenname, einschließlich eines optionalen Paketbezeichners, gefolgt von einem erforderlichen Namen.

TypeDescriptor

Wird von type_id_item verwendet

Ein TypeDescriptor ist die Darstellung eines beliebigen Typs, einschließlich Primitiven, Klassen, Arrays und void . Siehe unten für die Bedeutung der verschiedenen Versionen.

ShortyDescriptor

Wird von proto_id_item verwendet

Ein ShortyDescriptor ist die Kurzformdarstellung eines Methodenprototyps, einschließlich Rückgabe- und Parametertypen, außer dass es keinen Unterschied zwischen verschiedenen Referenztypen (Klassen oder Arrays) gibt. Stattdessen werden alle Referenztypen durch ein einzelnes 'L' -Zeichen dargestellt.

TypeDescriptor- Semantik

Dies ist die Bedeutung jeder der Varianten von TypeDescriptor .

Artikel und verwandte Strukturen

Dieser Abschnitt enthält Definitionen für alle Elemente der obersten Ebene, die in einer .dex -Datei vorkommen können.

header_item

erscheint im Kopfbereich

Ausrichtung: 4 Byte

map_list

erscheint im Datenbereich

referenziert von header_item

Ausrichtung: 4 Byte

Dies ist eine geordnete Liste des gesamten Inhalts einer Datei. Es enthält eine gewisse Redundanz in Bezug auf das header_item , soll aber eine einfache Form sein, die verwendet werden kann, um eine ganze Datei zu durchlaufen. Ein gegebener Typ darf höchstens einmal in einer Karte erscheinen, aber es gibt keine Beschränkung, in welcher Reihenfolge Typen erscheinen dürfen, abgesehen von den Einschränkungen, die durch den Rest des Formats impliziert werden (z. B. muss zuerst ein header -Abschnitt erscheinen, gefolgt von einer string_ids Abschnitt usw.). Außerdem müssen die Zuordnungseinträge nach anfänglichem Offset sortiert werden und dürfen sich nicht überlappen.

map_item-Format

Typencodes

string_id_item

erscheint im Abschnitt string_ids

Ausrichtung: 4 Byte

string_data_item

erscheint im Datenbereich

Ausrichtung: keine (Byte-ausgerichtet)

type_id_item

erscheint im Abschnitt type_ids

Ausrichtung: 4 Bytes

proto_id_item

erscheint im Abschnitt proto_ids

Ausrichtung: 4 Bytes

field_id_item

erscheint im Abschnitt field_ids

Ausrichtung: 4 Byte

method_id_item

erscheint im Abschnitt method_ids

Ausrichtung: 4 Byte

class_def_item

erscheint im Abschnitt class_defs

Ausrichtung: 4 Byte

call_site_id_item

erscheint im Abschnitt call_site_ids

Ausrichtung: 4 Bytes

call_site_item

erscheint im Datenbereich

Ausrichtung: keine (Byte ausgerichtet)

Das call_site_item ist ein encoded_array_item, dessen Elemente den Argumenten entsprechen, die einer Bootstrap-Linker-Methode bereitgestellt werden. Die ersten drei Argumente sind:

1. Ein Methoden-Handle, das die Bootstrap-Linker-Methode darstellt (VALUE_METHOD_HANDLE).
2. Ein Methodenname, den der Bootstrap-Linker auflösen soll (VALUE_STRING).
3. Ein Methodentyp, der dem Typ des aufzulösenden Methodennamens entspricht (VALUE_METHOD_TYPE).

Alle zusätzlichen Argumente sind konstante Werte, die an die Bootstrap-Linker-Methode übergeben werden. 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.