Format wykonywalny Dalvik

Ten dokument opisuje układ i zawartość plików .dex , które są używane do przechowywania zestawu definicji klas i skojarzonych z nimi danych pomocniczych.

Przewodnik po typach

LEB128

LEB128 ("Little - Endian B ase 128 ") to kodowanie o zmiennej długości dla dowolnych liczb całkowitych ze znakiem lub bez znaku. Format został zapożyczony ze specyfikacji DWARF3 . W pliku .dex LEB128 jest używany tylko do kodowania wielkości 32-bitowych.

Każda zakodowana wartość LEB128 składa się z jednego do pięciu bajtów, które razem reprezentują pojedynczą wartość 32-bitową. Każdy bajt ma ustawiony swój najbardziej znaczący bit, z wyjątkiem ostatniego bajtu w sekwencji, który ma swój najbardziej znaczący bit. Pozostałe siedem bitów każdego bajtu to ładunek, z najmniej znaczącymi siedmioma bitami ilości w pierwszym bajcie, kolejnymi siedmioma w drugim bajcie i tak dalej. W przypadku LEB128 ze znakiem ( sleb128 ), najbardziej znaczący bit ładunku końcowego bajtu w sekwencji jest rozszerzony o znak, aby wytworzyć wartość końcową. W przypadku bez znaku ( uleb128 ) wszelkie bity, które nie są jawnie reprezentowane, są interpretowane jako 0 .

Wariant uleb128p1 służy do reprezentowania wartości ze znakiem, gdzie reprezentacją jest wartość plus jeden zakodowana jako uleb128 . To sprawia, że ​​kodowanie -1 (alternatywnie uważane za wartość bez znaku 0xffffffff ) — ale żadnej innej liczby ujemnej — jest pojedynczym bajtem i jest przydatne dokładnie w tych przypadkach, w których reprezentowana liczba musi być nieujemna lub -1 (lub 0xffffffff ) i gdzie nie są dozwolone żadne inne wartości ujemne (lub gdy duże wartości bez znaku są mało prawdopodobne).

Oto kilka przykładów formatów:

Układ pliku

Definicje pól bitowych, łańcuchów i stałych

DEX_FILE_MAGIC

osadzone w header_item

Stała tablica/łańcuch DEX_FILE_MAGIC to lista bajtów, które muszą pojawić się na początku pliku .dex , aby został on rozpoznany jako taki. Wartość celowo zawiera znak nowej linii ( "\n" lub 0x0a ) i bajt null ( "\0" lub 0x00 ), aby pomóc w wykrywaniu pewnych form uszkodzenia. Wartość koduje również numer wersji formatu jako trzy cyfry dziesiętne, które zgodnie z oczekiwaniami będą wzrastać w miarę rozwoju formatu.

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

Uwaga: w wersji Android 9.0 dodano obsługę wersji 039 formatu, która wprowadziła dwa nowe kody bajtowe const-method-handle i const-method-type . (Każdy z nich jest opisany w tabeli Podsumowanie zestawu kodów bajtowych ). W systemie Android 10 wersja 039 rozszerza format pliku DEX o ukryte informacje o interfejsie API, które mają zastosowanie tylko do plików DEX w ścieżce klasy rozruchowej.

Uwaga: w wersji Android 8.0 dodano obsługę wersji 038 formatu. Wersja 038 dodała nowe kody bajtowe ( invoke-polymorphic i invoke-custom ) oraz dane dla uchwytów metod.

Uwaga: w wersji Androida 7.0 dodano obsługę wersji 037 formatu. Przed wersją 037 większość wersji Androida używała wersji 035 formatu. Jedyną różnicą między wersjami 035 i 037 jest dodanie metod domyślnych i dostosowanie invoke .

Uwaga: co najmniej kilka wcześniejszych wersji tego formatu było używanych w powszechnie dostępnych publicznych wydaniach oprogramowania. Na przykład wersja 009 była używana w wersjach M3 platformy Android (listopad–grudzień 2007), a wersja 013 była używana w wersjach M5 platformy Android (luty–marzec 2008). Pod kilkoma względami te wcześniejsze wersje formatu znacznie różnią się od wersji opisanej w tym dokumencie.

ENDIAN_CONSTANT i REVERSE_ENDIAN_CONSTANT

osadzone w header_item

Stała ENDIAN_CONSTANT służy do wskazania endianowości pliku, w którym się znajduje. Chociaż standardowy format .dex jest little-endian, implementacje mogą zdecydować się na wymianę bajtów. Jeśli implementacja napotka nagłówek, którego endian_tag to REVERSE_ENDIAN_CONSTANT zamiast ENDIAN_CONSTANT , będzie wiedziała, że ​​plik został zastąpiony bajtami z oczekiwanej postaci.

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

NO_INDEX

osadzone w class_def_item i debug_info_item

Stała NO_INDEX służy do wskazania braku wartości indeksu.

Uwaga: ta wartość nie jest zdefiniowana jako 0 , ponieważ w rzeczywistości jest to zazwyczaj prawidłowy indeks.

Wybrana wartość NO_INDEX jest reprezentowana jako pojedynczy bajt w kodowaniu uleb128p1 .

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

definicje flag_dostępu

osadzone w class_def_item, encoded_field, encoded_method i InnerClass

Pola bitowe tych flag są używane do wskazania dostępności i ogólnych właściwości klas i członków klasy.

* Dozwolone tylko dla adnotacji InnerClass i nie może nigdy być włączone w class_def_item .

Kodowanie MUTF-8 (zmodyfikowane UTF-8)

W ramach ustępstwa na rzecz łatwiejszej obsługi starszych wersji, format .dex koduje swoje dane ciągu w de facto standardowym zmodyfikowanym formacie UTF-8, zwanym dalej MUTF-8. Ten formularz jest identyczny ze standardowym UTF-8, z wyjątkiem:

• Używane są tylko kodowania jedno-, dwu- i trzybajtowe.
• Punkty kodowe z zakresu U+10000 … U+10ffff są zakodowane jako para zastępcza, z których każda jest reprezentowana jako trzybajtowa zakodowana wartość.
• Punkt kodowy U+0000 jest zakodowany w postaci dwubajtowej.
• Zwykły bajt null (wartość 0 ) wskazuje koniec ciągu, podobnie jak standardowa interpretacja języka C.

Pierwsze dwa powyższe elementy można podsumować w następujący sposób: MUTF-8 to format kodowania dla UTF-16, zamiast być bardziej bezpośrednim formatem kodowania znaków Unicode.

Ostatnie dwa powyższe elementy umożliwiają jednoczesne uwzględnienie punktu kodowego U+0000 w ciągu i manipulowanie nim jako ciągiem zakończonym znakiem NULL w stylu C.

Jednak specjalne kodowanie U+0000 oznacza, że ​​w przeciwieństwie do normalnego UTF-8, wynik wywołania standardowej funkcji C strcmp() na parze ciągów MUTF-8 nie zawsze wskazuje na poprawnie podpisany wynik porównania nierównych ciągów . Kiedy kolejność (nie tylko równość) jest problemem, najprostszym sposobem porównania ciągów MUTF-8 jest zdekodowanie ich znak po znaku i porównanie zdekodowanych wartości. (Możliwe są jednak również bardziej sprytne implementacje.)

Więcej informacji na temat kodowania znaków można znaleźć w dokumencie The Unicode Standard . MUTF-8 jest w rzeczywistości bliższy (stosunkowo mniej znanemu) kodowaniu CESU-8 niż UTF-8 per se.

kodowanie encoded_value

osadzone w annotation_element i encoded_array_item

encoded_value to zakodowany fragment (prawie) dowolnych danych o hierarchicznej strukturze. Kodowanie ma być zarówno zwarte, jak i łatwe do przeanalizowania.

Formaty wartości

encoded_array format

format encoded_adnotation

format elementu adnotacji

Składnia ciągów

W pliku .dex istnieje kilka rodzajów elementów, które ostatecznie odnoszą się do ciągu. Poniższe definicje w stylu BNF wskazują akceptowalną składnię tych ciągów.

Prosta nazwa

SimpleName jest podstawą składni nazw innych rzeczy. Format .dex pozwala na dużą swobodę geograficzną (znacznie większą niż większość popularnych języków źródłowych). W skrócie, prosta nazwa składa się z dowolnego znaku lub cyfry o niskim ASCII, kilku określonych symboli o niskim ASCII i większości punktów kodowych innych niż ASCII, które nie są znakami kontrolnymi, spacją ani znakami specjalnymi. Począwszy od wersji 040 format dodatkowo dopuszcza znaki spacji (kategoria Unicode Zs ). Należy zauważyć, że zastępcze punkty kodowe (w zakresie U+d800 … U+dfff ) nie są uważane za prawidłowe znaki nazwy per se, ale znaki uzupełniające Unicode są prawidłowe (które są reprezentowane przez ostatnią alternatywę reguły dla SimpleNameChar ) i powinny być reprezentowane w pliku jako pary zastępczych punktów kodowych w kodowaniu MUTF-8.

Nazwa członka

używane przez field_id_item i method_id_item

MemberName to nazwa członka klasy, której członkami są pola, metody i klasy wewnętrzne.

Pełna nazwa klasy

FullClassName to w pełni kwalifikowana nazwa klasy, zawierająca opcjonalny specyfikator pakietu, po którym następuje wymagana nazwa.

TypDescriptor

używane przez type_id_item

TypeDescriptor jest reprezentacją dowolnego typu, w tym prymitywów, klas, tablic i void . Zobacz poniżej znaczenie różnych wersji.

ShortyDescriptor

używany przez proto_id_item

ShortyDescriptor jest krótką reprezentacją prototypu metody, w tym typów zwracanych i parametrów, z wyjątkiem tego, że nie ma rozróżnienia między różnymi typami referencyjnymi (klasami lub tablicami). Zamiast tego wszystkie typy odwołań są reprezentowane przez pojedynczy znak 'L' .

TypeDescriptor Semantics

Takie jest znaczenie każdego z wariantów TypeDescriptor .

Przedmioty i powiązane struktury

Ta sekcja zawiera definicje dla każdego elementu najwyższego poziomu, który może pojawić się w pliku .dex .

pozycja_nagłówka

pojawia się w sekcji nagłówka

wyrównanie: 4 bajty

lista_map

pojawia się w sekcji danych

odwołuje się do pozycji header_item

wyrównanie: 4 bajty

To jest lista całej zawartości pliku, w kolejności. Zawiera pewną nadmiarowość w odniesieniu do elementu header_item , ale ma być łatwym do użycia formularzem do iteracji całego pliku. Dany typ musi pojawić sięna mapie co najwyżej raz, ale nie ma ograniczeń co do kolejności, w jakiej mogą pojawić się typy, poza ograniczeniami wynikającymi z reszty formatu (np. sekcja header musi pojawić się jako pierwsza, a następnie string_ids sekcja itp.). Dodatkowo wpisy mapy muszą być uporządkowane według początkowego przesunięcia i nie mogą się nakładać.

format elementu mapy

Kody typu

string_id_item

pojawia się w sekcji string_ids

wyrównanie: 4 bajty

string_data_item

pojawia się w sekcji danych

wyrównanie: brak (wyrównane do bajtów)

type_id_item

pojawia się w sekcji type_ids

wyrównanie: 4 bajty

proto_id_item

pojawia się w sekcji proto_ids

wyrównanie: 4 bajty

field_id_item

pojawia się w sekcji field_ids

wyrównanie: 4 bajty

method_id_item

pojawia się w sekcji identyfikatory metod

wyrównanie: 4 bajty

class_def_item

pojawia się w sekcji class_defs

wyrównanie: 4 bajty

call_site_id_item

pojawia się w sekcji call_site_ids

wyrównanie: 4 bajty

call_site_item

pojawia się w sekcji danych

wyrównanie: brak (wyrównanie do bajtów)

Call_site_item to encoded_array_item, którego elementy odpowiadają argumentom dostarczonym do metody konsolidatora ładowania początkowego. Pierwsze trzy argumenty to:

1. Uchwyt metody reprezentujący metodę konsolidatora ładowania początkowego (VALUE_METHOD_HANDLE).
2. Nazwa metody, którą konsolidator ładowania początkowego powinien rozwiązać (VALUE_STRING).
3. A method type corresponding to the type of the method name to be resolved (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.