Формат исполняемого файла Dalvik

В этом документе описывается структура и содержимое файлов .dex , которые используются для хранения набора определений классов и связанных с ними дополнительных данных.

Руководство по типам

ЛЕБ128

LEB128 ("Little- Endian Base 128 ") представляет собой кодировку переменной длины для произвольных целых чисел со знаком или без знака. Формат был заимствован из спецификации DWARF3 . В файле .dex LEB128 используется только для кодирования 32-битных величин.

Каждое закодированное значение LEB128 состоит из одного-пяти байтов, которые вместе представляют одно 32-битное значение. Для каждого байта установлен самый старший бит, за исключением последнего байта в последовательности, у которого самый старший бит сброшен. Остальные семь бит каждого байта являются полезной нагрузкой, причем семь младших битов количества находятся в первом байте, следующие семь — во втором байте и так далее. В случае LEB128 со знаком ( sleb128 ) старший бит полезной нагрузки последнего байта в последовательности расширяется по знаку для получения окончательного значения. В случае без знака ( uleb128 ) любые биты, не представленные явно, интерпретируются как 0 .

Вариант uleb128p1 используется для представления значения со знаком, где представление представляет собой значение плюс один , закодированный как uleb128 . Это делает кодирование -1 (альтернативно рассматриваемое как значение без знака 0xffffffff ) - но никакое другое отрицательное число - одним байтом, и полезно именно в тех случаях, когда представленное число должно быть либо неотрицательным, либо -1 (или 0xffffffff ), и где не допускаются другие отрицательные значения (или где маловероятно, что большие беззнаковые значения потребуются).

Вот несколько примеров форматов:

Макет файла

Определения битовых полей, строк и констант

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"

Примечание. Поддержка версии 039 формата была добавлена ​​в выпуск Android 9.0, в котором представлены два новых байт-кода: const-method-handle и const-method-type . (Каждый из них описан в сводной таблице набора байт-кодов .) В Android 10 версия 039 расширяет формат файла DEX, чтобы включить скрытую информацию API, которая применима только к файлам DEX в пути класса загрузки.

Примечание. Поддержка версии 038 формата была добавлена ​​в выпуске Android 8.0. В версии 038 добавлены новые байт-коды ( invoke-polymorphic и invoke-custom ) и данные для дескрипторов методов.

Примечание. Поддержка версии 037 формата была добавлена ​​в выпуске Android 7.0. До версии 037 в большинстве версий Android использовалась версия 035 формата. Единственная разница между версиями 035 и 037 заключается в добавлении методов по умолчанию и корректировке invoke .

Примечание. По крайней мере несколько более ранних версий формата использовались в общедоступных общедоступных версиях программного обеспечения. Например, версия 009 использовалась для выпусков M3 платформы Android (ноябрь–декабрь 2007 г.), а версия 013 — для выпусков M5 платформы Android (февраль–март 2008 г.). В некоторых отношениях эти более ранние версии формата значительно отличаются от версии, описанной в этом документе.

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 .

Кодировка MUTF-8 (модифицированная UTF-8)

В качестве уступки упрощению устаревшей поддержки формат .dex кодирует свои строковые данные в де-факто стандартной модифицированной форме UTF-8, далее именуемой MUTF-8. Эта форма идентична стандартной UTF-8, за исключением:

• Используются только одно-, двух- и трехбайтовые кодировки.
• Кодовые точки в диапазоне U+10000 … U+10ffff кодируются как суррогатная пара, каждая из которых представлена ​​как трехбайтовое закодированное значение.
• Кодовая точка U+0000 кодируется в двухбайтовой форме.
• Простой нулевой байт (значение 0 ) указывает на конец строки, как и стандартная интерпретация языка C.

Первые два пункта выше можно резюмировать следующим образом: MUTF-8 — это формат кодирования для UTF-16, а не более прямой формат кодирования для символов Unicode.

Последние два элемента выше позволяют одновременно включать кодовую точку U+0000 в строку и по-прежнему манипулировать ею как строкой с нулевым символом в конце в стиле C.

Однако специальная кодировка U+0000 означает, что, в отличие от обычной UTF-8, результат вызова стандартной функции C strcmp() для пары строк MUTF-8 не всегда указывает правильно подписанный результат сравнения неравных строк. . Когда важен порядок (а не только равенство), самый простой способ сравнить строки MUTF-8 — это декодировать их посимвольно и сравнивать декодированные значения. (Однако возможны и более умные реализации.)

Пожалуйста, обратитесь к стандарту Unicode для получения дополнительной информации о кодировке символов. MUTF-8 на самом деле ближе к (относительно менее известной) кодировке CESU-8 , чем к UTF-8 как таковой.

кодировка encoded_value

встроенный в annotation_element и encoded_array_item

encoded_value — это закодированная часть (почти) произвольных иерархически структурированных данных. Кодировка должна быть компактной и простой для анализа.

Форматы значений

формат кодированного_массива

формат encoded_annotation

формат annotation_element

Синтаксис строки

В файле .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 — это полное имя класса, включая необязательный спецификатор пакета, за которым следует обязательное имя.

Дескриптор типа

используется type_id_item

TypeDescriptor — это представление любого типа, включая примитивы, классы, массивы и void . См. Ниже значение различных версий.

ShortyDescriptor

используется proto_id_item

ShortyDescriptor — это краткое представление прототипа метода, включая типы возвращаемых значений и параметров, за исключением того, что нет различий между различными типами ссылок (класс или массив). Вместо этого все ссылочные типы представлены одним символом 'L' .

Семантика дескриптора типа

В этом смысл каждого из вариантов TypeDescriptor .

Предметы и связанные структуры

Этот раздел включает определения для каждого из элементов верхнего уровня, которые могут отображаться в файле .dex .

заголовок_элемент

появляется в разделе заголовка

выравнивание: 4 байта

map_list

появляется в разделе данных

ссылка из header_item

выравнивание: 4 байта

Это список всего содержимого файла по порядку. Он содержит некоторую избыточность по отношению к header_item , но задуман как простая форма для перебора всего файла. Данный тип должен появляться на карте не более одного раза, но нет никаких ограничений на то, в каком порядке могут появляться типы, кроме ограничений, подразумеваемых остальной частью формата (например, сначала должен появиться раздел header , за которым следует string_ids раздел и др.). Кроме того, записи карты должны быть упорядочены по начальному смещению и не должны перекрываться.

формат элемента карты

Коды типов

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. 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.