Format exécutable Dalvik

Ce document décrit la présentation 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 - E ndian B ase 128 ») est un codage de 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 utilisé que pour coder des quantités de 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 de poids fort activé, à l'exception du dernier octet de la séquence, dont le bit de poids fort est effacé. Les sept bits restants de chaque octet constituent la charge utile, avec les sept bits de poids faible dans le premier octet, les sept bits 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 par signe pour produire la valeur finale. Dans le cas non signé ( uleb128 ), tous les bits non 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 la valeur plus une codée sous la forme uleb128 . Cela rend le codage de -1 (également considéré comme la valeur non signée 0xffffffff ) — mais aucun autre nombre négatif — sur un seul octet, et est utile exactement dans les cas où le nombre représenté doit être soit non négatif, soit -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 :

Disposition des fichiers

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

DEX_FILE_MAGIC

intégré dans header_item

Le tableau/chaîne constante DEX_FILE_MAGIC est la liste d'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 code également un numéro de version de format sous la forme de trois chiffres décimaux, qui devraient 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écapitulatif des jeux de bytecodes .) Dans Android 10, la version 039 étend le format de fichier DEX pour inclure des informations d'API caché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 descripteurs 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 plateforme Android (novembre-décembre 2007) et la version 013 a été utilisée pour les versions M5 de la plateforme 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 permet d'indiquer le boutisme du fichier dans lequel elle se trouve. Bien que le format standard .dex soit petit-boutiste, les implémentations peuvent choisir d'effectuer un échange d'octets. Si une implémentation rencontrait un en-tête dont endian_tag est REVERSE_ENDIAN_CONSTANT au lieu de ENDIAN_CONSTANT , elle saurait que le fichier a été échangé d'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 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 le codage 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 indicateurs sont utilisés pour indiquer l'accessibilité et les propriétés globales des classes et des membres de la classe.

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

Encodage MUTF-8 (UTF-8 modifié)

En guise de concession pour faciliter la prise en charge des anciens formats, le format .dex encode ses données de chaîne sous une forme UTF-8 modifiée standard de facto, ci-après dénommée MUTF-8. Ce formulaire est identique à la norme UTF-8, sauf :

• Seuls les codages à un, deux et trois octets sont utilisés.
• Les points de code compris dans la plage U+10000 … U+10ffff sont codés sous forme de paire de substitution, dont chacun est représenté par une valeur codée sur trois octets.
• Le point de code U+0000 est codé sous forme de deux octets.
• Un simple octet nul (valeur 0 ) indique la fin d'une chaîne, comme c'est le cas pour 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 de codage pour UTF-16, au lieu d'être un format de codage 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 tout en le manipulant comme une chaîne terminée par un caractère C de style C.

Cependant, le codage spécial 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 une préoccupation, le moyen le 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 le codage des caractères. MUTF-8 est en fait plus proche du codage (relativement moins connu) CESU-8 que de l'UTF-8 en soi.

encodage encoded_value

intégré dans annotation_element et encoded_array_item

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

Formats de valeur

format encoded_array

format d'annotation_encodée

format annotation_element

Syntaxe de chaîne

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

NomSimple

Un SimpleName est la base de la syntaxe des noms d’autres choses. Le format .dex permet ici une bonne latitude (beaucoup plus que la plupart des langues sources courantes). En bref, un nom simple se compose de n'importe quel caractère ou chiffre alphabétique faible-ASCII, de quelques symboles spécifiques faible-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. À partir de la version 040 , le format autorise en plus 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 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 doit être représenté 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.

Nom de classe complet

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

TypeDescripteur

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 la signification des différentes versions.

ShortyDescripteur

utilisé par proto_id_item

Un ShortyDescriptor est la représentation abrégée d'un prototype de méthode, comprenant 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 du descripteur de type

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 .

en-tête_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 un formulaire facile à utiliser pour parcourir 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 header doit apparaître en premier, suivie d'un string_ids rubrique, etc.). De plus, les entrées de carte doivent être classées par décalage initial et ne doivent pas se chevaucher.

format élément_carte

Codes de type

string_id_item

apparaît dans la section string_ids

alignement : 4 octets

chaîne_données_élément

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

champ_id_item

apparaît dans la section field_ids

alignement : 4 octets

méthode_id_item

apparaît dans la section method_ids

alignement : 4 octets

classe_def_item

apparaît dans la section class_defs

alignement : 4 octets

appel_site_id_item

apparaît dans la section call_site_ids

alignement : 4 octets

appel_site_item

apparaît dans la section des données

alignement : aucun (octet aligné)

Le call_site_item est un encoded_array_item dont les éléments correspondent aux arguments fournis à une méthode d'é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 bootstrap 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 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 bootstrap doit avoir un 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

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

méthode_handle_item

apparaît dans la section method_handles

alignement : 4 octets

Codes de type de manche de méthode

class_data_item

référencé à partir de class_def_item

apparaît dans la section de données

Alignement: Aucun (aligné par octet)

Remarque: tous les champs de field_id S et method_id doivent se référer à la même classe de définition.

format encodé_field

format encodé_method

type_list

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

apparaît dans la section de données

Alignement: 4 octets

Format de type_item

code_item

référencé à partir de codé_method

apparaît dans la section de données

Alignement: 4 octets

format try_item

Format encodé_catch_handler_list

format encodé_catch_handler

Format encodé_type_addr_pair

debug_info_item

référencé à partir de code_item

apparaît dans la section de données

Alignement: Aucun (aligné par octet)

Chaque debug_info_item définit une machine d'état codée d'octet inspirée de nainf3 qui, une fois interprétée, émet le tableau des positions et (potentiellement) les informations 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 par les bytecodes de la machine d'état, et se termine par un octet DBG_END_SEQUENCE .

La machine d'État se compose de cinq registres. Le registre address représente le décalage d'instructions dans l' insns_item associé dans les 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 monotone. Le registre line représente le numéro de ligne source que la ligne doit être associée à la prochaine entrée de table des positions émise par la machine d'état. Il est initialisé dans l'en-tête de séquence et peut changer dans des directions positives ou négatives 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 se réfèrent. Il est initialisé à la valeur de source_file_idx dans class_def_item . Les deux autres variables, prologue_end et epilogue_begin , sont des drapeaux booléens (initialisés en false ) qui indiquent si la position suivante é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 de code d'octets sont les suivantes:

Opcodes spéciaux

OPCODES avec des valeurs entre 0x0a et 0xff (inclusives) déplacez les registres de line et address par une petite quantité, puis émettent une nouvelle entrée de table de position. 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é à partir de class_def_item

apparaît dans la section de données

Alignement: 4 octets

Remarque: tous les champs de field_id S et method_id doivent se référer à la même classe de définition.

Format sur le terrain

Format de méthode_annotation

Format de paramètre_annotation

annotation_set_ref_list

référencé à partir de paramètre_annotations_item

apparaît dans la section de données

Alignement: 4 octets

format annotation_set_ref_item

annotation_set_item

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

apparaît dans la section de données

Alignement: 4 octets

format annotation_off_item

annotation_item

référencé à partir d'ANNOTATION_SET_ITEM

apparaît dans la section de données

Alignement: Aucun (aligné par octet)

Valeurs de visibilité

Ce sont les options pour le champ visibility dans un annotation_item :

encodé_array_item

référencé à partir de class_def_item

apparaît dans la section de données

Alignement: Aucun (aligné par octet)

Hiddenapi_class_data_item

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

Remarque: La fonction API cachée a été introduite dans Android 10.0 et ne s'applique qu'aux fichiers DEX des classes dans le chemin de la classe de démarrage. La liste des drapeaux décrits ci-dessous peut être étendue dans les futures versions d'Android. Pour plus d'informations, voir les restrictions sur les interfaces non SDK .

Types de drapeaux de restriction:

Annotations du système

Les annotations du système sont utilisées pour représenter diverses pièces d'informations réfléchissantes sur les classes (et les méthodes et champs). Ces informations sont généralement accessibles indirectement par le code client (non-système).

Les annotations du système sont représentées dans les fichiers .dex sous forme d'annotations avec une visibilité définie sur VISIBILITY_SYSTEM .

dalvik.annotation.annotationdefault

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

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

dalvik.annotation.enclosingclass

apparaît sur les cours

Une annotation EnclosingClass est attachée à chaque classe qui est définie comme un membre d'une autre classe, en soi, soit anonyme mais non définie dans un corps de méthode (par exemple, une classe interne synthétique). Chaque classe qui a cette annotation doit également avoir une annotation InnerClass . De plus, une classe ne doit pas avoir à la fois de EnclosingClass et d'une annotation EnclosingMethod .

dalvik.annotation.enclosingMethod

apparaît sur les cours

Une annotation EnclosingMethod est attachée à chaque classe qui est définie à l'intérieur d'un corps de méthode. Chaque classe qui a cette annotation doit également avoir une annotation InnerClass . De plus, une classe ne doit pas avoir à la fois de EnclosingClass et d'une annotation EnclosingMethod .

dalvik.annotation.innerclass

apparaît sur les cours

Une annotation InnerClass est attachée à chaque classe qui est définie dans la portée lexicale de la définition d'une autre classe. Toute classe qui a cette annotation doit également avoir une annotation EnclosingClass , soit une annotation EnclosingMethod .

dalvik.annotation.member-classes

apparaît sur les cours

Une annotation MemberClasses est attachée à chaque classe qui déclare les classes membres. (Une classe de membres est une classe intérieure directe qui a un nom.)

dalvik.annotation.methodparamètres

apparaît sur les méthodes

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

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

L'annotation peut être omise d'une méthode ou d'un constructeur en toute sécurité lorsque les métadonnées des paramètres ne sont pas requises au moment de l'exécution. java.lang.reflect.Parameter.isNamePresent() peut être utilisé pour vérifier si les 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() se replieront à un comportement par défaut à l'exécution Si les informations ne sont pas présentes.

Lors de l'inclusion des métadonnées des 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 des paramètres incluent si un paramètre est synthétique ou mandaté ou non.

Une annotation MethodParameters ne décrit que les paramètres de méthode individuels. Par conséquent, les compilateurs peuvent omettre entièrement l'annotation pour les constructeurs et les méthodes qui n'ont pas de paramètres, pour le plaisir de la taille du code et de l'efficacité du temps d'exécution.

Les tableaux documentés ci-dessous doivent être de la même taille que pour la structure Dex method_id_item associée à la méthode, sinon un java.lang.reflect.MalformedParametersException sera lancé au moment de l'exécution.

C'est-à-dire: method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size doit être le même que 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 de la signature ou d'autres informations de métadonnées qui sont basées uniquement sur des paramètres explicites déclarés dans le code source. MethodParameters n'incluront pas non plus d'informations sur les paramètres du récepteur d'annotation de type qui n'existent pas dans la signature de la méthode réelle.

Dalvik.annotation.signature

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

Une annotation Signature est attachée à chaque classe, champ ou méthode qui est définie en termes de type plus compliqué que ce qui est représentable par un type_id_item . Le format .dex ne définit pas le format pour les signatures; Il est simplement destiné à être en mesure de représenter les signatures dont une langue source requiert pour une mise en œuvre réussie de la sémantique de cette langue. En tant que tels, les signatures ne sont généralement pas analysées (ou vérifiées) par des implémentations de machines virtuelles. Les signatures sont simplement transmises aux API et 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 concernant uniquement les signatures valides, se gardant explicitement contre la possibilité de rencontrer une signature syntaxiquement non valide.

Parce que les chaînes de signature ont tendance à avoir beaucoup de contenu dupliqué, une annotation Signature est définie comme un tableau de chaînes, où les éléments dupliqués se réfèrent naturellement 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'y a pas de règles sur la façon de séparer une signature en chaînes distinctes; Cela dépend entièrement des outils qui génèrent des fichiers .dex .

dalvik.annotation.throws

apparaît sur les méthodes

Une annotation Throws est attachée à chaque méthode qui est déclarée pour lancer un ou plusieurs types d'exceptions.