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.

guía de tipos

LEB128

LEB128 (" L ittle- Endian B ase 128 ") es una codificación de longitud variable para cantidades enteras arbitrarias con o sin signo. El formato fue tomado de la especificación DWARF3 . En un archivo .dex , LEB128 sólo se utiliza 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 su bit más significativo establecido, excepto el byte final de la secuencia, que tiene su bit más significativo limpio. 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 no representado explícitamente se interpreta como 0 .

La variante uleb128p1 se utiliza 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 de 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).

A continuación se muestran 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 deben 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 con tres dígitos decimales, que se espera que aumente monótonamente 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: La compatibilidad con la versión 039 del formato se agregó en la versión Android 9.0, que introdujo dos nuevos códigos de bytes, const-method-handle y const-method-type . (Cada uno de ellos se describe en la tabla Resumen del conjunto de códigos de bytes ). En Android 10, la versión 039 extiende el formato de archivo DEX para incluir información API oculta que solo se aplica a los archivos DEX en la ruta de clase de inicio.

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

Nota: La compatibilidad con la versión 037 del formato se agregó en la versión Android 7.0. Antes de la versión 037 la mayoría de las versiones de Android utilizaban 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 utilizó para las versiones M3 de la plataforma Android (noviembre-diciembre de 2007) y la versión 013 se utilizó 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 endianidad del archivo en el que se encuentra. Aunque el formato .dex estándar es little-endian, las implementaciones pueden optar por realizar el intercambio de bytes. Si una implementación encuentra un encabezado cuyo endian_tag es REVERSE_ENDIAN_CONSTANT en lugar de ENDIAN_CONSTANT , sabrá que el archivo ha sido intercambiado en bytes desde la forma esperada.

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

NO_ÍNDICE

Integrado 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

Incrustado 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 anotaciones InnerClass y nunca debe estar activado en un class_def_item .

Codificación UTF-8 modificada

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:

• Sólo 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 está codificado 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 dos primeros 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 hacen posible incluir simultáneamente el punto de código U+0000 en una cadena y aún manipularlo como una cadena terminada en nulo estilo C.

Sin embargo, la codificación especial de U+0000 significa que, a diferencia del UTF-8 normal, el resultado de llamar a la función estándar de C strcmp() en un par de cadenas MUTF-8 no siempre indica el resultado correctamente 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. En realidad, MUTF-8 está más cerca de la codificación (relativamente menos conocida) CESU-8 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 (casi) arbitrarios estructurados jerárquicamente. La codificación debe ser compacta y sencilla de analizar.

Formatos de valor

formato de matriz_codificada

formato de anotación_codificada

formato elemento_anotación

Sintaxis de cadena

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

Nombre simple

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

Nombre de miembro

utilizado por field_id_item y método_id_item

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

Nombre de clase completo

Un FullClassName es un nombre de clase completo, que incluye un especificador de paquete opcional seguido de un nombre obligatorio.

Descriptor de tipo

Utilizado por type_id_item

Un TypeDescriptor es la representación de cualquier tipo, incluidos primitivos, clases, 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 parámetros, 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 único carácter 'L' .

Semántica de TypeDescriptor

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

Artículos y estructuras relacionadas.

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

elemento_encabezado

Aparece en la sección del encabezado.

Alineación: 4 bytes

lista_mapa

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 ninguna restricción sobre el orden en el que pueden aparecer los tipos, aparte de las restricciones implícitas en el resto del formato (por ejemplo, una sección header debe aparecer primero, seguida de string_ids sección, etcétera). Además, las entradas del mapa deben ordenarse por desplazamiento inicial y no deben superponerse.

formato de elemento de mapa

Códigos de tipo

elemento_id_cadena

Aparece en la sección string_ids

Alineación: 4 bytes

elemento_datos_cadena

Aparece en la sección de datos.

Alineación: ninguna (alineada por bytes)

tipo_id_elemento

Aparece en la sección type_ids

Alineación: 4 bytes

proto_id_item

Aparece en la sección proto_ids

Alineación: 4 bytes

elemento_id_campo

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

elemento_sitio_llamada

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 enlace de arranque. Los primeros tres argumentos son:

1. Un identificador de método que representa el método del vinculador de arranque (VALUE_METHOD_HANDLE).
2. Un nombre de método que el vinculador de arranque debe resolver (VALUE_STRING).
3. Un tipo de método correspondiente al tipo del nombre del método que se va a resolver (VALUE_METHOD_TYPE).

Cualquier argumento adicional son valores constantes pasados ​​al método del vinculador de arranque. Estos argumentos se pasan en orden y sin ninguna conversión de tipo.

El identificador del método que representa el método del vinculador de arranque debe tener un tipo de retorno java.lang.invoke.CallSite . Los primeros tres tipos de parámetros son:

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

Los tipos de parámetros de cualquier argumento adicional se determinan a partir de sus valores constantes.

método_handle_item

Aparece en la sección método_handles

Alineación: 4 bytes

Códigos de tipo de identificador de método

class_data_item

Referenciado desde class_def_item

Aparece en la sección de datos

Alineación: ninguno (byte alineado)

NOTA: Todos los instancias field_id y method_id de los Elementos deben referirse a la misma clase de definición.

formato de code_field

formato de method

type_list

Referenciado desde class_def_item y proto_id_item

Aparece en la sección de datos

Alineación: 4 bytes

formato type_item

Code_Item

Referenciado desde encoded_method

Aparece en la sección de datos

Alineación: 4 bytes

Formato de try_item

Encoded_catch_handler_list format

Formato de encodeD_Catch_Handler

Encoded_type_addr_pair format

debug_info_item

Referenciado desde code_item

Aparece en la sección de datos

Alineación: ninguno (byte alineado)

Cada debug_info_item define una máquina de estado codificada por bytes inspirada en DWARF3 que, cuando se interpreta, emite la tabla de posiciones y (potencialmente) la información variable local para un code_item . La secuencia comienza con un encabezado de longitud variable (la longitud de la cual depende del número de parámetros del método), es seguida por los bytes de la máquina de estado y termina con un byte DBG_END_SEQUENCE .

La máquina de estado consta de cinco registros. El registro address representa el desplazamiento de instrucciones en el insns_item asociado en unidades de código de 16 bits. El registro de address comienza a 0 al comienzo de cada secuencia debug_info y solo debe aumentar monotónicamente. El registro line representa qué número de línea de origen debe estar asociado con la siguiente entrada de tabla de posiciones emitida por la máquina de estado. Se inicializa en el encabezado de secuencia, y puede cambiar en direcciones positivas o negativas, pero nunca debe ser inferior a 1 . El registro source_file representa el archivo de origen al que se refieren las entradas del número de línea. Se inicializa al valor de source_file_idx en class_def_item . Las otras dos variables, prologue_end y epilogue_begin , son banderas booleanas (inicializadas a false ) que indican si la siguiente posición emitida debe considerarse un prólogo o epílogo del método. La máquina de estado también debe rastrear el nombre y el tipo de la última variable local en vivo en cada registro para el código DBG_RESTART_LOCAL .

El encabezado es el siguiente:

Los valores del código de byte son los siguientes:

Códigos de operación especiales

Los códigos de operación con valores entre 0x0a y 0xff (inclusive) mueven los registros de line y address por una pequeña cantidad y luego emiten una nueva entrada de tabla de posición. La fórmula para los incrementos es el siguiente:

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)

anotaciones_directory_item

Referenciado desde class_def_item

Aparece en la sección de datos

Alineación: 4 bytes

NOTA: Todos los instancias field_id y method_id de los Elementos deben referirse a la misma clase de definición.

formato de campo_annotación

Method_annotation Format

Parameter_Annotation Formato

anotación_set_ref_list

Referenciado desde parameter_annotations_item

Aparece en la sección de datos

Alineación: 4 bytes

Annotation_set_ref_item format

anotación_set_item

Referenciado desde annotations_directory_item, field_annotations_item, método_annotations_item y annotation_set_ref_item

Aparece en la sección de datos

Alineación: 4 bytes

Annotation_off_item format

anotación_item

Referenciado de annotation_set_item

Aparece en la sección de datos

Alineación: ninguno (byte alineado)

Valores de visibilidad

Estas son las opciones para el campo visibility en un annotation_item :

encoded_array_item

Referenciado desde class_def_item

Aparece en la sección de datos

Alineación: ninguno (byte alineado)

Hiddenapi_class_data_item

Esta sección contiene datos sobre las interfaces restringidas utilizadas por cada clase.

Nota: La función API oculta se introdujo en Android 10.0 y solo se aplica a los archivos dex de clases Dex en la ruta de clase de arranque. La lista de banderas descritas a continuación puede extenderse en las versiones futuras de Android. Para obtener más información, consulte Restricciones sobre interfaces que no son SDK .

Tipos de bandera de restricción:

Anotaciones del sistema

Las anotaciones del sistema se utilizan para representar varias piezas de información reflexiva sobre clases (y métodos y campos). Esta información generalmente solo se accede indirectamente por el código del cliente (no sistemas).

Las anotaciones del sistema se representan en archivos .dex como anotaciones con visibilidad establecida en VISIBILITY_SYSTEM .

dalvik.annotation.annotationdefault

Aparece en métodos en interfaces de anotación

Se adjunta una anotación AnnotationDefault a cada interfaz de anotación que desea indicar enlaces predeterminados.

dalvik.Annotation.ClosingClass

Aparece en clases

Una anotación EnclosingClass se adjunta a cada clase que se define como un miembro de otra clase, per se, o es anónimo pero no se define dentro de un cuerpo de método (por ejemplo, una clase interna sintética). Cada clase que tiene esta anotación también debe tener una anotación InnerClass . Además, una clase no debe tener una anotación EnclosingClass y una anotación EnclosingMethod .

dalvik.annotation.EntlosingMethod

Aparece en clases

Se une una anotación EnclosingMethod a cada clase que se define dentro de un cuerpo de método. Cada clase que tiene esta anotación también debe tener una anotación InnerClass . Además, una clase no debe tener una anotación EnclosingClass y una anotación EnclosingMethod .

dalvik.annotation.innerClass

Aparece en clases

Se adjunta una anotación InnerClass a cada clase que se define en el alcance léxico de la definición de otra clase. Cualquier clase que tenga esta anotación también debe tener una anotación EnclosingClass o una anotación EnclosingMethod .

dalvik.annotation.memblasses

Aparece en clases

Una anotación MemberClasses se adjunta a cada clase que declara clases de miembros. (Una clase de miembro es una clase interna directa que tiene un nombre).

dalvik.annotation.metodparameters

Aparece en los métodos

Nota: Esta anotación se agregó después de Android 7.1. Su presencia en versiones anteriores de Android será ignorada.

Una anotación MethodParameters es opcional y puede usarse para proporcionar metadatos de parámetros, como nombres de parámetros y modificadores.

La anotación se puede omitir desde un método o constructor de forma segura cuando los metadatos del parámetro no son necesarios en tiempo de ejecución. java.lang.reflect.Parameter.isNamePresent() se puede usar para verificar si los metadatos están presentes para un parámetro, y los métodos de reflexión asociados como java.lang.reflect.Parameter.getName() recurrirán al comportamiento predeterminado en tiempo de ejecución Si la información no está presente.

Al incluir metadatos de parámetros, los compiladores deben incluir información para clases generadas como Enums, ya que los metadatos del parámetro incluyen si un parámetro es sintético o exigido.

Una anotación MethodParameters describe solo parámetros de método individual. Por lo tanto, los compiladores pueden omitir la anotación por completo para constructores y métodos que no tienen parámetros, por el tamaño del tamaño y la eficiencia de tiempo de ejecución.

Las matrices documentadas a continuación deben ser del mismo tamaño que para la estructura method_id_item Dex asociada con el método, de lo contrario, se lanzará un java.lang.reflect.MalformedParametersException en tiempo de ejecución.

Eso es: method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size debe ser lo mismo que names().length y accessFlags().length .

Debido a que MethodParameters describe todos los parámetros del método formal, incluso aquellos que no se declaran explícita o implícitamente en el código fuente, el tamaño de las matrices puede diferir de la firma u otra información de metadatos que se basa solo en los parámetros explícitos declarados en el código fuente. MethodParameters tampoco incluirá ninguna información sobre los parámetros del receptor de anotación de tipo que no existen en la firma del método real.

Dalvik.annotation. Signature

Aparece en clases, campos y métodos

Se adjunta una anotación Signature a cada clase, campo o método que se define en términos de un tipo más complicado que el representable por un type_id_item . El formato .dex no define el formato para firmas; Simplemente está destinado a poder representar cualquier firma que requiera un lenguaje fuente para la implementación exitosa de la semántica de ese lenguaje. Como tal, las firmas generalmente no se analizan (o verifican) mediante implementaciones de máquina virtual. Las firmas simplemente se transmiten a API y herramientas de nivel superior (como debuggers). Cualquier uso de una firma, por lo tanto, debe escribirse para no hacer suposiciones sobre solo recibir firmas válidas, explícitamente protegerse contra la posibilidad de encontrar una firma sintácticamente inválida.

Debido a que las cadenas de firma tienden a tener mucho contenido duplicado, una anotación Signature se define como una variedad de cadenas, donde los elementos duplicados se refieren naturalmente a los mismos datos subyacentes, y la firma se considera la concatenación de todas las cadenas en la matriz . No hay reglas sobre cómo separar una firma en cuerdas separadas; Eso depende completamente de las herramientas que generan archivos .dex .

dalvik.annotation.throws

Aparece en los métodos

Se adjunta una anotación Throws a cada método que se declara para lanzar uno o más tipos de excepción.