Formato ejecutable Dalvik

Este documento describe el diseño y el contenido de los archivos .dex , que se utilizan para contener un conjunto de definiciones de clases y sus datos adjuntos asociados.

guia de tipos

LEB128

LEB128 ("Little- Endian Base 128 ") es una codificación de longitud variable para cantidades enteras arbitrarias con signo o sin signo. El formato se tomó prestado de la especificación DWARF3 . En un archivo .dex , LEB128 solo se usa para codificar cantidades de 32 bits.

Cada valor codificado LEB128 consta de uno a cinco bytes, que juntos representan un único valor de 32 bits. Cada byte tiene establecido su bit más significativo, excepto el byte final de la secuencia, que tiene su bit más significativo borrado. Los siete bits restantes de cada byte son carga útil, con los siete bits menos significativos de la cantidad en el primer byte, los siete siguientes en el segundo byte y así sucesivamente. En el caso de un LEB128 con signo ( sleb128 ), el bit de carga útil más significativo del byte final de la secuencia se extiende con signo para producir el valor final. En el caso sin signo ( uleb128 ), cualquier bit que no esté explícitamente representado se interpreta como 0 .

La variante uleb128p1 se usa para representar un valor con signo, donde la representación es del valor más uno codificado como uleb128 . Esto hace que la codificación de -1 (alternativamente considerado como el valor sin signo 0xffffffff ), pero ningún otro número negativo, sea un solo byte, y es útil exactamente en aquellos casos en los que el número representado debe ser no negativo o -1 (o 0xffffffff ), y donde no se permiten otros valores negativos (o donde es poco probable que se necesiten valores grandes sin signo).

Estos son algunos ejemplos de los formatos:

diseño de archivo

Definiciones de campos de bits, cadenas y constantes

DEX_FILE_MAGIC

incrustado en header_item

La matriz/cadena constante DEX_FILE_MAGIC es la lista de bytes que debe aparecer al principio de un archivo .dex para que sea reconocido como tal. El valor contiene intencionalmente una nueva línea ( "\n" o 0x0a ) y un byte nulo ( "\0" o 0x00 ) para ayudar en la detección de ciertas formas de corrupción. El valor también codifica un número de versión de formato como tres dígitos decimales, que se espera que aumente de forma monótona con el tiempo a medida que evoluciona el formato.

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

Nota: Se agregó soporte para la versión 039 del formato en la versión de Android 9.0, que introdujo dos códigos de bytes nuevos, const-method-handle y const-method-type . (Cada uno de estos se describe en la tabla Resumen del conjunto de códigos de bytes ). En Android 10, la versión 039 amplía el formato de archivo DEX para incluir información de API oculta que solo se aplica a los archivos DEX en la ruta de clase de arranque.

Nota: Se agregó soporte para la versión 038 del formato en la versión de Android 8.0. La versión 038 agregó nuevos códigos de bytes ( invoke-polymorphic e invoke-custom ) y datos para identificadores de métodos.

Nota: Se agregó soporte para la versión 037 del formato en la versión de Android 7.0. Antes de la versión 037 , la mayoría de las versiones de Android usaban la versión 035 del formato. La única diferencia entre las versiones 035 y 037 es la adición de métodos predeterminados y el ajuste de la invoke .

Nota: Se han utilizado al menos un par de versiones anteriores del formato en versiones de software públicas ampliamente disponibles. Por ejemplo, la versión 009 se usó para las versiones M3 de la plataforma Android (noviembre-diciembre de 2007) y la versión 013 se usó para las versiones M5 de la plataforma Android (febrero-marzo de 2008). En varios aspectos, estas versiones anteriores del formato difieren significativamente de la versión descrita en este documento.

ENDIAN_CONSTANT y REVERSE_ENDIAN_CONSTANT

incrustado en header_item

La constante ENDIAN_CONSTANT se utiliza para indicar el carácter endian del archivo en el que se encuentra. Aunque el formato .dex estándar es little-endian, las implementaciones pueden optar por realizar un intercambio de bytes. Si una implementación encuentra un encabezado cuya endian_tag es REVERSE_ENDIAN_CONSTANT en lugar de ENDIAN_CONSTANT , sabrá que el archivo se ha intercambiado en bytes de la forma esperada.

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

SIN_ÍNDICE

incrustado en class_def_item y debug_info_item

La constante NO_INDEX se utiliza para indicar que falta un valor de índice.

Nota: este valor no está definido como 0 porque, de hecho, suele ser un índice válido.

El valor elegido para NO_INDEX se puede representar como un solo byte en la codificación uleb128p1 .

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

definiciones de banderas de acceso

integrado en class_def_item, encoded_field, encoded_method e InnerClass

Los campos de bits de estas banderas se utilizan para indicar la accesibilidad y las propiedades generales de las clases y los miembros de la clase.

* Solo se permite para las anotaciones de InnerClass y nunca debe estar activado en un class_def_item .

Codificación MUTF-8 (UTF-8 modificado)

Como concesión a un soporte heredado más sencillo, el formato .dex codifica sus datos de cadena en un formato UTF-8 modificado estándar de facto, en lo sucesivo denominado MUTF-8. Este formulario es idéntico al estándar UTF-8, excepto:

• Solo se utilizan codificaciones de uno, dos y tres bytes.
• Los puntos de código en el rango U+10000 … U+10ffff se codifican como un par sustituto, cada uno de los cuales se representa como un valor codificado de tres bytes.
• El punto de código U+0000 se codifica en formato de dos bytes.
• Un byte nulo simple (valor 0 ) indica el final de una cadena, como es la interpretación estándar del lenguaje C.

Los primeros dos elementos anteriores se pueden resumir como: MUTF-8 es un formato de codificación para UTF-16, en lugar de ser un formato de codificación más directo para caracteres Unicode.

Los dos últimos elementos anteriores permiten incluir simultáneamente el punto de código U+0000 en una cadena y seguir manipulándolo como una cadena terminada en cero de estilo C.

Sin embargo, la codificación especial de U+0000 significa que, a diferencia de UTF-8 normal, el resultado de llamar a la función C estándar strcmp() en un par de cadenas MUTF-8 no siempre indica el resultado debidamente firmado de la comparación de cadenas desiguales . . Cuando el orden (no solo la igualdad) es una preocupación, la forma más sencilla de comparar cadenas MUTF-8 es decodificarlas carácter por carácter y comparar los valores decodificados. (Sin embargo, también son posibles implementaciones más inteligentes).

Consulte el estándar Unicode para obtener más información sobre la codificación de caracteres. MUTF-8 en realidad está más cerca de la codificación CESU-8 (relativamente menos conocida) que de UTF-8 per se.

codificación de valor_codificado

incrustado en annotation_element y encoded_array_item

Un encoded_value es una pieza codificada de datos estructurados jerárquicamente (casi) arbitrarios. La codificación está destinada a ser compacta y sencilla de analizar.

Formatos de valor

formato de matriz codificada

formato de anotación codificada

formato de elemento de anotación

sintaxis de cadena

Hay varios tipos de elementos en un archivo .dex que, en última instancia, se refieren a una cadena. Las siguientes definiciones de estilo BNF indican la sintaxis aceptable para estas cadenas.

NombreSimple

Un SimpleName es la base para la sintaxis de los nombres de otras cosas. El formato .dex permite una buena cantidad de libertad aquí (mucho más que los idiomas de origen más comunes). En resumen, un nombre simple consiste en cualquier dígito o carácter alfabético ASCII bajo, algunos símbolos ASCII bajos específicos y la mayoría de los puntos de código que no son ASCII que no son caracteres de control, espacios o especiales. A partir de la versión 040 , el formato también permite caracteres de espacio (categoría Unicode Zs ). Tenga en cuenta que los puntos de código sustitutos (en el rango U+d800 … U+dfff ) no se consideran caracteres de nombre válidos per se, pero los caracteres suplementarios de Unicode son válidos (que están representados por la alternativa final de la regla para SimpleNameChar ), y debe representarse en un archivo como pares de puntos de código sustitutos en la codificación MUTF-8.

Nombre de miembro

utilizado por field_id_item y method_id_item

Un MemberName es el nombre de un miembro de una clase, siendo los miembros campos, métodos y clases internas.

FullClassName

Un FullClassName es un nombre de clase completamente calificado, que incluye un especificador de paquete opcional seguido de un nombre requerido.

TipoDescriptor

utilizado por type_id_item

Un TypeDescriptor es la representación de cualquier tipo, incluidas las primitivas, las clases, las matrices y void . Consulte a continuación el significado de las distintas versiones.

ShortyDescriptor

utilizado por proto_id_item

Un ShortyDescriptor es la representación abreviada de un prototipo de método, incluidos los tipos de retorno y de parámetro, excepto que no hay distinción entre varios tipos de referencia (clase o matriz). En cambio, todos los tipos de referencia están representados por un solo carácter 'L' .

Semántica del descriptor de tipo

Este es el significado de cada una de las variantes de TypeDescriptor .

Elementos y estructuras relacionadas

Esta sección incluye definiciones para cada uno de los elementos de nivel superior que pueden aparecer en un archivo .dex .

encabezado_elemento

aparece en la sección de encabezado

alineación: 4 bytes

map_list

aparece en la sección de datos

referenciado desde header_item

alineación: 4 bytes

Esta es una lista de todo el contenido de un archivo, en orden. Contiene cierta redundancia con respecto a header_item pero pretende ser una forma fácil de usar para iterar sobre un archivo completo. Un tipo determinado debe aparecer como máximo una vez en un mapa, pero no hay restricciones sobre el orden en que pueden aparecer los tipos, además de las restricciones implícitas en el resto del formato (por ejemplo, una sección de header debe aparecer primero, seguida de string_ids sección, etc). Además, las entradas del mapa deben ordenarse por desplazamiento inicial y no deben superponerse.

formato map_item

Códigos de tipo

cadena_id_elemento

aparece en la sección string_ids

alineación: 4 bytes

cadena_datos_elemento

aparece en la sección de datos

alineación: ninguno (alineado por bytes)

tipo_id_elemento

aparece en la sección type_ids

alineación: 4 bytes

proto_id_elemento

aparece en la sección proto_ids

alineación: 4 bytes

campo_id_elemento

aparece en la sección field_ids

alineación: 4 bytes

método_id_elemento

aparece en la sección method_ids

alineación: 4 bytes

class_def_item

aparece en la sección class_defs

alineación: 4 bytes

call_site_id_item

aparece en la sección call_site_ids

alineación: 4 bytes

llamar_sitio_elemento

aparece en la sección de datos

alineación: ninguna (byte alineado)

call_site_item es un encoded_array_item cuyos elementos corresponden a los argumentos proporcionados a un método de vinculación de arranque. Los tres primeros argumentos son:

1. Un identificador de método que representa el método del enlazador de arranque (VALUE_METHOD_HANDLE).
2. Un nombre de método que debe resolver el enlazador de arranque (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.