Formato executável Dalvik

Este documento descreve o layout e o conteúdo dos arquivos .dex , que são usados ​​para armazenar um conjunto de definições de classe e seus dados adjuntos associados.

Guia de tipos

LEB128

LEB128 (" Little - E ndian B ase 128 ") é uma codificação de comprimento variável para quantidades inteiras arbitrárias com ou sem sinal. O formato foi emprestado da especificação DWARF3 . Em um arquivo .dex , LEB128 só é usado para codificar quantidades de 32 bits.

Cada valor codificado LEB128 consiste em um a cinco bytes, que juntos representam um único valor de 32 bits. Cada byte tem seu bit mais significativo definido, exceto o byte final da sequência, que tem seu bit mais significativo limpo. Os sete bits restantes de cada byte são carga útil, com os sete bits menos significativos da quantidade no primeiro byte, os próximos sete no segundo byte e assim por diante. No caso de um LEB128 assinado ( sleb128 ), o bit de carga útil mais significativo do byte final na sequência é estendido com sinal para produzir o valor final. No caso não assinado ( uleb128 ), quaisquer bits não representados explicitamente são interpretados como 0 .

A variante uleb128p1 é usada para representar um valor assinado, onde a representação é do valor mais um codificado como uleb128 . Isso torna a codificação de -1 (alternativamente considerada como o valor não assinado 0xffffffff ) - mas nenhum outro número negativo - um único byte e é útil exatamente naqueles casos em que o número representado deve ser não negativo ou -1 (ou 0xffffffff ) e onde nenhum outro valor negativo é permitido (ou onde é improvável que grandes valores não assinados sejam necessários).

Aqui estão alguns exemplos dos formatos:

Layout de arquivo

Definições de campo de bits, string e constante

DEX_FILE_MAGIC

Incorporado em header_item

A matriz/string constante DEX_FILE_MAGIC é a lista de bytes que devem aparecer no início de um arquivo .dex para que ele seja reconhecido como tal. O valor contém intencionalmente uma nova linha ( "\n" ou 0x0a ) e um byte nulo ( "\0" ou 0x00 ) para ajudar na detecção de certas formas de corrupção. O valor também codifica um número de versão do formato como três dígitos decimais, que deverá aumentar monotonicamente ao longo do tempo à medida que o formato evolui.

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

Observação: o suporte para a versão 039 do formato foi adicionado na versão Android 9.0, que introduziu dois novos bytecodes, const-method-handle e const-method-type . (Cada um deles está descrito na tabela Resumo do conjunto de bytes .) No Android 10, a versão 039 estende o formato de arquivo DEX para incluir informações ocultas da API que só são aplicáveis ​​a arquivos DEX no caminho da classe de inicialização.

Nota: O suporte para a versão 038 do formato foi adicionado na versão Android 8.0. A versão 038 adicionou novos bytecodes ( invoke-polymorphic e invoke-custom ) e dados para identificadores de métodos.

Observação: o suporte para a versão 037 do formato foi adicionado na versão Android 7.0. Antes da versão 037 a maioria das versões do Android usava a versão 035 do formato. A única diferença entre as versões 035 e 037 é a adição de métodos padrão e o ajuste da invoke .

Nota: Pelo menos algumas versões anteriores do formato foram usadas em lançamentos de software público amplamente disponíveis. Por exemplo, a versão 009 foi usada para as versões M3 da plataforma Android (novembro a dezembro de 2007) e a versão 013 foi usada para as versões M5 da plataforma Android (fevereiro a março de 2008). Em vários aspectos, estas versões anteriores do formato diferem significativamente da versão descrita neste documento.

ENDIAN_CONSTANT e REVERSE_ENDIAN_CONSTANT

Incorporado em header_item

A constante ENDIAN_CONSTANT é usada para indicar o endianness do arquivo em que se encontra. Embora o formato .dex padrão seja little-endian, as implementações podem optar por realizar a troca de bytes. Se uma implementação encontrar um cabeçalho cujo endian_tag seja REVERSE_ENDIAN_CONSTANT em vez de ENDIAN_CONSTANT , ela saberá que o arquivo foi trocado por bytes do formato esperado.

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

NO_INDEX

Incorporado em class_def_item e debug_info_item

A constante NO_INDEX é usada para indicar que um valor de índice está ausente.

Nota: Este valor não está definido como 0 , porque na verdade esse é normalmente um índice válido.

O valor escolhido para NO_INDEX é representável como um único byte na codificação uleb128p1 .

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

definições de access_flags

Incorporado em class_def_item, encoded_field, encoded_method e InnerClass

Os campos de bits desses sinalizadores são usados ​​para indicar a acessibilidade e as propriedades gerais das classes e dos membros da classe.

* Permitido apenas para anotações InnerClass e nunca deve estar ativado em um class_def_item .

Codificação UTF-8 modificada

Como uma concessão para um suporte legado mais fácil, o formato .dex codifica seus dados de string em um formato UTF-8 modificado padrão de fato, doravante denominado MUTF-8. Este formulário é idêntico ao padrão UTF-8, exceto:

• Somente as codificações de um, dois e três bytes são usadas.
• Os pontos de código no intervalo U+10000 … U+10ffff são codificados como um par substituto, cada um dos quais é representado como um valor codificado de três bytes.
• O ponto de código U+0000 é codificado no formato de dois bytes.
• Um byte nulo simples (valor 0 ) indica o fim de uma string, assim como a interpretação padrão da linguagem C.

Os dois primeiros itens acima podem ser resumidos como: MUTF-8 é um formato de codificação para UTF-16, em vez de ser um formato de codificação mais direto para caracteres Unicode.

Os dois itens finais acima tornam possível incluir simultaneamente o ponto de código U+0000 em uma string e ainda manipulá-lo como uma string terminada em nulo no estilo C.

No entanto, a codificação especial de U+0000 significa que, ao contrário do UTF-8 normal, o resultado da chamada da função C padrão strcmp() em um par de strings MUTF-8 nem sempre indica o resultado devidamente assinado da comparação de strings desiguais . Quando a ordem (não apenas a igualdade) é uma preocupação, a maneira mais direta de comparar strings MUTF-8 é decodificá-las caractere por caractere e comparar os valores decodificados. (No entanto, implementações mais inteligentes também são possíveis.)

Consulte o padrão Unicode para obter mais informações sobre codificação de caracteres. Na verdade, o MUTF-8 está mais próximo da codificação CESU-8 (relativamente menos conhecida) do que do UTF-8 em si.

codificação de valor_codificado

Incorporado em annotation_element e encoded_array_item

Um encoded_value é uma parte codificada de dados (quase) arbitrários estruturados hierarquicamente. A codificação deve ser compacta e fácil de analisar.

Formatos de valor

formato codificado_array

formato de anotação_codificada

formato annotation_element

Sintaxe de string

Existem vários tipos de itens em um arquivo .dex que, em última análise, se referem a uma string. As seguintes definições de estilo BNF indicam a sintaxe aceitável para essas strings.

Nome Simples

Um SimpleName é a base para a sintaxe dos nomes de outras coisas. O formato .dex permite uma boa latitude aqui (muito mais do que a maioria dos idiomas de origem comuns). Resumindo, um nome simples consiste em qualquer caractere ou dígito alfabético de baixo ASCII, alguns símbolos específicos de baixo ASCII e a maioria dos pontos de código não ASCII que não são caracteres de controle, espaço ou especiais. A partir da versão 040 o formato permite adicionalmente caracteres de espaço (categoria Unicode Zs ). Observe que os pontos de código substitutos (no intervalo U+d800 … U+dfff ) não são considerados caracteres de nome válidos, por si só, mas os caracteres suplementares Unicode são válidos (que são representados pela alternativa final da regra para SimpleNameChar ), e eles devem ser representados em um arquivo como pares de pontos de código substitutos na codificação MUTF-8.

Nome do membro

usado por field_id_item e method_id_item

Um MemberName é o nome de um membro de uma classe, sendo os membros campos, métodos e classes internas.

FullClassName

Um FullClassName é um nome de classe totalmente qualificado, incluindo um especificador de pacote opcional seguido por um nome obrigatório.

TipoDescriptor

Usado por type_id_item

Um TypeDescriptor é a representação de qualquer tipo, incluindo primitivos, classes, arrays e void . Veja abaixo o significado das várias versões.

ShortyDescriptor

Usado por proto_id_item

Um ShortyDescriptor é a representação abreviada de um protótipo de método, incluindo tipos de retorno e de parâmetro, exceto que não há distinção entre vários tipos de referência (classe ou array). Em vez disso, todos os tipos de referência são representados por um único caractere 'L' .

Semântica do TypeDescriptor

Este é o significado de cada uma das variantes do TypeDescriptor .

Itens e estruturas relacionadas

Esta seção inclui definições para cada um dos itens de nível superior que podem aparecer em um arquivo .dex .

item_de_cabeçalho

Aparece na seção do cabeçalho

Alinhamento: 4 bytes

lista_de_mapas

Aparece na seção de dados

Referenciado em header_item

Alinhamento: 4 bytes

Esta é uma lista de todo o conteúdo de um arquivo, em ordem. Ele contém alguma redundância em relação ao header_item , mas pretende ser uma forma fácil de usar para iterar um arquivo inteiro. Um determinado tipo deve aparecer no máximo uma vez em um mapa, mas não há nenhuma restrição sobre a ordem em que os tipos podem aparecer, além das restrições implícitas no restante do formato (por exemplo, uma seção header deve aparecer primeiro, seguida por uma string_ids seção, etc.). Além disso, as entradas do mapa devem ser ordenadas por deslocamento inicial e não devem se sobrepor.

formato map_item

Códigos de tipo

string_id_item

Aparece na seção string_ids

Alinhamento: 4 bytes

string_data_item

Aparece na seção de dados

Alinhamento: nenhum (alinhado por byte)

tipo_id_item

Aparece na seção type_ids

Alinhamento: 4 bytes

proto_id_item

Aparece na seção proto_ids

Alinhamento: 4 bytes

campo_id_item

Aparece na seção field_ids

Alinhamento: 4 bytes

método_id_item

Aparece na seção method_ids

Alinhamento: 4 bytes

class_def_item

Aparece na seção class_defs

Alinhamento: 4 bytes

call_site_id_item

Aparece na seção call_site_ids

Alinhamento: 4 bytes

call_site_item

Aparece na seção de dados

Alinhamento: nenhum (alinhado por bytes)

O call_site_item é um encoded_array_item cujos elementos correspondem aos argumentos fornecidos para um método de vinculador de bootstrap. Os três primeiros argumentos são:

1. Um identificador de método que representa o método do vinculador de inicialização (VALUE_METHOD_HANDLE).
2. Um nome de método que o vinculador de bootstrap deve resolver (VALUE_STRING).
3. Um tipo de método correspondente ao tipo do nome do método a ser resolvido (VALUE_METHOD_TYPE).

Quaisquer argumentos adicionais são valores constantes passados ​​para o método do vinculador de bootstrap. Esses argumentos são passados ​​em ordem e sem nenhuma conversão de tipo.

O identificador do método que representa o método do vinculador de bootstrap deve ter o tipo de retorno java.lang.invoke.CallSite . Os primeiros três tipos de parâmetros são:

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

Os tipos de parâmetros de quaisquer argumentos adicionais são determinados a partir dos seus valores constantes.

método_handle_item

Aparece na seção method_handles

Alinhamento: 4 bytes

Códigos de tipo de identificador de método

Class_data_item

Referenciado de classe_def_item

Aparece na seção de dados

Alinhamento: Nenhum (alinhado de byte)

NOTA: As instâncias de todos os elementos ' field_id e method_id devem se referir à mesma classe definidora.

formato coded_field

formato coded_method

type_list

Referenciado de classe_def_item e proto_id_item

Aparece na seção de dados

Alinhamento: 4 bytes

TIPO_Item formato

code_item

Referenciado de coded_method

Aparece na seção de dados

Alinhamento: 4 bytes

formato try_item

formato coded_catch_handler_list

formato coded_catch_handler

formato coded_type_addr_pair

Debug_info_item

Referenciado de code_item

Aparece na seção de dados

Alinhamento: Nenhum (alinhado de byte)

Cada debug_info_item define uma máquina de estado codificada por byte inspirada no DWARF3 que, quando interpretada, emite a tabela de posições e (potencialmente) as informações variáveis ​​locais para um code_item . A sequência começa com um cabeçalho de comprimento variável (cujo comprimento depende do número de parâmetros do método), é seguido pelos bytecodes da máquina de estado e termina com um byte DBG_END_SEQUENCE .

A máquina estadual consiste em cinco registros. O registro address representa o deslocamento da instrução no insns_item associado em unidades de código de 16 bits. O registro de address é iniciado em 0 no início de cada sequência debug_info e deve apenas aumentar monotonicamente. O registro da line representa qual número de linha de origem deve estar associado à próxima entrada da tabela de posições emitida pela máquina de estado. Ele é inicializado no cabeçalho da sequência e pode mudar em direções positivas ou negativas, mas nunca deve ser menor que 1 . O registro source_file representa o arquivo de origem a que as entradas do número da linha se referem. Ele é inicializado com o valor de source_file_idx em class_def_item . As outras duas variáveis, prologue_end e epilogue_begin , são sinalizadores booleanos (inicializados para false ) que indicam se a próxima posição emitida deve ser considerada um prólogo de método ou epilogue. A máquina de estado também deve rastrear o nome e o tipo da última variável local ao vivo em cada registro para o código DBG_RESTART_LOCAL .

O cabeçalho é o seguinte:

Os valores do código de byte são os seguintes:

Códigos de opções especiais

O OPCODES com valores entre 0x0a e 0xff (inclusive) move a line e os registros de address por uma pequena quantidade e, em seguida, emite uma nova entrada de tabela de posição. A fórmula para os incrementos são os seguintes:

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)

Anotações_directory_item

Referenciado de classe_def_item

Aparece na seção de dados

Alinhamento: 4 bytes

NOTA: As instâncias de todos os elementos ' field_id e method_id devem se referir à mesma classe definidora.

formato de field_annotation

Method_annotation Formato

Parameter_annotation Formato

AnoTation_set_ref_list

Referenciado de parameter_annotações_item

Aparece na seção de dados

Alinhamento: 4 bytes

Annotation_set_ref_item formato

AnoTation_set_item

Referenciado de anotações_directory_item, field_annotações_item, métodos_annotações_item e anotação_set_ref_item

Aparece na seção de dados

Alinhamento: 4 bytes

AnoTation_Off_item Formato

anotação_item

Referenciado de anotação_set_item

Aparece na seção de dados

Alinhamento: Nenhum (alinhado de byte)

Valores de visibilidade

Essas são as opções para o campo visibility em um annotation_item :

coded_array_item

Referenciado de classe_def_item

Aparece na seção de dados

Alinhamento: Nenhum (alinhado de byte)

hiddenpi_class_data_item

Esta seção contém dados sobre interfaces restritas usadas por cada classe.

Nota: O recurso de API oculto foi introduzido no Android 10.0 e é aplicável apenas aos arquivos DEX das classes no caminho da classe de inicialização. A lista de sinalizadores descritos abaixo pode ser estendida nos lançamentos futuros do Android. Para obter mais informações, consulte Restrições em interfaces não SDK .

Tipos de bandeira de restrição:

Anotações do sistema

As anotações do sistema são usadas para representar várias informações reflexivas sobre classes (e métodos e campos). Essas informações geralmente são acessadas apenas indiretamente pelo código do cliente (não sistema).

As anotações do sistema são representadas nos arquivos .dex como anotações com visibilidade definida como VISIBILITY_SYSTEM .

dalvik.annotation.annotationDefault

Aparece nos métodos em interfaces de anotação

Uma anotação AnnotationDefault é anexada a cada interface de anotação que deseja indicar ligações padrão.

dalvik.annotation.enclosingClass

Aparece nas aulas

Uma anotação EnclosingClass é anexada a cada classe que é definida como membro de outra classe, por si só, ou é anônima, mas não é definida dentro de um corpo de método (por exemplo, uma classe interna sintética). Todas as aulas que têm essa anotação também devem ter uma anotação InnerClass . Além disso, uma classe não deve ter uma EnclosingClass e uma anotação EnclosingMethod .

dalvik.annotation.enclosingMethod

Aparece nas aulas

Uma anotação EnclosingMethod é anexada a cada classe que é definida dentro de um corpo de método. Todas as aulas que têm essa anotação também devem ter uma anotação InnerClass . Além disso, uma classe não deve ter uma EnclosingClass e uma anotação EnclosingMethod .

dalvik.annotation.innerclass

Aparece nas aulas

Uma anotação InnerClass é anexada a cada classe, definida no escopo lexical da definição de outra classe. Qualquer aula que tenha essa anotação também deve ter uma anotação EnclosingClass ou uma anotação EnclosingMethod .

dalvik.annotation.Memberclasses

Aparece nas aulas

Uma anotação MemberClasses é anexada a cada classe que declara as classes membros. (Uma classe membro é uma classe interna direta que tem um nome.)

dalvik.annotation.methodparameters

Aparece nos métodos

Nota: Esta anotação foi adicionada após o Android 7.1. Sua presença nos lançamentos anteriores do Android será ignorada.

Uma anotação MethodParameters é opcional e pode ser usada para fornecer metadados de parâmetros, como nomes e modificadores de parâmetros.

A anotação pode ser omitida de um método ou construtor com segurança quando os metadados do parâmetro não são necessários em tempo de execução. java.lang.reflect.Parameter.isNamePresent() pode ser usado para verificar se os metadados estão presentes para um parâmetro, e os métodos de reflexão associados como java.lang.reflect.Parameter.getName() voltarão ao comportamento padrão no tempo de execução Se a informação não estiver presente.

Ao incluir metadados de parâmetros, os compiladores devem incluir informações para classes geradas, como enums, pois os metadados do parâmetro incluem se um parâmetro é ou não sintético ou obrigatório.

Uma anotação MethodParameters descreve apenas parâmetros de método individuais. Portanto, os compiladores podem omitir a anotação inteiramente para construtores e métodos que não possuem parâmetros, em prol da eficiência do tamanho do código e do tempo de execução.

As matrizes documentadas abaixo devem ter o mesmo tamanho que a estrutura method_id_item DEX associada ao método, caso contrário, um java.lang.reflect.MalformedParametersException será lançado em tempo de execução.

Ou seja: method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size deve ser o mesmo que names().length e accessFlags().length .

Como MethodParameters descreve todos os parâmetros formais do método, mesmo aqueles não declarados de maneira explícita ou implicitamente no código -fonte, o tamanho das matrizes pode diferir da assinatura ou de outras informações de metadados baseadas apenas em parâmetros explícitos declarados no código -fonte. MethodParameters também não incluirão nenhuma informação sobre os parâmetros do receptor de anotação de tipo que não existem na assinatura do método real.

dalvik.annotation.signature

Aparece em aulas, campos e métodos

Uma anotação Signature é anexada a cada classe, campo ou método definido em termos de um tipo mais complicado do que é representável por um type_id_item . O formato .dex não define o formato para assinaturas; É apenas para poder representar as assinaturas que um idioma de origem exige para a implementação bem -sucedida da semântica desse idioma. Como tal, as assinaturas geralmente não são analisadas (ou verificadas) por implementações de máquinas virtuais. As assinaturas simplesmente são entregues a APIs e ferramentas de nível superior (como depuradores). Qualquer uso de uma assinatura, portanto, deve ser escrito para não fazer suposições sobre o recebimento apenas de assinaturas válidas, protegendo -se explicitamente contra a possibilidade de encontrar uma assinatura sintaticamente inválida.

Como as cordas de assinatura tendem a ter muito conteúdo duplicado, uma anotação Signature é definida como uma variedade de cordas, onde elementos duplicados se referem naturalmente aos mesmos dados subjacentes, e a assinatura é considerada a concatenação de todas as cordas da matriz . Não há regras sobre como separar uma assinatura em cordas separadas; Isso depende inteiramente das ferramentas que geram arquivos .dex .

dalvik.annotation.throws

Aparece nos métodos

A anotação Throws é anexada a cada método que é declarado como lançar um ou mais tipos de exceção.