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 leurs données complémentaires associées.

Guide des types

LEB128

LEB128 ("Little-Endian Base 128") est un encodage de longueur variable pour les quantités entières signées ou non signées 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 de l'octet final de la séquence, dont le bit le plus significatif est effacé. Les sept bits restants de chaque octet sont une 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 du dernier octet de la séquence est étendu au signe pour produire la valeur finale. Dans le cas non signé (uleb128), tous les bits qui ne sont pas explicitement représentés sont interprétés comme 0.

La variante uleb128p1 est utilisée pour représenter une valeur signée, où la représentation est celle de la valeur plus un encodée en tant que uleb128. Cela permet d'encoder -1 (ou la valeur non signée 0xffffffff) sur un seul octet, mais pas les autres nombres négatifs. C'est utile dans les cas où le nombre représenté doit être non négatif ou égal à -1 (ou 0xffffffff), et où aucune autre valeur négative n'est autorisée (ou lorsque de grandes valeurs non signées ne sont pas susceptibles d'être nécessaires).

Voici quelques exemples de formats :

Disposition du fichier

Format du conteneur

La version 41 introduit un nouveau format de conteneur pour les données DEX afin de gagner de l'espace. Ce format de conteneur permet de combiner plusieurs fichiers DEX logiques en un seul fichier physique. Le nouveau format est principalement une simple concaténation des fichiers de l'ancien format, avec quelques différences :

• file_size correspond à la taille du fichier logique, et non du fichier physique. Il peut être utilisé pour parcourir tous les fichiers logiques du conteneur.
• Les fichiers dex logiques peuvent faire référence à des données ultérieures dans le conteneur (mais pas 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 permet de partager des sections avec des décalages entre des fichiers logiques.
• L'en-tête ajoute deux nouveaux champs pour décrire les limites du conteneur. Il s'agit d'un contrôle 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 nécessairement être contiguës.

Définitions de bitfield, de chaîne et de constante

DEX_FILE_MAGIC

Intégré dans header_item

La chaîne/le tableau constant DEX_FILE_MAGIC correspond à la liste des octets qui doivent figurer au début d'un fichier .dex pour qu'il soit reconnu comme tel. La valeur contient intentionnellement un caractère de nouvelle ligne ("\n" ou 0x0a) et un octet nul ("\0" ou 0x00) pour faciliter la détection de certaines formes de corruption. La valeur encode également un numéro de version du 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 041 du format a été ajoutée dans la version 16 d'Android, qui est compatible avec le format de conteneur.

Remarque : La prise en charge de la version 040 du format a été ajoutée dans la version Android 10.0, 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ésumé 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 Android 8.0. La version 038 a ajouté de nouveaux codes d'octet (invoke-polymorphic et invoke-custom) et des données pour les gestionnaires de méthodes.

Remarque : La prise en charge de la version 037 du format a été ajoutée dans la version 7.0 d'Android. 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é dans header_item

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

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

NO_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 sur 0, car il s'agit 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 des indicateurs d'accès

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 générales des classes et des membres de classe.

* Autorisé uniquement pour les annotations InnerClass et jamais pour les class_def_item.

Encodage UTF-8 modifié

Pour faciliter la prise en charge des anciens formats, le format .dex encode ses données de chaîne dans un format UTF-8 modifié, qui est devenu une norme de facto et que nous appellerons MUTF-8. Cette forme est identique à la forme UTF-8 standard, à quelques exceptions près :

• Seuls les encodages sur un, deux et trois octets sont utilisés.
• Les points de code compris dans la plage U+10000 … U+10ffff sont encodés sous forme de paire de substitution, dont chacun est représenté par une valeur encodée sur trois octets.
• Le point de code U+0000 est encodé sur deux octets.
• Un simple octet nul (valeur 0) indique la fin d'une chaîne, conformément à 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 à la fois d'inclure le point de code U+0000 dans une chaîne et de le manipuler comme une chaîne de style C terminée par un caractère nul.

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

Pour en savoir plus sur l'encodage des caractères, veuillez consulter The Unicode Standard. MUTF-8 est en fait plus proche de l'encodage CESU-8 (relativement moins connu) que d'UTF-8 en soi.

Encodage de la valeur encodée

Intégré dans annotation_element et encoded_array_item

Un encoded_value est un élément encodé de données structurées hiérarchiquement (presque) arbitraires. L'encodage est conçu pour être à la fois compact et facile à analyser.

Formats de valeurs

Format encoded_array

Format encoded_annotation

Format de annotation_element

Syntaxe des chaînes

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

SimpleName

Un SimpleName constitue la base de la syntaxe des noms d'autres éléments. Le format .dex offre une grande marge de manœuvre (bien plus que la plupart des langues sources courantes). En bref, un nom simple se compose de n'importe quel caractère alphabétique ou chiffre ASCII en minuscules, de quelques symboles ASCII en minuscules spécifiques et de la plupart des points de code non ASCII qui ne sont pas des caractères de contrôle, des espaces ou des caractères spéciaux. À partir de la version 040, le format autorise également les caractères d'espacement (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 Unicode supplémentaires sont valides (ils sont représentés par l'alternative finale de la règle pour SimpleNameChar) et 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 primitives, 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 abrégée d'un prototype de méthode, y compris les types de retour et de paramètre, à l'exception du fait 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 de TypeDescriptor

Voici 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 premier niveau qui peuvent 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 "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 est conçu pour être un formulaire facile à utiliser pour parcourir un fichier entier. Un type donné ne doit apparaître qu'une seule fois dans une carte, mais il n'y a aucune restriction sur l'ordre dans lequel les types peuvent apparaître, à l'exception des restrictions impliquées par le 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 ordonné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

Apparaît dans la section "Données"

Alignement : aucun (alignement 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 "Données"

Alignement : aucun (alignement sur les octets)

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 les suivants :

1. Handle de méthode représentant la méthode de liaison du bootstrap (VALUE_METHOD_HANDLE).
2. Nom de méthode que le bootstrap linker doit résoudre (VALUE_STRING).
3. 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 de bootstrap. Ces arguments sont transmis 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. Voici les trois premiers types de paramètres :

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

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

method_handle_item

Apparaît dans la section "method_handles"

Alignement : 4 octets

Codes de type de handle de méthode

class_data_item

Référencé depuis class_def_item

Apparaît dans la section "Données"

Alignement : aucun (alignement sur les 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 encoded_field

Format de encoded_method

type_list

Référencé à partir de class_def_item et proto_id_item

Apparaît dans la section "Données"

Alignement : 4 octets

Format type_item

code_item

Référencé à partir de encoded_method

Apparaît dans la section "Données"

Alignement : 4 octets

Format try_item

Format de encoded_catch_handler_list

Format de encoded_catch_handler

Format de encoded_type_addr_pair

debug_info_item

Référencé à partir de code_item

Apparaît dans la section "Données"

Alignement : aucun (alignement sur les octets)

Chaque debug_info_item définit une machine à états codée en octets inspirée de DWARF3 qui, une fois interprétée, é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 de 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.

La 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 qui doit être associé à la prochaine entrée de table des 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 font référence les entrées de numéro de ligne. Elle est initialisée 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 à états 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 de code d'octet sont les suivantes :

Codes d'opération spéciaux

Les codes d'opération dont les valeurs sont comprises entre 0x0a et 0xff (inclus) déplacent légèrement les registres line et address, puis émettent une nouvelle entrée dans la table des positions. La formule pour les 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é depuis class_def_item

Apparaît 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 parameter_annotation

annotation_set_ref_list

Référencé à partir de parameter_annotations_item

Apparaît 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

Apparaît dans la section "Données"

Alignement : 4 octets

Format annotation_off_item

annotation_item

Référencé à partir de annotation_set_item

Apparaît dans la section "Données"

Alignement : aucun (alignement sur les octets)

Valeurs de visibilité

Voici les options du champ visibility dans un annotation_item :

encoded_array_item

Référencé depuis class_def_item

Apparaît dans la section "Données"

Alignement : aucun (alignement sur les octets)

hiddenapi_class_data_item

Cette section contient des données sur les interfaces restreintes 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 de classe de démarrage. La liste des indicateurs décrits ci-dessous pourra être étendue dans les futures versions d'Android. Pour en savoir plus, consultez les restrictions concernant les interfaces non SDK.

Types de signalements de restriction :

Annotations système

Les annotations système sont utilisées pour représenter diverses informations réflexives sur les classes (ainsi que 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 en tant qu'annotations dont la visibilité est définie sur VISIBILITY_SYSTEM.

dalvik.annotation.AnnotationDefault

Apparaît sur les méthodes dans les interfaces d'annotation

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

dalvik.annotation.EnclosingClass

S'affiche dans les cours

Une annotation EnclosingClass est associée à chaque classe qui est définie en tant que membre d'une autre classe, en soi, ou qui est anonyme, mais pas définie dans le corps d'une méthode (par exemple, une classe interne synthétique). Chaque classe comportant 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

S'affiche dans les cours

Une annotation EnclosingMethod est associée à chaque classe définie dans le corps d'une méthode. Chaque classe comportant 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

S'affiche dans les cours

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

dalvik.annotation.MemberClasses

S'affiche dans les cours

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

dalvik.annotation.MethodParameters

Apparaît 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 les noms et les 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() peut être utilisé pour vérifier si des métadonnées sont présentes pour un paramètre. Les méthodes de réflexion associées, telles que java.lang.reflect.Parameter.getName(), reviendront au comportement par défaut au moment de l'exécution si les informations ne sont pas présentes.

Lorsque vous incluez des métadonnées de paramètres, 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 sans paramètre, dans un souci de taille du code et d'efficacité de l'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. Dans le cas contraire, une 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 explicitement ou implicitement déclarés dans le code source, la taille des tableaux peut différer des informations de signature ou d'autres métadonnées qui ne sont basées que sur les 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 de type plus complexe que celui représentable 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 dont une langue source a besoin pour implémenter correctement la sémantique de cette langue. 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 les débogueurs). Par conséquent, toute utilisation d'une signature doit être écrite de manière à ne faire aucune hypothèse sur la réception de signatures valides uniquement, en se protégeant explicitement contre la possibilité de rencontrer une signature syntaxiquement invalide.

É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 concernant la manière 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

Apparaît 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'exception.