Format exécutable Dalvik

Ce document décrit la disposition et le contenu des fichiers .dex , qui sont utilisés pour contenir un ensemble de définitions de classe et leurs données complémentaires associées.

Guide des types

LEB128

LEB128 ("Little- Endian B ase 128 ") est un codage à longueur variable pour des quantités entières arbitraires signées ou non signées. Le format a été emprunté à la spécification DWARF3 . Dans un fichier .dex , LEB128 n'est jamais utilisé que pour encoder des quantités 32 bits.

Chaque valeur codée LEB128 se compose de un à cinq octets, qui représentent ensemble une seule valeur de 32 bits. Chaque octet a son bit le plus significatif défini, à l'exception du dernier octet de la séquence, qui a son bit le plus significatif effacé. Les sept bits restants de chaque octet sont la charge utile, avec les sept bits les moins significatifs de la quantité dans le premier octet, les sept suivants dans le deuxième octet et ainsi de suite. Dans le cas d'un LEB128 signé ( sleb128 ), le bit de charge utile le plus significatif de l'octet final de la séquence est prolongé par un signe pour produire la valeur finale. Dans le cas non signé ( uleb128 ), tous les bits non représentés explicitement sont interprétés comme 0 .

La variante uleb128p1 est utilisée pour représenter une valeur signée, où la représentation est de la valeur plus un encodée en tant que uleb128 . Cela rend le codage de -1 (alternativement considéré comme la valeur non signée 0xffffffff ) - mais aucun autre nombre négatif - un seul octet, et est utile exactement dans les cas où le nombre représenté doit être non négatif ou -1 (ou 0xffffffff ), et où aucune autre valeur négative n'est autorisée (ou où il est peu probable que de grandes valeurs non signées soient nécessaires).

Voici quelques exemples de formats :

Mise en page du fichier

Définitions des champs de bits, des chaînes et des constantes

DEX_FILE_MAGIC

intégré dans header_item

Le tableau/chaîne constant DEX_FILE_MAGIC est la liste des octets qui doivent apparaître au début d'un fichier .dex pour qu'il soit reconnu comme tel. La valeur contient intentionnellement une nouvelle ligne ( "\n" ou 0x0a ) et un octet nul ( "\0" ou 0x00 ) afin d'aider à la détection de certaines formes de corruption. La valeur encode également un numéro de version de format sous la forme de trois chiffres décimaux, qui devrait augmenter de manière monotone au fil du temps à mesure que le format évolue.

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

Remarque : la prise en charge de la version 039 du format a été ajoutée dans la version Android 9.0, qui a introduit deux nouveaux bytecodes, const-method-handle et const-method-type . (Ceux-ci sont chacun décrits dans le tableau Résumé du jeu de bytecodes .) Dans Android 10, la version 039 étend le format de fichier DEX pour inclure des informations d'API masquées qui ne s'appliquent qu'aux fichiers DEX sur le chemin de classe de démarrage.

Remarque : La prise en charge de la version 038 du format a été ajoutée dans la version Android 8.0. La version 038 a ajouté de nouveaux bytecodes ( invoke-polymorphic et invoke-custom ) et des données pour les poignées de méthode.

Remarque : La prise en charge de la version 037 du format a été ajoutée dans la version Android 7.0. Avant la version 037 , la plupart des versions d'Android utilisaient la version 035 du format. La seule différence entre les versions 035 et 037 est l'ajout de méthodes par défaut et l'ajustement de l' invoke .

Remarque : Au moins quelques versions antérieures du format ont été utilisées dans des versions logicielles publiques largement disponibles. Par exemple, la version 009 a été utilisée pour les versions M3 de la plate-forme Android (novembre-décembre 2007) et la version 013 a été utilisée pour les versions M5 de la plate-forme Android (février-mars 2008). À plusieurs égards, ces versions antérieures du format diffèrent considérablement de la version décrite dans ce document.

ENDIAN_CONSTANT et REVERSE_ENDIAN_CONSTANT

intégré dans header_item

La constante ENDIAN_CONSTANT est utilisée pour indiquer l'endianité du fichier dans lequel elle se trouve. Bien que le format .dex standard soit little-endian, les implémentations peuvent choisir d'effectuer un échange d'octets. Si une implémentation rencontre un en-tête dont la endian_tag est REVERSE_ENDIAN_CONSTANT au lieu de ENDIAN_CONSTANT , elle saura que le fichier a été échangé par octet à partir de la forme attendue.

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

AUCUN_INDEX

intégré dans class_def_item et debug_info_item

La constante NO_INDEX est utilisée pour indiquer qu'une valeur d'index est absente.

Remarque : Cette valeur n'est pas définie comme étant 0 , car il s'agit en fait généralement d'un index valide.

La valeur choisie pour NO_INDEX est représentable sous la forme d'un seul octet dans l'encodage uleb128p1 .

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

définitions d'access_flags

intégré dans class_def_item, encoded_field, encoded_method et InnerClass

Les champs de bits de ces drapeaux sont utilisés pour indiquer l'accessibilité et les propriétés globales des classes et des membres de classe.

* Autorisé uniquement pour les annotations InnerClass et ne doit jamais être activé dans un class_def_item .

Codage MUTF-8 (UTF-8 modifié)

En tant que concession à une prise en charge héritée plus facile, le format .dex encode ses données de chaîne sous une forme UTF-8 modifiée standard de facto, ci-après appelée MUTF-8. Cette forme est identique à la norme UTF-8, sauf :

• Seuls les codages à un, deux et trois octets sont utilisés.
• Les points de code dans la plage U+10000 … U+10ffff sont codés comme une paire de substitution, chacun étant représenté par une valeur codée sur trois octets.
• Le point de code U+0000 est codé sous forme de deux octets.
• Un octet nul simple (valeur 0 ) indique la fin d'une chaîne, comme c'est le cas dans l'interprétation standard du langage C.

Les deux premiers éléments ci-dessus peuvent être résumés comme suit : MUTF-8 est un format d'encodage pour UTF-16, au lieu d'être un format d'encodage plus direct pour les caractères Unicode.

Les deux derniers éléments ci-dessus permettent simultanément d'inclure le point de code U+0000 dans une chaîne et de le manipuler comme une chaîne à terminaison nulle de style C.

Cependant, le codage spécial de U+0000 signifie que, contrairement à l'UTF-8 normal, le résultat de l'appel de la fonction C standard strcmp() sur une paire de chaînes MUTF-8 n'indique pas toujours le résultat correctement signé de la comparaison de chaînes inégales . . Lorsque l'ordre (pas seulement l'égalité) est un problème, la façon la plus simple de comparer les chaînes MUTF-8 est de les décoder caractère par caractère et de comparer les valeurs décodées. (Cependant, des implémentations plus intelligentes sont également possibles.)

Veuillez vous référer à la norme Unicode pour plus d'informations sur l'encodage des caractères. MUTF-8 est en fait plus proche de l'encodage (relativement moins connu) CESU-8 que de l'UTF-8 en soi.

encodage encoding_value

intégré dans annotation_element et encoded_array_item

Une encoded_value est un élément codé de données structurées hiérarchiquement (presque) arbitraires. L'encodage est censé être à la fois compact et simple à analyser.

Formats de valeur

format de tableau_encodé

format d'annotation_encodée

format annotation_element

Syntaxe de chaîne

Il existe plusieurs types d'éléments dans un fichier .dex qui se réfèrent finalement à une chaîne. Les définitions de style BNF suivantes indiquent la syntaxe acceptable pour ces chaînes.

Nom_simple

Un SimpleName est la base de la syntaxe des noms d'autres choses. Le format .dex permet ici une bonne latitude (bien plus que la plupart des langues sources courantes). En bref, un nom simple se compose de tout caractère ou chiffre alphabétique bas-ASCII, de quelques symboles spécifiques bas-ASCII et de la plupart des points de code non-ASCII qui ne sont pas des caractères de contrôle, d'espace ou spéciaux. A partir de la version 040 , le format autorise en plus les espaces (catégorie Unicode Zs ). Notez que les points de code de substitution (dans la plage U+d800 … U+dfff ) ne sont pas considérés comme des caractères de nom valides, en soi, mais les caractères supplémentaires Unicode sont valides (qui sont représentés par l'alternative finale de la règle pour SimpleNameChar ), et ils doivent être représentés dans un fichier sous forme de paires de points de code de substitution dans le codage MUTF-8.

Nom de membre

utilisé par field_id_item et method_id_item

Un MemberName est le nom d'un membre d'une classe, les membres étant des champs, des méthodes et des classes internes.

NomClasseComplet

Un FullClassName est un nom de classe complet, comprenant un spécificateur de package facultatif suivi d'un nom obligatoire.

TypeDescriptor

utilisé par type_id_item

Un TypeDescriptor est la représentation de n'importe quel type, y compris les primitives, les classes, les tableaux et void . Voir ci-dessous pour la signification des différentes versions.

ShortyDescriptor

utilisé par proto_id_item

Un ShortyDescriptor est la représentation abrégée d'un prototype de méthode, y compris les types de retour et de paramètre, sauf qu'il n'y a pas de distinction entre les différents types de référence (classe ou tableau). Au lieu de cela, tous les types de référence sont représentés par un seul caractère 'L' .

Sémantique TypeDescriptorTypeDescriptor Semantics

C'est la signification de chacune des variantes de TypeDescriptor .

Articles et structures associées

Cette section comprend des définitions pour chacun des éléments de niveau supérieur pouvant apparaître dans un fichier .dex .

header_item

apparaît dans la section d'en-tête

alignement : 4 octets

map_list

apparaît dans la section des données

référencé depuis header_item

alignement : 4 octets

Il s'agit d'une liste de tout le contenu d'un fichier, dans l'ordre. Il contient une certaine redondance par rapport à header_item mais est destiné à être une forme facile à utiliser pour itérer sur un fichier entier. Un type donné doit apparaître au plus une fois dans une carte, mais il n'y a aucune restriction sur l'ordre dans lequel les types peuvent apparaître, autres que les restrictions impliquées par le reste du format (par exemple, une section d'en- header doit apparaître en premier, suivie d'un string_ids section, etc). De plus, les entrées de la carte doivent être triées par décalage initial et ne doivent pas se chevaucher.

format map_item

Codes de types

string_id_item

apparaît dans la section string_ids

alignement : 4 octets

string_data_item

apparaît dans la section des données

alignement : aucun (aligné sur les octets)

type_id_item

apparaît dans la section type_ids

alignement : 4 octets

proto_id_item

apparaît dans la section proto_ids

alignement : 4 octets

field_id_item

apparaît dans la section field_ids

alignement : 4 octets

method_id_item

apparaît dans la section method_ids

alignement : 4 octets

class_def_item

apparaît dans la section class_defs

alignement : 4 octets

call_site_id_item

apparaît dans la section call_site_ids

alignement : 4 octets

call_site_item

apparaît dans la section des données

alignement : aucun (aligné sur les octets)

Le call_site_item est un encoded_array_item dont les éléments correspondent aux arguments fournis à une méthode de l'éditeur de liens bootstrap. Les trois premiers arguments sont :

1. Un handle de méthode représentant la méthode de l'éditeur de liens bootstrap (VALUE_METHOD_HANDLE).
2. Un nom de méthode que l'éditeur de liens d'amorçage doit résoudre (VALUE_STRING).
3. Un type de méthode correspondant au type du nom de méthode à résoudre (VALUE_METHOD_TYPE).

Tous les arguments supplémentaires sont des valeurs constantes transmises à la méthode de l'éditeur de liens bootstrap. Ces arguments sont passés dans l'ordre et sans aucune conversion de type.

Le handle de méthode représentant la méthode de l'éditeur de liens d'amorçage doit avoir le type de retour java.lang.invoke.CallSite . Les trois premiers types de paramètres sont :

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.