Formato eseguibile Dalvik

Questo documento descrive il layout e il contenuto dei file .dex , che vengono utilizzati per contenere una serie di definizioni di classi e i dati aggiuntivi associati.

Guida ai tipi

LEB128

LEB128 ("Little- Endian B ase 128 ") è una codifica a lunghezza variabile per quantità intere arbitrarie con o senza segno. Il formato è stato preso in prestito dalla specifica DWARF3 . In un file .dex , LEB128 viene utilizzato solo per codificare quantità a 32 bit.

Ciascun valore codificato LEB128 è composto da uno a cinque byte, che insieme rappresentano un singolo valore a 32 bit. Ogni byte ha il bit più significativo impostato tranne il byte finale nella sequenza, che ha il bit più significativo libero. I restanti sette bit di ogni byte sono payload, con i sette bit meno significativi della quantità nel primo byte, i successivi sette nel secondo byte e così via. Nel caso di un LEB128 con segno ( sleb128 ), il bit di payload più significativo del byte finale nella sequenza viene esteso con il segno per produrre il valore finale. Nel caso senza segno ( uleb128 ), tutti i bit non rappresentati in modo esplicito vengono interpretati come 0 .

La variante uleb128p1 viene utilizzata per rappresentare un valore con segno, dove la rappresentazione è del valore più uno codificato come uleb128 . Questo rende la codifica di -1 (in alternativa pensato come il valore senza segno 0xffffffff ) - ma nessun altro numero negativo - un singolo byte, ed è utile esattamente in quei casi in cui il numero rappresentato deve essere non negativo o -1 (o 0xffffffff ) e dove non sono consentiti altri valori negativi (o dove è improbabile che siano necessari valori grandi senza segno).

Ecco alcuni esempi di formati:

Disposizione dei file

Definizioni di bitfield, stringhe e costanti

DEX_FILE_MAGIC

incorporato in header_item

L'array/string costante DEX_FILE_MAGIC è l'elenco di byte che devono apparire all'inizio di un file .dex affinché venga riconosciuto come tale. Il valore contiene intenzionalmente una nuova riga ( "\n" o 0x0a ) e un byte null ( "\0" o 0x00 ) per facilitare il rilevamento di determinate forme di corruzione. Il valore codifica anche un numero di versione del formato come tre cifre decimali, che dovrebbe aumentare in modo monotono nel tempo man mano che il formato evolve.

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

Nota: il supporto per la versione 039 del formato è stato aggiunto nella versione Android 9.0, che ha introdotto due nuovi bytecode, const-method-handle e const-method-type . (Tutti questi sono descritti nella tabella Riepilogo del set di bytecode .) In Android 10, la versione 039 estende il formato del file DEX per includere informazioni API nascoste applicabili solo ai file DEX nel percorso della classe di avvio.

Nota: il supporto per la versione 038 del formato è stato aggiunto nella versione Android 8.0. La versione 038 ha aggiunto nuovi bytecode ( invoke-polymorphic e invoke-custom ) e dati per gli handle del metodo.

Nota: il supporto per la versione 037 del formato è stato aggiunto nella versione Android 7.0. Prima della versione 037 la maggior parte delle versioni di Android utilizzava la versione 035 del formato. L'unica differenza tra le versioni 035 e 037 è l'aggiunta di metodi predefiniti e la regolazione invoke .

Nota: almeno un paio di versioni precedenti del formato sono state utilizzate in versioni di software pubblico ampiamente disponibili. Ad esempio, la versione 009 è stata utilizzata per le versioni M3 della piattaforma Android (novembre-dicembre 2007) e la versione 013 è stata utilizzata per le versioni M5 della piattaforma Android (febbraio-marzo 2008). Per diversi aspetti, queste versioni precedenti del formato differiscono in modo significativo dalla versione descritta in questo documento.

ENDIAN_CONSTANT e REVERSE_ENDIAN_CONSTANT

incorporato in header_item

La costante ENDIAN_CONSTANT viene utilizzata per indicare l'endianità del file in cui si trova. Sebbene il formato .dex standard sia little-endian, le implementazioni possono scegliere di eseguire lo scambio di byte. Se un'implementazione incontra un'intestazione il cui endian_tag è REVERSE_ENDIAN_CONSTANT invece di ENDIAN_CONSTANT , saprebbe che il file è stato scambiato di byte dal modulo previsto.

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

NO_INDICE

incorporato in class_def_item e debug_info_item

La costante NO_INDEX viene utilizzata per indicare che un valore di indice è assente.

Nota: questo valore non è definito come 0 , perché in realtà è in genere un indice valido.

Il valore scelto per NO_INDEX è rappresentabile come un singolo byte nella codifica uleb128p1 .

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

definizioni di access_flags

incorporato in class_def_item, encoded_field, encoded_method e InnerClass

I campi di bit di questi flag vengono utilizzati per indicare l'accessibilità e le proprietà generali delle classi e dei membri della classe.

* Consentito solo per le annotazioni InnerClass e non deve mai essere attivo in un class_def_item .

Codifica MUTF-8 (UTF-8 modificato).

Come concessione a un supporto legacy più semplice, il formato .dex codifica i suoi dati di stringa in un formato UTF-8 modificato standard de facto, di seguito denominato MUTF-8. Questo modulo è identico allo standard UTF-8, tranne:

• Vengono utilizzate solo le codifiche a uno, due e tre byte.
• I punti di codice nell'intervallo U+10000 … U+10ffff sono codificati come una coppia surrogata, ciascuno dei quali è rappresentato come un valore codificato a tre byte.
• Il punto di codice U+0000 è codificato in formato a due byte.
• Un byte null semplice (valore 0 ) indica la fine di una stringa, così come l'interpretazione del linguaggio C standard.

I primi due elementi sopra possono essere riassunti come: MUTF-8 è un formato di codifica per UTF-16, invece di essere un formato di codifica più diretto per i caratteri Unicode.

Gli ultimi due elementi sopra consentono di includere contemporaneamente il punto di codice U+0000 in una stringa e di manipolarlo ancora come una stringa con terminazione nulla in stile C.

Tuttavia, la codifica speciale di U+0000 significa che, a differenza del normale UTF-8, il risultato della chiamata della funzione C standard strcmp() su una coppia di stringhe MUTF-8 non indica sempre il risultato del confronto di stringhe disuguali con segno corretto . Quando l'ordine (non solo l'uguaglianza) è un problema, il modo più semplice per confrontare le stringhe MUTF-8 è decodificarle carattere per carattere e confrontare i valori decodificati. (Tuttavia, sono possibili anche implementazioni più intelligenti.)

Fare riferimento a The Unicode Standard per ulteriori informazioni sulla codifica dei caratteri. MUTF-8 è in realtà più vicino alla codifica (relativamente meno nota) CESU-8 che a UTF-8 di per sé.

codifica valore_codificato

incorporato in annotation_element e encoded_array_item

Un encoded_value è un pezzo codificato di dati strutturati gerarchicamente (quasi) arbitrari. La codifica è pensata per essere compatta e semplice da analizzare.

Formati di valore

formato array_codificato

formato annotazione_codificata

formato annotation_element

Sintassi delle stringhe

Esistono diversi tipi di elementi in un file .dex che alla fine si riferiscono a una stringa. Le seguenti definizioni in stile BNF indicano la sintassi accettabile per queste stringhe.

SimpleName

Un SimpleName è la base per la sintassi dei nomi di altre cose. Il formato .dex consente qui una discreta latitudine (molto più delle lingue di origine più comuni). In breve, un nome semplice è costituito da qualsiasi carattere o cifra alfabetica con ASCII basso, alcuni simboli specifici con ASCII basso e la maggior parte dei punti di codice non ASCII che non sono caratteri di controllo, spazi o speciali. A partire dalla versione 040 il formato consente inoltre i caratteri spazio (categoria Unicode Zs ). Si noti che i punti di codice surrogati (nell'intervallo U+d800 … U+dfff ) non sono considerati caratteri di nome validi, di per sé, ma sono validi i caratteri supplementari Unicode (che sono rappresentati dall'alternativa finale della regola per SimpleNameChar ), e dovrebbe essere rappresentato in un file come coppie di punti di codice surrogati nella codifica MUTF-8.

Nome del membro

utilizzato da field_id_item e method_id_item

Un MemberName è il nome di un membro di una classe, i membri sono campi, metodi e classi interne.

Nomeclasse completo

Un FullClassName è un nome di classe completo, incluso un identificatore di pacchetto facoltativo seguito da un nome obbligatorio.

TypeDescriptor

utilizzato da type_id_item

Un TypeDescriptor è la rappresentazione di qualsiasi tipo, incluse primitive, classi, matrici e void . Vedi sotto per il significato delle varie versioni.

ShortyDescriptor

utilizzato da proto_id_item

Uno ShortyDescriptor è la rappresentazione in forma abbreviata di un prototipo di metodo, inclusi i tipi di ritorno e di parametro, tranne per il fatto che non c'è distinzione tra vari tipi di riferimento (classe o array). Tutti i tipi di riferimento sono invece rappresentati da un singolo carattere 'L' .

TypeDescriptor Semantica

Questo è il significato di ciascuna delle varianti di TypeDescriptor .

Articoli e relative strutture

Questa sezione include le definizioni per ciascuno degli elementi di primo livello che possono apparire in un file .dex .

header_item

appare nella sezione dell'intestazione

allineamento: 4 byte

lista_mappa

appare nella sezione dati

referenziato da header_item

allineamento: 4 byte

Questo è un elenco dell'intero contenuto di un file, in ordine. Contiene una certa ridondanza rispetto a header_item ma è inteso come un modulo facile da usare per scorrere un intero file. Un determinato tipo deve apparire al massimo una volta in una mappa, ma non ci sono restrizioni su quali tipi di ordine possono apparire, a parte le restrizioni implicite nel resto del formato (ad esempio, una sezione di header deve apparire prima, seguita da string_ids sezione, ecc.). Inoltre, le voci della mappa devono essere ordinate per offset iniziale e non devono sovrapporsi.

formato map_item

Codici di tipo

elemento_id_stringa

appare nella sezione string_ids

allineamento: 4 byte

elemento_dati_stringa

appare nella sezione dati

allineamento: nessuno (allineato ai byte)

type_id_item

appare nella sezione type_ids

allineamento: 4 byte

proto_id_item

appare nella sezione proto_ids

allineamento: 4 byte

elemento_id_campo

appare nella sezione field_ids

allineamento: 4 byte

elemento_id_metodo

appare nella sezione method_ids

allineamento: 4 byte

class_def_item

appare nella sezione class_defs

allineamento: 4 byte

call_site_id_item

appare nella sezione call_site_ids

allineamento: 4 byte

call_site_item

appare nella sezione dati

allineamento: nessuno (byte allineato)

Il call_site_item è un encoded_array_item i cui elementi corrispondono agli argomenti forniti a un metodo del linker bootstrap. I primi tre argomenti sono:

1. Un handle di metodo che rappresenta il metodo del linker bootstrap (VALUE_METHOD_HANDLE).
2. Un nome di metodo che il linker bootstrap dovrebbe risolvere (VALUE_STRING).
3. A method type corresponding to the type of the method name to be resolved (VALUE_METHOD_TYPE).

Any additional arguments are constant values passed to the bootstrap linker method. These arguments are passed in order and without any type conversions.

The method handle representing the bootstrap linker method must have return type java.lang.invoke.CallSite . The first three parameter types are:

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

The parameter types of any additional arguments are determined from their constant values.

method_handle_item

appears in the method_handles section

alignment: 4 bytes

Method Handle Type Codes

class_data_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

Note: All elements' field_id s and method_id s must refer to the same defining class.

encoded_field format

encoded_method format

type_list

referenced from class_def_item and proto_id_item

appears in the data section

alignment: 4 bytes

type_item format

code_item

referenced from encoded_method

appears in the data section

alignment: 4 bytes

try_item format

encoded_catch_handler_list format

encoded_catch_handler format

encoded_type_addr_pair format

debug_info_item

referenced from code_item

appears in the data section

alignment: none (byte-aligned)

Each debug_info_item defines a DWARF3-inspired byte-coded state machine that, when interpreted, emits the positions table and (potentially) the local variable information for a code_item . The sequence begins with a variable-length header (the length of which depends on the number of method parameters), is followed by the state machine bytecodes, and ends with an DBG_END_SEQUENCE byte.

The state machine consists of five registers. The address register represents the instruction offset in the associated insns_item in 16-bit code units. The address register starts at 0 at the beginning of each debug_info sequence and must only monotonically increase. The line register represents what source line number should be associated with the next positions table entry emitted by the state machine. It is initialized in the sequence header, and may change in positive or negative directions but must never be less than 1 . The source_file register represents the source file that the line number entries refer to. It is initialized to the value of source_file_idx in class_def_item . The other two variables, prologue_end and epilogue_begin , are boolean flags (initialized to false ) that indicate whether the next position emitted should be considered a method prologue or epilogue. The state machine must also track the name and type of the last local variable live in each register for the DBG_RESTART_LOCAL code.

The header is as follows:

The byte code values are as follows:

Special opcodes

Opcodes with values between 0x0a and 0xff (inclusive) move both the line and address registers by a small amount and then emit a new position table entry. The formula for the increments are as follows:

DBG_FIRST_SPECIAL = 0x0a  // the smallest special opcode
DBG_LINE_BASE   = -4      // the smallest line number increment
DBG_LINE_RANGE  = 15      // the number of line increments represented

adjusted_opcode = opcode - DBG_FIRST_SPECIAL

line += DBG_LINE_BASE + (adjusted_opcode % DBG_LINE_RANGE)
address += (adjusted_opcode / DBG_LINE_RANGE)

annotations_directory_item

referenced from class_def_item

appears in the data section

alignment: 4 bytes

Note: All elements' field_id s and method_id s must refer to the same defining class.

field_annotation format

method_annotation format

parameter_annotation format

annotation_set_ref_list

referenced from parameter_annotations_item

appears in the data section

alignment: 4 bytes

annotation_set_ref_item format

annotation_set_item

referenced from annotations_directory_item, field_annotations_item, method_annotations_item, and annotation_set_ref_item

appears in the data section

alignment: 4 bytes

annotation_off_item format

annotation_item

referenced from annotation_set_item

appears in the data section

alignment: none (byte-aligned)

Visibility values

These are the options for the visibility field in an annotation_item :

encoded_array_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

hiddenapi_class_data_item

This section contains data on restricted interfaces used by each class.

Note: The hidden API feature was introduced in Android 10.0 and is only applicable to the DEX files of classes in the boot class path. The list of flags described below may be extended in the future releases of Android. For more information, see restrictions on non-SDK interfaces .

Restriction flag types:

System annotations

System annotations are used to represent various pieces of reflective information about classes (and methods and fields). This information is generally only accessed indirectly by client (non-system) code.

System annotations are represented in .dex files as annotations with visibility set to VISIBILITY_SYSTEM .

dalvik.annotation.AnnotationDefault

appears on methods in annotation interfaces

An AnnotationDefault annotation is attached to each annotation interface which wishes to indicate default bindings.

dalvik.annotation.EnclosingClass

appears on classes

An EnclosingClass annotation is attached to each class which is either defined as a member of another class, per se, or is anonymous but not defined within a method body (eg, a synthetic inner class). Every class that has this annotation must also have an InnerClass annotation. Additionally, a class must not have both an EnclosingClass and an EnclosingMethod annotation.

dalvik.annotation.EnclosingMethod

appears on classes

An EnclosingMethod annotation is attached to each class which is defined inside a method body. Every class that has this annotation must also have an InnerClass annotation. Additionally, a class must not have both an EnclosingClass and an EnclosingMethod annotation.

dalvik.annotation.InnerClass

appears on classes

An InnerClass annotation is attached to each class which is defined in the lexical scope of another class's definition. Any class which has this annotation must also have either an EnclosingClass annotation or an EnclosingMethod annotation.

dalvik.annotation.MemberClasses

appears on classes

A MemberClasses annotation is attached to each class which declares member classes. (A member class is a direct inner class that has a name.)

dalvik.annotation.MethodParameters

appears on methods

Note: This annotation was added after Android 7.1. Its presence on earlier Android releases will be ignored.

A MethodParameters annotation is optional and can be used to provide parameter metadata such as parameter names and modifiers.

The annotation can be omitted from a method or constructor safely when the parameter metadata is not required at runtime. java.lang.reflect.Parameter.isNamePresent() can be used to check whether metadata is present for a parameter, and the associated reflection methods such as java.lang.reflect.Parameter.getName() will fall back to default behavior at runtime if the information is not present.

When including parameter metadata, compilers must include information for generated classes such as enums, since the parameter metadata includes whether or not a parameter is synthetic or mandated.

A MethodParameters annotation describes only individual method parameters. Therefore, compilers may omit the annotation entirely for constructors and methods that have no parameters, for the sake of code-size and runtime efficiency.

The arrays documented below must be the same size as for the method_id_item dex structure associated with the method, otherwise a java.lang.reflect.MalformedParametersException will be thrown at runtime.

That is: method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size must be the same as names().length and accessFlags().length .

Because MethodParameters describes all formal method parameters, even those not explicitly or implicitly declared in source code, the size of the arrays may differ from the Signature or other metadata information that is based only on explicit parameters declared in source code. MethodParameters will also not include any information about type annotation receiver parameters that do not exist in the actual method signature.

dalvik.annotation.Signature

appears on classes, fields, and methods

A Signature annotation is attached to each class, field, or method which is defined in terms of a more complicated type than is representable by a type_id_item . The .dex format does not define the format for signatures; it is merely meant to be able to represent whatever signatures a source language requires for successful implementation of that language's semantics. As such, signatures are not generally parsed (or verified) by virtual machine implementations. The signatures simply get handed off to higher-level APIs and tools (such as debuggers). Any use of a signature, therefore, should be written so as not to make any assumptions about only receiving valid signatures, explicitly guarding itself against the possibility of coming across a syntactically invalid signature.

Because signature strings tend to have a lot of duplicated content, a Signature annotation is defined as an array of strings, where duplicated elements naturally refer to the same underlying data, and the signature is taken to be the concatenation of all the strings in the array. There are no rules about how to pull apart a signature into separate strings; that is entirely up to the tools that generate .dex files.

dalvik.annotation.Throws

appears on methods

A Throws annotation is attached to each method which is declared to throw one or more exception types.