Format exécutable Dalvik

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

Guide des types

LEB128

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

Chaque valeur encodée LEB128 se compose d'un à cinq octets, qui représentent ensemble une seule valeur de 32 bits. Le bit le plus significatif de chaque octet est défini, à l'exception du dernier octet de la séquence, dont le bit le plus significatif est effacé. Les sept bits restants de chaque octet correspondent à 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 étendu 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 fait de l'encodage de -1 (ou de la valeur non signée 0xffffffff) un seul octet, mais pas d'autre nombre négatif. Cette fonctionnalité est utile dans les cas exacts 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ù de grandes valeurs non signées ne sont probablement pas nécessaires).

Voici quelques exemples de formats:

Mise en page du fichier

Format du conteneur

La version 41 introduit un nouveau format de conteneur pour les données DEX dans le but d'économiser de l'espace. Ce format de conteneur permet de combiner plusieurs fichiers DEX logiques en un seul fichier physique. Le nouveau format est essentiellement une concatenaison naïve de fichiers au format précédent, avec quelques différences:

• file_size correspond à la taille du fichier logique, et non du fichier physique. Il peut être utilisé pour itérer sur tous les fichiers logiques du conteneur.
• Les fichiers dex logiques peuvent faire référence à toutes les données ultérieures du conteneur (mais pas à celles antérieures). Cela permet aux fichiers dex de partager des données, telles que des chaînes, entre eux.
• Tous les décalages sont relatifs au fichier physique. Aucun décalage n'est relatif à l'en-tête. Cela garantit que les sections avec des décalages peuvent être partagées entre les fichiers logiques.
• L'en-tête ajoute deux nouveaux champs pour décrire les limites du conteneur. Il s'agit d'une vérification de cohérence supplémentaire qui facilite le portage du code vers le nouveau format.
• Les champs data_size et data_off ne sont plus utilisés. Les données peuvent être réparties sur plusieurs fichiers logiques et ne doivent pas être contiguës.

Définitions de champ de bits, de chaîne et de constante

DEX_FILE_MAGIC

Intégré à header_item

Le tableau/chaîne constant DEX_FILE_MAGIC est la liste d'octets qui doit 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 de faciliter 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 040 du format a été ajoutée dans la version Android 10.0, ce qui a étendu l'ensemble des caractères autorisés dans SimpleNames.

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. (Chacun d'eux est décrit dans le tableau Récapitulatif de l'ensemble de bytecode.) 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 8.0 d'Android. 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 invoke.

Remarque:Au moins deux 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 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é à header_item

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

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

NO_INDEX

Intégrés à class_def_item et debug_info_item

La constante NO_INDEX permet d'indiquer qu'une valeur d'index est absente.

Remarque:Cette valeur n'est pas définie sur 0, car il s'agit généralement d'un indice valide.

La valeur choisie pour NO_INDEX peut être représentée par un seul octet dans l'encodage uleb128p1.

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

Définitions des access_flags

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

Les champs de bits de ces indicateurs 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.

Encodage UTF-8 modifié

Pour faciliter la compatibilité avec les anciennes versions, le format .dex encode ses données de chaîne dans un format UTF-8 modifié standard de facto, ci-après appelé MUTF-8. Ce format est identique à l'UTF-8 standard, à l'exception des points suivants:

• Seuls les encodages à un, deux et trois octets sont utilisés.
• Les points de code compris dans la plage U+10000 à U+10ffff sont encodés en tant que paire de valeurs de substitution, chacune représentée par une valeur encodée sur trois octets.
• Le point de code U+0000 est encodé sous forme de deux octets.
• Une octet nulle simple (valeur 0) indique la fin d'une chaîne, comme c'est l'interprétation standard du langage C.

Les deux premiers éléments ci-dessus peuvent se résumer 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 d'inclure simultanément le point de code U+0000 dans une chaîne et de le manipuler toujours en tant que chaîne terminée par un caractère nul de style C.

Toutefois, l'encodage 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 (et non seulement l'égalité) est un problème, le moyen le plus simple de comparer des chaînes MUTF-8 consiste à les décoder caractère par caractère, puis à comparer les valeurs décodées. (Toutefois, des implémentations plus intelligentes sont également possibles.)

Pour en savoir plus sur l'encodage des caractères, consultez la norme Unicode. MUTF-8 est en fait plus proche de l'encodage CESU-8 (relativement moins connu) que de l'encodage UTF-8 en lui-même.

Encodage de encoded_value

Intégré dans annotation_element et encoded_array_item

Un encoded_value est un élément de données structurées de manière hiérarchique (presque) arbitraire et encodé. L'encodage doit être à la fois compact et simple à analyser.

Formats de valeur

Format encoded_array

Format encoded_annotation

Format annotation_element

Syntaxe des chaînes

Un fichier .dex contient plusieurs types d'éléments qui font finalement référence à une chaîne. Les définitions de style BNF suivantes indiquent la syntaxe acceptable pour ces chaînes.

SimpleName

Un SimpleName est la base de la syntaxe des noms d'autres éléments. Le format .dex offre une certaine marge de manœuvre (beaucoup plus que la plupart des langues sources courantes). En résumé, un nom simple se compose de tout caractère alphabétique ou chiffre ASCII bas de gamme, de quelques symboles ASCII bas de gamme spécifiques 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. À partir de la version 040, le format autorise également les caractères d'espace (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 que les caractères supplémentaires Unicode sont valides (qui sont représentés par l'alternative finale de la règle pour SimpleNameChar), et qu'ils doivent être représentés dans un fichier sous forme de paires de points de code de substitution dans l'encodage MUTF-8.

MemberName

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.

FullClassName

Un FullClassName est un nom de classe complet, y compris 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 primitifs, les classes, les tableaux et void. Vous trouverez ci-dessous la signification des différentes versions.

ShortyDescriptor

Utilisé par proto_id_item

Un ShortyDescriptor est la représentation courte d'un prototype de méthode, y compris les types de retour et de paramètre, à l'exception 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érences sont représentés par un seul caractère 'L'.

Sémantique de TypeDescriptor

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

Éléments et structures associées

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

header_item

S'affiche dans la section d'en-tête

Alignement: 4 octets

map_list

S'affiche dans la section "Données"

Référencé à partir de header_item

Alignement: 4 octets

Il s'agit d'une liste de l'intégralité du contenu d'un fichier, dans l'ordre. Il contient une certaine redondance par rapport à header_item, mais il est conçu pour être un formulaire facile à utiliser pour itérer sur un fichier entier. Un type donné ne doit apparaître qu'une seule fois dans une carte, mais il n'existe aucune restriction sur les types d'ordres pouvant apparaître, à l'exception des restrictions implicites du reste du format (par exemple, une section header doit apparaître en premier, suivie d'une section string_ids, 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 type

string_id_item

Apparaît dans la section "string_ids"

Alignement: 4 octets

string_data_item

S'affiche dans la section "Données"

Alignement: aucun (aligné sur octet)

type_id_item

Apparaît dans la section "type_ids"

Alignement: 4 octets

proto_id_item

S'affiche 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" (ID de méthode)

Alignement: 4 octets

class_def_item

S'affiche dans la section "class_defs"

Alignement: 4 octets

call_site_id_item

S'affiche dans la section "call_site_ids"

Alignement: 4 octets

call_site_item

S'affiche dans la section "Données"

Alignement: aucun (aligné sur octet)

call_site_item est un encoded_array_item dont les éléments correspondent aux arguments fournis à une méthode de linker de démarrage. Les trois premiers arguments sont les suivants:

1. Un handle de méthode représentant la méthode du linker de démarrage (VALUE_METHOD_HANDLE).
2. Nom de méthode que le linker de démarrage doit résoudre (VALUE_STRING).
3. Type de méthode correspondant au type du nom de la méthode à résoudre (VALUE_METHOD_TYPE).

Les arguments supplémentaires sont des valeurs constantes transmises à la méthode du linker de démarrage. Ces arguments sont transmis dans l'ordre et sans conversion de type.

Le gestionnaire de méthode représentant la méthode du linker d'amorçage doit avoir le type de retour java.lang.invoke.CallSite. Les trois premiers types de paramètres sont les suivants:

1. java.lang.invoke.Lookup
2. java.lang.String
3. java.lang.invoke.MethodType

Les types de paramètres de tous les arguments supplémentaires sont déterminés à partir de leurs valeurs constantes.

method_handle_item

S'affiche dans la section "method_handles"

Alignement: 4 octets

Codes de type de poignée de méthode

class_data_item

Référencé à partir de class_def_item

S'affiche dans la section "Données"

Alignement: aucun (aligné sur octet)

Remarque:Toutes les instances field_id et method_id des éléments doivent faire référence à la même classe de définition.

Format de encoded_field

Format encoded_method

type_list

Références de class_def_item et proto_id_item

S'affiche dans la section "Données"

Alignement: 4 octets

Format type_item

code_item

Référencé à partir de encoded_method

S'affiche dans la section "Données"

Alignement: 4 octets

Format try_item

Format encoded_catch_handler_list

Format encoded_catch_handler

Format encoded_type_addr_pair

debug_info_item

Référencé à partir de code_item

S'affiche dans la section "Données"

Alignement: aucun (aligné sur octet)

Chaque debug_info_item définit une machine d'état codée en octets inspirée de DWARF3 qui, lors de l'interprétation, émet la table des positions et (potentiellement) les informations sur les variables locales pour un code_item. La séquence commence par un en-tête à longueur variable (dont la longueur dépend du nombre de paramètres de méthode), est suivie des bytecodes de la machine à états et se termine par un octet DBG_END_SEQUENCE.

Le schéma de machine à états se compose de cinq registres. Le registre address représente le décalage d'instruction dans le insns_item associé en unités de code 16 bits. Le registre address commence à 0 au début de chaque séquence debug_info et ne doit augmenter que de manière monotone. Le registre line représente le numéro de ligne source à associer à la prochaine entrée de table de positions émise par la machine à états. Il est initialisé dans l'en-tête de séquence et peut changer dans le sens positif ou négatif, mais ne doit jamais être inférieur à 1. Le registre source_file représente le fichier source auquel les entrées de numéro de ligne font référence. Il est initialisé sur la valeur de source_file_idx dans class_def_item. Les deux autres variables, prologue_end et epilogue_begin, sont des indicateurs booléens (initialisés sur false) qui indiquent si la prochaine position émise doit être considérée comme un prologue ou un épilogue de méthode. La machine d'état doit également suivre le nom et le type de la dernière variable locale en direct dans chaque registre pour le code DBG_RESTART_LOCAL.

L'en-tête est le suivant:

Les valeurs du code d'octet sont les suivantes:

Opcodes spéciaux

Les opcodes dont la valeur est comprise entre 0x0a et 0xff (inclus) déplacent les registres line et address d'une petite quantité, puis émettent une nouvelle entrée de table de positions. La formule des incréments est la suivante:

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

Référencé à partir de class_def_item

S'affiche dans la section "Données"

Alignement: 4 octets

Remarque:Toutes les instances field_id et method_id des éléments doivent faire référence à la même classe de définition.

Format de field_annotation

Format de method_annotation

Format de l'annotation "parameter"

annotation_set_ref_list

Référence de parameter_annotations_item

S'affiche dans la section "Données"

Alignement: 4 octets

Format annotation_set_ref_item

annotation_set_item

Référencé à partir de annotations_directory_item, field_annotations_item, method_annotations_item et annotation_set_ref_item

S'affiche dans la section "Données"

Alignement: 4 octets

Format annotation_off_item

annotation_item

Référencé à partir de annotation_set_item

S'affiche dans la section "Données"

Alignement: aucun (aligné sur octet)

Valeurs de visibilité

Voici les options pour le champ visibility dans un annotation_item:

encoded_array_item

Référencé à partir de class_def_item

S'affiche dans la section "Données"

Alignement: aucun (aligné sur octet)

hiddenapi_class_data_item

Cette section contient des données sur les interfaces limitées utilisées par chaque classe.

Remarque:La fonctionnalité d'API masquée a été introduite dans Android 10.0 et ne s'applique qu'aux fichiers DEX des classes dans le chemin d'accès des classes de démarrage. La liste des indicateurs décrite ci-dessous peut être étendue dans les prochaines versions d'Android. Pour en savoir plus, consultez les restrictions concernant les interfaces non SDK.

Types d'indicateurs de restriction:

Annotations système

Les annotations système sont utilisées pour représenter différentes informations réfléchissantes sur les classes (et les méthodes et les champs). Ces informations ne sont généralement accessibles qu'indirectement par le code client (non système).

Les annotations système sont représentées dans les fichiers .dex sous forme d'annotations dont la visibilité est définie sur VISIBILITY_SYSTEM.

dalvik.annotation.AnnotationDefault

S'affiche sur les méthodes dans les interfaces d'annotation

Une annotation AnnotationDefault est associée à chaque interface d'annotation qui souhaite indiquer les liaisons par défaut.

dalvik.annotation.EnclosingClass

Figure sur les cours

Une annotation EnclosingClass est associée à chaque classe définie en tant que membre d'une autre classe, en soi, ou anonyme, mais non définie dans le corps d'une méthode (par exemple, une classe interne synthétique). Chaque classe qui comporte cette annotation doit également comporter une annotation InnerClass. De plus, une classe ne doit pas comporter à la fois une annotation EnclosingClass et une annotation EnclosingMethod.

dalvik.annotation.EnclosingMethod

Figure sur les cours

Une annotation EnclosingMethod est associée à chaque classe définie dans le corps d'une méthode. Chaque classe qui comporte cette annotation doit également comporter une annotation InnerClass. De plus, une classe ne doit pas comporter à la fois une annotation EnclosingClass et une annotation EnclosingMethod.

dalvik.annotation.InnerClass

Figure sur les cours

Une annotation InnerClass est associée à chaque classe définie dans le champ lexical de la définition d'une autre classe. Toute classe qui comporte cette annotation doit également comporter soit une annotation EnclosingClass ou une annotation EnclosingMethod.

dalvik.annotation.MemberClasses

Figure sur les cours

Une annotation MemberClasses est associée à chaque classe qui déclare des classes membres. (Une classe membre est une classe interne directe qui possède un nom.)

dalvik.annotation.MethodParameters

S'affiche sur les méthodes

Remarque:Cette annotation a été ajoutée après Android 7.1. Sa présence sur les versions antérieures d'Android sera ignorée.

Une annotation MethodParameters est facultative et peut être utilisée pour fournir des métadonnées de paramètre telles que des noms et des modificateurs de paramètre.

L'annotation peut être omise d'une méthode ou d'un constructeur sans risque lorsque les métadonnées de paramètre ne sont pas requises au moment de l'exécution. java.lang.reflect.Parameter.isNamePresent() permet de vérifier si des métadonnées sont présentes pour un paramètre, et les méthodes de réflexion associées telles que java.lang.reflect.Parameter.getName() reviennent au comportement par défaut au moment de l'exécution si les informations ne sont pas présentes.

Lorsque des métadonnées de paramètres sont incluses, les compilateurs doivent inclure des informations pour les classes générées telles que les énumérations, car les métadonnées de paramètres indiquent si un paramètre est synthétique ou obligatoire.

Une annotation MethodParameters ne décrit que les paramètres de méthode individuels. Par conséquent, les compilateurs peuvent omettre complètement l'annotation pour les constructeurs et les méthodes qui ne comportent aucun paramètre, pour des raisons de taille de code et d'efficacité d'exécution.

Les tableaux documentés ci-dessous doivent avoir la même taille que pour la structure dex method_id_item associée à la méthode, sinon une exception java.lang.reflect.MalformedParametersException sera générée au moment de l'exécution.

Autrement dit, method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size doit être identique à names().length et accessFlags().length.

Étant donné que MethodParameters décrit tous les paramètres de méthode formels, même ceux qui ne sont pas déclarés explicitement ou implicitement dans le code source, la taille des tableaux peut différer de la signature ou d'autres informations de métadonnées basées uniquement sur des paramètres explicites déclarés dans le code source. MethodParameters n'inclura pas non plus d'informations sur les paramètres de récepteur d'annotation de type qui n'existent pas dans la signature de méthode réelle.

dalvik.annotation.Signature

Apparaît sur les classes, les champs et les méthodes

Une annotation Signature est associée à chaque classe, champ ou méthode définie en termes d'un type plus complexe que celui qui peut être représenté par un type_id_item. Le format .dex ne définit pas le format des signatures. Il est simplement destiné à pouvoir représenter toutes les signatures qu'un langage source nécessite pour une implémentation réussie de la sémantique de ce langage. Par conséquent, les signatures ne sont généralement pas analysées (ni vérifiées) par les implémentations de machines virtuelles. Les signatures sont simplement transmises à des API et des outils de niveau supérieur (tels que des débogueurs). Par conséquent, toute utilisation d'une signature doit être écrite de manière à ne pas faire d'hypothèses sur la réception de signatures valides uniquement, et à se protéger explicitement contre la possibilité de rencontrer une signature syntaxiquement non valide.

Étant donné que les chaînes de signature ont tendance à contenir beaucoup de contenu en double, une annotation Signature est définie comme un tableau de chaînes, où les éléments en double font naturellement référence aux mêmes données sous-jacentes, et la signature est considérée comme la concaténation de toutes les chaînes du tableau. Il n'existe aucune règle sur la façon de séparer une signature en chaînes distinctes. Cela dépend entièrement des outils qui génèrent les fichiers .dex.

dalvik.annotation.Throws

S'affiche sur les méthodes

Une annotation Throws est associée à chaque méthode déclarée pour générer un ou plusieurs types d'exceptions.