Formato executável Dalvik

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

Guia de tipos

Nome Descrição
byte 8 bits assinado int
ubyte Int não assinado de 8 bits
curto 16 bits assinado int, little-endian
ushor 16 bits unsigned int, little-endian
int 32 bits assinado int, little-endian
uint 32 bits unsigned int, little-endian
grandes 64 bits assinado int, little-endian
longo 64 bits unsigned int, little-endian
sleb128 assinado LEB128, comprimento variável (veja abaixo)
uleb128 LEB128 não assinado, comprimento variável (veja abaixo)
uleb128p1 LEB128 não assinado mais 1 , comprimento variável (veja abaixo)

LEB128

LEB128 ("Little- Endian B ase 128 ") é uma codificação de comprimento variável para quantidades inteiras arbitrárias com sinal ou sem sinal. O formato foi emprestado da especificação DWARF3 . Em um arquivo .dex , o LEB128 é usado apenas 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 conjunto de bits mais significativo, exceto o byte final na 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 para produzir o valor final. No caso sem sinal ( uleb128 ), quaisquer bits não representados explicitamente são interpretados como 0 .

Diagrama bit a bit de um valor LEB128 de dois bytes
Primeiro byte Segundo byte
1 bocado 6 pedaço 5 bocado 4 parte 3 parte 2 pedaço 1 bit 0 0 pedaço 13 bocado 12 pedaço 11 pedaço 10 bocado 9 bocado 8 pedaço 7

A variante uleb128p1 é usada para representar um valor com sinal, onde a representação é do valor mais um codificado como uleb128 . Isso torna a codificação de -1 (alternativa considerada como o valor sem sinal 0xffffffff ) — mas nenhum outro número negativo — um único byte, e é útil exatamente nos 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 sem sinal sejam necessários).

Veja alguns exemplos dos formatos:

Sequência Codificada Como sleb128 Como uleb128 Como uleb128p1
00 0 0 -1
01 1 1 0
7f -1 127 126
80 7f -128 16256 16255

Layout do arquivo

Nome Formato Descrição
cabeçalho cabeçalho_item o cabeçalho
string_ids string_id_item[] lista de identificadores de string. Estes são identificadores para todas as strings usadas por este arquivo, seja para nomeação interna (por exemplo, descritores de tipo) ou como objetos constantes referidos pelo código. Essa lista deve ser classificada por conteúdo de cadeia de caracteres, usando valores de ponto de código UTF-16 (não de maneira sensível à localidade) e não deve conter entradas duplicadas.
type_ids type_id_item[] lista de identificadores de tipo. Estes são identificadores para todos os tipos (classes, arrays ou tipos primitivos) referidos por este arquivo, sejam eles definidos no arquivo ou não. Essa lista deve ser classificada pelo índice string_id e não deve conter entradas duplicadas.
proto_ids proto_id_item[] lista de identificadores de protótipo de método. Estes são identificadores para todos os protótipos referidos por este arquivo. Essa lista deve ser classificada em ordem principal de tipo de retorno (por índice type_id ) e, em seguida, por lista de argumentos (ordenação lexicográfica, argumentos individuais ordenados por índice type_id ). A lista não deve conter entradas duplicadas.
field_ids field_id_item[] lista de identificadores de campo. Estes são identificadores para todos os campos referidos por este arquivo, sejam eles definidos no arquivo ou não. Essa lista deve ser classificada, onde o tipo de definição (por índice type_id ) é a ordem principal, o nome do campo (por índice string_id ) é a ordem intermediária e o tipo (por índice type_id ) é a ordem secundária. A lista não deve conter entradas duplicadas.
method_ids method_id_item[] lista de identificadores de método. Estes são identificadores para todos os métodos referidos por este arquivo, sejam eles definidos no arquivo ou não. Essa lista deve ser classificada, onde o tipo de definição (por índice type_id ) é a ordem principal, o nome do método (por índice string_id ) é a ordem intermediária e o protótipo do método (por índice proto_id ) é a ordem secundária. A lista não deve conter entradas duplicadas.
class_defs class_def_item[] lista de definições de classe. As classes devem ser ordenadas de forma que a superclasse de uma determinada classe e as interfaces implementadas apareçam na lista antes da classe de referência. Além disso, é inválido que uma definição para a classe com o mesmo nome apareça mais de uma vez na lista.
call_site_ids call_site_id_item[] chamar a lista de identificadores de site. Estes são identificadores para todos os sites de chamada referidos por este arquivo, definidos no arquivo ou não. Esta lista deve ser classificada em ordem crescente de call_site_off .
method_handles method_handle_item[] o método manipula a lista. Uma lista de todos os identificadores de método referidos por este arquivo, definidos no arquivo ou não. Esta lista não é classificada e pode conter duplicatas que corresponderão logicamente a diferentes instâncias de manipulação de métodos.
dados ubyte[] área de dados, contendo todos os dados de suporte para as tabelas listadas acima. Itens diferentes têm requisitos de alinhamento diferentes e bytes de preenchimento são inseridos antes de cada item, se necessário, para obter o alinhamento adequado.
link_data ubyte[] dados usados ​​em arquivos vinculados estaticamente. O formato dos dados nesta seção não é especificado por este documento. Esta seção está vazia em arquivos não vinculados e as implementações de tempo de execução podem usá-la como acharem melhor.

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

DEX_FILE_MAGIC

incorporado em header_item

A constante array/string DEX_FILE_MAGIC é a lista de bytes que deve aparecer no início de um arquivo .dex para que 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 de formato como três dígitos decimais, que deve 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"

Nota: 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 é descrito na tabela Resumo do conjunto de bytecodes .) No Android 10, a versão 039 estende o formato de arquivo DEX para incluir informações de API ocultas que são aplicáveis ​​apenas 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étodo.

Nota: 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 do método invoke .

Nota: Pelo menos algumas versões anteriores do formato foram usadas em versões de software públicas 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, essas 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 é utilizada para indicar a endianidade 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 cuja endian_tag seja REVERSE_ENDIAN_CONSTANT em vez de ENDIAN_CONSTANT , ela saberá que o arquivo foi trocado de byte 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.

Observação: esse valor não está definido como 0 , porque, na verdade, geralmente é 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 de classes e membros de classe.

Nome Valor Para classes (e anotações InnerClass ) Para campos Para métodos
ACC_PUBLIC 0x1 public : visível em todos os lugares public : visível em todos os lugares public : visível em todos os lugares
ACC_PRIVATE 0x2 * private : visível apenas para definir a classe private : visível apenas para definir a classe private : visível apenas para definir a classe
ACC_PROTECTED 0x4 * protected : visível para pacote e subclasses protected : visível para pacote e subclasses protected : visível para pacote e subclasses
ACC_STATIC 0x8 * static : não é construído com uma referência externa this static : global para definir a classe static : não aceita this argumento
ACC_FINAL 0x10 final : não subclassificável final : imutável após a construção final : não substituível
ACC_SYNCHRONIZED 0x20 synchronized : bloqueio associado adquirido automaticamente em torno da chamada para este método.

Nota: Isso só é válido para definir quando ACC_NATIVE também estiver definido.

ACC_VOLATILE 0x40 volatile : regras de acesso especiais para ajudar na segurança do encadeamento
ACC_BRIDGE 0x40 método bridge, adicionado automaticamente pelo compilador como uma ponte segura de tipo
ACC_TRANSIENT 0x80 transient : não deve ser salvo por serialização padrão
ACC_VARARGS 0x80 último argumento deve ser tratado como um argumento "rest" pelo compilador
ACC_NATIVE 0x100 native : implementado em código nativo
ACC_INTERFACE 0x200 interface : classe abstrata multiplicável
ACC_ABSTRACT 0x400 abstract : não diretamente instanciável abstract : não implementado por esta classe
ACC_STRICT 0x800 strictfp : regras estritas para aritmética de ponto flutuante
ACC_SYNTHETIC 0x1000 não definido diretamente no código-fonte não definido diretamente no código-fonte não definido diretamente no código-fonte
ACC_ANNOTATION 0x2000 declarado como uma classe de anotação
ACC_ENUM 0x4000 declarado como um tipo enumerado declarado como um valor enumerado
(sem uso) 0x8000
ACC_CONSTRUCTOR 0x10000 método construtor (inicializador de classe ou instância)
ACC_DECLARED_
SINCRONIZADO
0x20000 declarado synchronized .

Nota: Isso não tem efeito na execução (exceto na reflexão deste sinalizador, por si só).

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

Codificação MUTF-8 (UTF-8 Modificado)

Como uma concessão ao suporte legado mais fácil, o formato .dex codifica seus dados de string em um formato UTF-8 modificado pelo padrão de fato, daqui em diante referido como 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+10000U+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 na forma de dois bytes.
  • Um byte nulo simples (valor 0 ) indica o final 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 simultaneamente possível incluir o ponto de código U+0000 em uma string e ainda manipulá-lo como uma string terminada em nulo estilo C.

No entanto, a codificação especial de U+0000 significa que, ao contrário do UTF-8 normal, o resultado de chamar a 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 ordenar (não apenas 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. O MUTF-8 está realmente mais próximo da codificação (relativamente menos conhecida) CESU-8 do que do UTF-8 per se.

codificação de valor_codificado

incorporado em annotation_element e encoded_array_item

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

Nome Formato Descrição
(valor_arg << 5) | tipo_valor ubyte byte indicando o tipo do value imediatamente subsequente junto com um argumento de esclarecimento opcional nos três bits de ordem superior. Veja abaixo as várias definições de value . Na maioria dos casos, value_arg codifica o comprimento do value imediatamente subsequente em bytes, como (size - 1) , por exemplo, 0 significa que o valor requer um byte e 7 significa que requer oito bytes; no entanto, há exceções, conforme indicado abaixo.
valor ubyte[] bytes representando o valor, variável em comprimento e interpretada de forma diferente para diferentes bytes value_type , embora sempre little-endian. Consulte as várias definições de valor abaixo para obter detalhes.

Formatos de valor

Digite o nome value_type value_arg Formato value Formato Descrição
VALUE_BYTE 0x00 (nenhum; deve ser 0 ) ubyte[1] valor inteiro de um byte assinado
VALUE_SHORT 0x02 tamanho - 1 (0…1) ubyte[tamanho] valor inteiro de dois bytes com sinal, estendido por sinal
VALUE_CHAR 0x03 tamanho - 1 (0…1) ubyte[tamanho] valor inteiro de dois bytes sem sinal, estendido em zero
VALUE_INT 0x04 tamanho - 1 (0…3) ubyte[tamanho] valor inteiro de quatro bytes com sinal, estendido por sinal
VALUE_LONG 0x06 tamanho - 1 (0…7) ubyte[tamanho] valor inteiro de oito bytes assinado, estendido por sinal
VALUE_FLOAT 0x10 tamanho - 1 (0…3) ubyte[tamanho] padrão de bits de quatro bytes, estendido em zero à direita e interpretado como um valor de ponto flutuante IEEE754 de 32 bits
VALUE_DOUBLE 0x11 tamanho - 1 (0…7) ubyte[tamanho] padrão de bits de oito bytes, estendido em zero à direita e interpretado como um valor de ponto flutuante IEEE754 de 64 bits
VALUE_METHOD_TYPE 0x15 tamanho - 1 (0…3) ubyte[tamanho] valor inteiro de quatro bytes sem sinal (estendido com zero), interpretado como um índice na seção proto_ids e representando um valor de tipo de método
VALUE_METHOD_HANDLE 0x16 tamanho - 1 (0…3) ubyte[tamanho] valor inteiro de quatro bytes sem sinal (estendido com zero), interpretado como um índice na seção method_handles e representando um valor de identificador de método
VALUE_STRING 0x17 tamanho - 1 (0…3) ubyte[tamanho] valor inteiro de quatro bytes sem sinal (estendido com zero), interpretado como um índice na seção string_ids e representando um valor de string
VALUE_TYPE 0x18 tamanho - 1 (0…3) ubyte[tamanho] valor inteiro de quatro bytes não assinado (zero estendido), interpretado como um índice na seção type_ids e representando um valor de tipo/classe reflexivo
VALUE_FIELD 0x19 tamanho - 1 (0…3) ubyte[tamanho] valor inteiro de quatro bytes não assinado (zero estendido), interpretado como um índice na seção field_ids e representando um valor de campo reflexivo
VALUE_METHOD 0x1a tamanho - 1 (0…3) ubyte[tamanho] valor inteiro de quatro bytes sem sinal (estendido com zero), interpretado como um índice na seção method_ids e representando um valor de método reflexivo
VALUE_ENUM 0x1b tamanho - 1 (0…3) ubyte[tamanho] valor inteiro de quatro bytes não assinado (zero estendido), interpretado como um índice na seção field_ids e representando o valor de uma constante de tipo enumerado
VALUE_ARRAY 0x1c (nenhum; deve ser 0 ) matriz_codificada um array de valores, no formato especificado por " encoded_array format" abaixo. O tamanho do value está implícito na codificação.
VALUE_ANNOTATION 0x1d (nenhum; deve ser 0 ) anotação_codificada uma sub-anotação, no formato especificado por " formato de encoded_annotation " abaixo. O tamanho do value está implícito na codificação.
VALUE_NULL 0x1e (nenhum; deve ser 0 ) (Nenhum) valor de referência null
VALUE_BOOLEAN 0x1f booleano (0…1) (Nenhum) valor de um bit; 0 para false e 1 para true . O bit é representado no value_arg .

formato codificado_array

Nome Formato Descrição
Tamanho uleb128 número de elementos na matriz
valores valor_codificado[tamanho] uma série de seqüências de bytes de size encoded_value no formato especificado por esta seção, concatenadas sequencialmente.

formato de anotação codificado

Nome Formato Descrição
type_idx uleb128 tipo de anotação. Este deve ser um tipo de classe (não array ou primitivo).
Tamanho uleb128 número de mapeamentos nome-valor nesta anotação
elementos annotation_element[tamanho] elementos da anotação, representados diretamente em linha (não como deslocamentos). Os elementos devem ser classificados em ordem crescente pelo índice string_id .

formato annotation_element

Nome Formato Descrição
nome_idx uleb128 nome do elemento, representado como um índice na seção string_ids . A string deve estar em conformidade com a sintaxe de MemberName , definida acima.
valor valor_codificado valor do elemento

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.

SimpleName

Um SimpleName é a base para a sintaxe dos nomes de outras coisas. O formato .dex permite uma quantidade razoável de latitude aqui (muito mais do que os idiomas de origem mais comuns). Em resumo, um nome simples consiste em qualquer caractere ou dígito alfabético baixo ASCII, alguns símbolos específicos em 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 pontos de código substitutos (no intervalo U+d800U+dfff ) não são considerados caracteres de nome válidos, por si só, mas 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 Simples
SimpleNameChar ( SimpleNameChar )*
SimpleNameChar
'A' ... 'Z'
| 'a' ... 'z'
| '0''9'
| ' ' desde a versão DEX 040
| '$'
| '-'
| '_'
| U+00a0 desde a versão DEX 040
| U+00a1U+1fff
| U+2000U+200a desde a versão DEX 040
| U+2010U+2027
| U+202f desde a versão DEX 040
| U+2030U+d7ff
| U+e000U+ffef
| U+10000U+10ffff

Nome do membro

usado por field_id_item e method_id_item

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

Nome do membro
SimpleName
| '<' SimpleName '>'

FullClassName

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

FullClassName
OpcionalPackagePrefix SimpleName
OpcionalPacotePrefixo
( SimpleName '/' )*

Descritor de tipo

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.

Descritor de Tipo→
'V'
| Descritor de tipo de campo
Descritor de tipo de campo →
NonArrayFieldTypeDescriptor
| ( '[' * 1…255) NonArrayFieldTypeDescriptor
NonArrayFieldTypeDescriptor
'Z'
| 'B'
| 'S'
| 'C'
| 'I'
| 'J'
| 'F'
| 'D'
| 'L' FullClassName ';'

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' .

ShortyDescritor
ShortyReturnType ( ShortyFieldType )*
ShortyReturnType
'V'
| ShortyFieldType
ShortyFieldType
'Z'
| 'B'
| 'S'
| 'C'
| 'I'
| 'J'
| 'F'
| 'D'
| 'L'

Semântica do descritor de tipo

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

Sintaxe Significado
V void ; válido apenas para tipos de retorno
Z boolean
B byte
S short
C char
EU int
J long
F float
D double
L totalmente/qualificado/Nome ; a classe fully.qualified.Name
[ descritor array of descriptor , utilizável recursivamente para arrays-of-arrays, embora seja inválido ter mais de 255 dimensões.

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 .

cabeçalho_item

aparece na seção de cabeçalho

alinhamento: 4 bytes

Nome Formato Descrição
Magia ubyte[8] = DEX_FILE_MAGIC valor mágico. Veja a discussão acima em " DEX_FILE_MAGIC " para mais detalhes.
soma de verificação uint adler32 checksum do resto do arquivo (tudo menos magic e este campo); usado para detectar corrupção de arquivos
assinatura ubyte[20] Assinatura SHA-1 (hash) do resto do arquivo (tudo menos magic , checksum e este campo); usado para identificar exclusivamente arquivos
tamanho do arquivo uint tamanho do arquivo inteiro (incluindo o cabeçalho), em bytes
header_size uint = 0x70 tamanho do cabeçalho (esta seção inteira), em bytes. Isso permite pelo menos uma quantidade limitada de compatibilidade para trás/para frente sem invalidar o formato.
endian_tag uint = ENDIAN_CONSTANT marca endianness. Consulte a discussão acima em " ENDIAN_CONSTANT e REVERSE_ENDIAN_CONSTANT " para obter mais detalhes.
tamanho_link uint tamanho da seção do link ou 0 se este arquivo não estiver vinculado estaticamente
link_off uint deslocamento do início do arquivo para a seção de link, ou 0 se link_size == 0 . O deslocamento, se diferente de zero, deve ser um deslocamento na seção link_data . O formato dos dados apontados não é especificado por este documento; este campo de cabeçalho (e o anterior) são deixados como ganchos para uso por implementações de tempo de execução.
map_off uint deslocamento do início do arquivo para o item de mapa. O deslocamento, que deve ser diferente de zero, deve ser um deslocamento na seção de data , e os dados devem estar no formato especificado por " map_list " abaixo.
string_ids_size uint contagem de strings na lista de identificadores de string
string_ids_off uint deslocamento do início do arquivo para a lista de identificadores de string, ou 0 se string_ids_size == 0 (reconhecidamente um caso estranho). O deslocamento, se diferente de zero, deve ser para o início da seção string_ids .
type_ids_size uint contagem de elementos na lista de identificadores de tipo, no máximo 65535
type_ids_off uint deslocamento do início do arquivo para a lista de identificadores de tipo, ou 0 se type_ids_size == 0 (reconhecidamente um caso estranho). O deslocamento, se diferente de zero, deve ser para o início da seção type_ids .
proto_ids_size uint contagem de elementos na lista de identificadores de protótipo, no máximo 65535
proto_ids_off uint deslocamento do início do arquivo para a lista de identificadores de protótipo, ou 0 se proto_ids_size == 0 (reconhecidamente um caso estranho). O deslocamento, se diferente de zero, deve ser para o início da seção proto_ids .
field_ids_size uint contagem de elementos na lista de identificadores de campo
field_ids_off uint deslocamento do início do arquivo para a lista de identificadores de campo ou 0 se field_ids_size == 0 . O deslocamento, se diferente de zero, deve ser para o início da seção field_ids .
method_ids_size uint contagem de elementos na lista de identificadores de método
method_ids_off uint deslocamento do início do arquivo para a lista de identificadores de método ou 0 se method_ids_size == 0 . O deslocamento, se diferente de zero, deve ser para o início da seção method_ids .
class_defs_size uint contagem de elementos na lista de definições de classe
class_defs_off uint deslocamento do início do arquivo para a lista de definições de classe, ou 0 se class_defs_size == 0 (reconhecidamente um caso estranho). O deslocamento, se diferente de zero, deve ser para o início da seção class_defs .
data_size uint Tamanho da seção de data em bytes. Deve ser um múltiplo par de sizeof(uint).
data_off uint deslocamento desde o início do arquivo até o início da seção de data .

lista_mapa

aparece na seção de dados

referenciado de 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 em um arquivo inteiro. Um determinado tipo deve aparecer no máximo uma vez em um mapa, mas não há restrição em quais tipos de ordem podem aparecer, além das restrições implícitas no resto do formato (por exemplo, uma seção de 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.

Nome Formato Descrição
Tamanho uint tamanho da lista, em entradas
Lista map_item[tamanho] elementos da lista

formato map_item

Nome Formato Descrição
modelo ushor tipo dos itens; Veja a tabela abaixo
não utilizado ushor (sem uso)
Tamanho uint contagem do número de itens a serem encontrados no deslocamento indicado
Deslocamento uint deslocamento do início do arquivo para os itens em questão

Códigos de tipo

Tipo de item Constante Valor Tamanho do item em bytes
cabeçalho_item TYPE_HEADER_ITEM 0x0000 0x70
string_id_item TYPE_STRING_ID_ITEM 0x0001 0x04
type_id_item TYPE_TYPE_ID_ITEM 0x0002 0x04
proto_id_item TYPE_PROTO_ID_ITEM 0x0003 0x0c
field_id_item TYPE_FIELD_ID_ITEM 0x0004 0x08
method_id_item TYPE_METHOD_ID_ITEM 0x0005 0x08
class_def_item TYPE_CLASS_DEF_ITEM 0x0006 0x20
call_site_id_item TYPE_CALL_SITE_ID_ITEM 0x0007 0x04
method_handle_item TYPE_METHOD_HANDLE_ITEM 0x0008 0x08
lista_mapa TYPE_MAP_LIST 0x1000 4 + (item.tamanho * 12)
type_list TYPE_TYPE_LIST 0x1001 4 + (item.tamanho * 2)
annotation_set_ref_list TYPE_ANNOTATION_SET_REF_LIST 0x1002 4 + (item.tamanho * 4)
annotation_set_item TYPE_ANNOTATION_SET_ITEM 0x1003 4 + (item.tamanho * 4)
class_data_item TYPE_CLASS_DATA_ITEM 0x2000 implícito; deve analisar
code_item TYPE_CODE_ITEM 0x2001 implícito; deve analisar
string_data_item TYPE_STRING_DATA_ITEM 0x2002 implícito; deve analisar
debug_info_item TYPE_DEBUG_INFO_ITEM 0x2003 implícito; deve analisar
anotação_item TYPE_ANNOTATION_ITEM 0x2004 implícito; deve analisar
codificado_array_item TYPE_ENCODED_ARRAY_ITEM 0x2005 implícito; deve analisar
annotations_directory_item TYPE_ANNOTATIONS_DIRECTORY_ITEM 0x2006 implícito; deve analisar
hiddenapi_class_data_item TYPE_HIDDENAPI_CLASS_DATA_ITEM 0xF000 implícito; deve analisar

string_id_item

aparece na seção string_ids

alinhamento: 4 bytes

Nome Formato Descrição
string_data_off uint deslocamento do início do arquivo para os dados de string para este item. O deslocamento deve estar em um local na seção de data e os dados devem estar no formato especificado por " string_data_item " abaixo. Não há requisito de alinhamento para o deslocamento.

string_data_item

aparece na seção de dados

alinhamento: nenhum (alinhado por byte)

Nome Formato Descrição
utf16_size uleb128 tamanho desta string, em unidades de código UTF-16 (que é o "comprimento da string" em muitos sistemas). Ou seja, este é o comprimento decodificado da string. (O comprimento codificado está implícito na posição do byte 0 )
dados ubyte[] uma série de unidades de código MUTF-8 (aka octetos, também conhecido como bytes) seguido por um byte de valor 0 . Consulte "Codificação MUTF-8 (UTF-8 Modificada)" acima para obter detalhes e discussão sobre o formato de dados.

Nota: É aceitável ter uma string que inclua (a forma codificada de) unidades de código substituto UTF-16 (ou seja, U+d800U+dfff ) isoladamente ou fora de ordem em relação à codificação usual de Unicode em UTF-16. Cabe aos usos de strings de nível superior rejeitar essas codificações inválidas, se apropriado.

type_id_item

aparece na seção type_ids

alinhamento: 4 bytes

Nome Formato Descrição
descriptor_idx uint index na lista string_ids para a string do descritor desse tipo. A string deve estar de acordo com a sintaxe para TypeDescriptor , definida acima.

proto_id_item

aparece na seção proto_ids

alinhamento: 4 bytes

Nome Formato Descrição
shorty_idx uint index na lista string_ids para a string do descritor de formato curto deste protótipo. A string deve estar de acordo com a sintaxe de ShortyDescriptor , definida acima, e deve corresponder ao tipo de retorno e aos parâmetros deste item.
return_type_idx uint index na lista type_ids para o tipo de retorno deste protótipo
parâmetros_desligado uint deslocamento do início do arquivo para a lista de tipos de parâmetros para este protótipo, ou 0 se este protótipo não tiver parâmetros. Este deslocamento, se diferente de zero, deve estar na seção de data , e os dados devem estar no formato especificado por "type_list" abaixo. Além disso, não deve haver referência ao tipo void na lista.

field_id_item

aparece na seção field_ids

alinhamento: 4 bytes

Nome Formato Descrição
class_idx ushor index na lista type_ids para o definidor deste campo. Este deve ser um tipo de classe e não uma matriz ou tipo primitivo.
type_idx ushor indexe na lista type_ids para o tipo deste campo
nome_idx uint index na lista string_ids para o nome deste campo. A string deve estar em conformidade com a sintaxe de MemberName , definida acima.

method_id_item

aparece na seção method_ids

alinhamento: 4 bytes

Nome Formato Descrição
class_idx ushor index na lista type_ids para o definidor desse método. Este deve ser um tipo de classe ou array, e não um tipo primitivo.
proto_idx ushor index na lista proto_ids para o protótipo deste método
nome_idx uint index na lista string_ids para o nome deste método. A string deve estar em conformidade com a sintaxe de MemberName , definida acima.

class_def_item

aparece na seção class_defs

alinhamento: 4 bytes

Nome Formato Descrição
class_idx uint index na lista type_ids para esta classe. Este deve ser um tipo de classe e não uma matriz ou tipo primitivo.
access_flags uint sinalizadores de acesso para a classe ( public , final , etc.). Consulte " definições de access_flags " para obter detalhes.
superclass_idx uint index na lista type_ids para a superclasse, ou o valor constante NO_INDEX se esta classe não tiver superclasse (ou seja, é uma classe raiz como Object ). Se estiver presente, deve ser um tipo de classe e não uma matriz ou tipo primitivo.
interfaces_off uint deslocamento do início do arquivo para a lista de interfaces ou 0 se não houver nenhuma. Este deslocamento deve estar na seção de data , e os dados devem estar no formato especificado por " type_list " abaixo. Cada um dos elementos da lista deve ser um tipo de classe (não uma matriz ou tipo primitivo) e não deve haver duplicatas.
source_file_idx uint index na lista string_ids para o nome do arquivo que contém a fonte original para (pelo menos a maioria) desta classe, ou o valor especial NO_INDEX para representar a falta desta informação. O debug_info_item de qualquer método pode substituir este arquivo de origem, mas a expectativa é que a maioria das classes venha apenas de um arquivo de origem.
annotations_off uint deslocamento do início do arquivo para a estrutura de anotações para esta classe, ou 0 se não houver anotações nesta classe. Este deslocamento, se diferente de zero, deve estar na seção de data , e os dados devem estar no formato especificado por " annotations_directory_item " abaixo, com todos os itens referentes a esta classe como o definidor.
class_data_off uint deslocamento do início do arquivo para os dados de classe associados para este item, ou 0 se não houver dados de classe para esta classe. (Este pode ser o caso, por exemplo, se esta classe for uma interface de marcador.) O deslocamento, se diferente de zero, deve estar na seção de data , e os dados devem estar no formato especificado por " class_data_item " abaixo, com todos os itens referentes a esta classe como o definidor.
static_values_off uint deslocamento do início do arquivo para a lista de valores iniciais para campos static , ou 0 se não houver nenhum (e todos os campos static devem ser inicializados com 0 ou null ). Esse deslocamento deve estar na seção de data e os dados devem estar no formato especificado por " encoded_array_item " abaixo. O tamanho do array não deve ser maior que o número de campos static declarados por esta classe, e os elementos correspondem aos campos static na mesma ordem declarada no field_list correspondente. O tipo de cada elemento do array deve corresponder ao tipo declarado de seu campo correspondente. Se houver menos elementos na matriz do que campos static , os campos restantes serão inicializados com um tipo apropriado 0 ou null .

call_site_id_item

aparece na seção call_site_ids

alinhamento: 4 bytes

Nome Formato Descrição
call_site_off uint deslocamento desde o início do arquivo para chamar a definição do site. O deslocamento deve estar na seção de dados e os dados devem estar no formato especificado por "call_site_item" abaixo.

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 a um método vinculador de bootstrap. Os três primeiros argumentos são:

  1. Um identificador de método que representa o método do vinculador de bootstrap (VALUE_METHOD_HANDLE).
  2. Um nome de método que o vinculador de bootstrap deve resolver (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

Name Format Descrição
method_handle_type ushort type of the method handle; see table below
unused ushort (unused)
field_or_method_id ushort Field or method id depending on whether the method handle type is an accessor or a method invoker
unused ushort (unused)

Method Handle Type Codes

Constant Value Descrição
METHOD_HANDLE_TYPE_STATIC_PUT 0x00 Method handle is a static field setter (accessor)
METHOD_HANDLE_TYPE_STATIC_GET 0x01 Method handle is a static field getter (accessor)
METHOD_HANDLE_TYPE_INSTANCE_PUT 0x02 Method handle is an instance field setter (accessor)
METHOD_HANDLE_TYPE_INSTANCE_GET 0x03 Method handle is an instance field getter (accessor)
METHOD_HANDLE_TYPE_INVOKE_STATIC 0x04 Method handle is a static method invoker
METHOD_HANDLE_TYPE_INVOKE_INSTANCE 0x05 Method handle is an instance method invoker
METHOD_HANDLE_TYPE_INVOKE_CONSTRUCTOR 0x06 Method handle is a constructor method invoker
METHOD_HANDLE_TYPE_INVOKE_DIRECT 0x07 Method handle is a direct method invoker
METHOD_HANDLE_TYPE_INVOKE_INTERFACE 0x08 Method handle is an interface method invoker

class_data_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

Name Format Descrição
static_fields_size uleb128 the number of static fields defined in this item
instance_fields_size uleb128 the number of instance fields defined in this item
direct_methods_size uleb128 the number of direct methods defined in this item
virtual_methods_size uleb128 the number of virtual methods defined in this item
static_fields encoded_field[static_fields_size] the defined static fields, represented as a sequence of encoded elements. The fields must be sorted by field_idx in increasing order.
instance_fields encoded_field[instance_fields_size] the defined instance fields, represented as a sequence of encoded elements. The fields must be sorted by field_idx in increasing order.
direct_methods encoded_method[direct_methods_size] the defined direct (any of static , private , or constructor) methods, represented as a sequence of encoded elements. The methods must be sorted by method_idx in increasing order.
virtual_methods encoded_method[virtual_methods_size] the defined virtual (none of static , private , or constructor) methods, represented as a sequence of encoded elements. This list should not include inherited methods unless overridden by the class that this item represents. The methods must be sorted by method_idx in increasing order. The method_idx of a virtual method must not be the same as any direct method.

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

encoded_field format

Name Format Descrição
field_idx_diff uleb128 index into the field_ids list for the identity of this field (includes the name and descriptor), represented as a difference from the index of previous element in the list. The index of the first element in a list is represented directly.
access_flags uleb128 access flags for the field ( public , final , etc.). See " access_flags Definitions" for details.

encoded_method format

Name Format Descrição
method_idx_diff uleb128 index into the method_ids list for the identity of this method (includes the name and descriptor), represented as a difference from the index of previous element in the list. The index of the first element in a list is represented directly.
access_flags uleb128 access flags for the method ( public , final , etc.). See " access_flags Definitions" for details.
code_off uleb128 offset from the start of the file to the code structure for this method, or 0 if this method is either abstract or native . The offset should be to a location in the data section. The format of the data is specified by " code_item " below.

type_list

referenced from class_def_item and proto_id_item

appears in the data section

alignment: 4 bytes

Name Format Descrição
size uint size of the list, in entries
list type_item[size] elements of the list

type_item format

Name Format Descrição
type_idx ushort index into the type_ids list

code_item

referenced from encoded_method

appears in the data section

alignment: 4 bytes

Name Format Descrição
registers_size ushort the number of registers used by this code
ins_size ushort the number of words of incoming arguments to the method that this code is for
outs_size ushort the number of words of outgoing argument space required by this code for method invocation
tries_size ushort the number of try_item s for this instance. If non-zero, then these appear as the tries array just after the insns in this instance.
debug_info_off uint offset from the start of the file to the debug info (line numbers + local variable info) sequence for this code, or 0 if there simply is no information. The offset, if non-zero, should be to a location in the data section. The format of the data is specified by " debug_info_item " below.
insns_size uint size of the instructions list, in 16-bit code units
insns ushort[insns_size] actual array of bytecode. The format of code in an insns array is specified by the companion document Dalvik bytecode . Note that though this is defined as an array of ushort , there are some internal structures that prefer four-byte alignment. Also, if this happens to be in an endian-swapped file, then the swapping is only done on individual ushort s and not on the larger internal structures.
padding ushort (optional) = 0 two bytes of padding to make tries four-byte aligned. This element is only present if tries_size is non-zero and insns_size is odd.
tries try_item[tries_size] (optional) array indicating where in the code exceptions are caught and how to handle them. Elements of the array must be non-overlapping in range and in order from low to high address. This element is only present if tries_size is non-zero.
handlers encoded_catch_handler_list (optional) bytes representing a list of lists of catch types and associated handler addresses. Each try_item has a byte-wise offset into this structure. This element is only present if tries_size is non-zero.

try_item format

Name Format Descrição
start_addr uint start address of the block of code covered by this entry. The address is a count of 16-bit code units to the start of the first covered instruction.
insn_count ushort number of 16-bit code units covered by this entry. The last code unit covered (inclusive) is start_addr + insn_count - 1 .
handler_off ushort offset in bytes from the start of the associated encoded_catch_hander_list to the encoded_catch_handler for this entry. This must be an offset to the start of an encoded_catch_handler .

encoded_catch_handler_list format

Name Format Descrição
size uleb128 size of this list, in entries
list encoded_catch_handler[handlers_size] actual list of handler lists, represented directly (not as offsets), and concatenated sequentially

encoded_catch_handler format

Name Format Descrição
size sleb128 number of catch types in this list. If non-positive, then this is the negative of the number of catch types, and the catches are followed by a catch-all handler. For example: A size of 0 means that there is a catch-all but no explicitly typed catches. A size of 2 means that there are two explicitly typed catches and no catch-all. And a size of -1 means that there is one typed catch along with a catch-all.
handlers encoded_type_addr_pair[abs(size)] stream of abs(size) encoded items, one for each caught type, in the order that the types should be tested.
catch_all_addr uleb128 (optional) bytecode address of the catch-all handler. This element is only present if size is non-positive.

encoded_type_addr_pair format

Name Format Descrição
type_idx uleb128 index into the type_ids list for the type of the exception to catch
addr uleb128 bytecode address of the associated exception handler

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:

Name Format Descrição
line_start uleb128 the initial value for the state machine's line register. Does not represent an actual positions entry.
parameters_size uleb128 the number of parameter names that are encoded. There should be one per method parameter, excluding an instance method's this , if any.
parameter_names uleb128p1[parameters_size] string index of the method parameter name. An encoded value of NO_INDEX indicates that no name is available for the associated parameter. The type descriptor and signature are implied from the method descriptor and signature.

The byte code values are as follows:

Name Value Format Arguments Descrição
DBG_END_SEQUENCE 0x00 (none) terminates a debug info sequence for a code_item
DBG_ADVANCE_PC 0x01 uleb128 addr_diff addr_diff : amount to add to address register advances the address register without emitting a positions entry
DBG_ADVANCE_LINE 0x02 sleb128 line_diff line_diff : amount to change line register by advances the line register without emitting a positions entry
DBG_START_LOCAL 0x03 uleb128 register_num
uleb128p1 name_idx
uleb128p1 type_idx
register_num : register that will contain local
name_idx : string index of the name
type_idx : type index of the type
introduces a local variable at the current address. Either name_idx or type_idx may be NO_INDEX to indicate that that value is unknown.
DBG_START_LOCAL_EXTENDED 0x04 uleb128 register_num
uleb128p1 name_idx
uleb128p1 type_idx
uleb128p1 sig_idx
register_num : register that will contain local
name_idx : string index of the name
type_idx : type index of the type
sig_idx : string index of the type signature
introduces a local with a type signature at the current address. Any of name_idx , type_idx , or sig_idx may be NO_INDEX to indicate that that value is unknown. (If sig_idx is -1 , though, the same data could be represented more efficiently using the opcode DBG_START_LOCAL .)

Note: See the discussion under " dalvik.annotation.Signature " below for caveats about handling signatures.

DBG_END_LOCAL 0x05 uleb128 register_num register_num : register that contained local marks a currently-live local variable as out of scope at the current address
DBG_RESTART_LOCAL 0x06 uleb128 register_num register_num : register to restart re-introduces a local variable at the current address. The name and type are the same as the last local that was live in the specified register.
DBG_SET_PROLOGUE_END 0x07 (none) sets the prologue_end state machine register, indicating that the next position entry that is added should be considered the end of a method prologue (an appropriate place for a method breakpoint). The prologue_end register is cleared by any special ( >= 0x0a ) opcode.
DBG_SET_EPILOGUE_BEGIN 0x08 (none) sets the epilogue_begin state machine register, indicating that the next position entry that is added should be considered the beginning of a method epilogue (an appropriate place to suspend execution before method exit). The epilogue_begin register is cleared by any special ( >= 0x0a ) opcode.
DBG_SET_FILE 0x09 uleb128p1 name_idx name_idx : string index of source file name; NO_INDEX if unknown indicates that all subsequent line number entries make reference to this source file name, instead of the default name specified in code_item
Special Opcodes 0x0a…0xff (none) advances the line and address registers, emits a position entry, and clears prologue_end and epilogue_begin . See below for description.

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

Name Format Descrição
class_annotations_off uint offset from the start of the file to the annotations made directly on the class, or 0 if the class has no direct annotations. The offset, if non-zero, should be to a location in the data section. The format of the data is specified by " annotation_set_item " below.
fields_size uint count of fields annotated by this item
annotated_methods_size uint count of methods annotated by this item
annotated_parameters_size uint count of method parameter lists annotated by this item
field_annotations field_annotation[fields_size] (optional) list of associated field annotations. The elements of the list must be sorted in increasing order, by field_idx .
method_annotations method_annotation[methods_size] (optional) list of associated method annotations. The elements of the list must be sorted in increasing order, by method_idx .
parameter_annotations parameter_annotation[parameters_size] (optional) list of associated method parameter annotations. The elements of the list must be sorted in increasing order, by method_idx .

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

field_annotation format

Name Format Descrição
field_idx uint index into the field_ids list for the identity of the field being annotated
annotations_off uint offset from the start of the file to the list of annotations for the field. The offset should be to a location in the data section. The format of the data is specified by " annotation_set_item " below.

method_annotation format

Name Format Descrição
method_idx uint index into the method_ids list for the identity of the method being annotated
annotations_off uint offset from the start of the file to the list of annotations for the method. The offset should be to a location in the data section. The format of the data is specified by " annotation_set_item " below.

parameter_annotation format

Name Format Descrição
method_idx uint index into the method_ids list for the identity of the method whose parameters are being annotated
annotations_off uint offset from the start of the file to the list of annotations for the method parameters. The offset should be to a location in the data section. The format of the data is specified by " annotation_set_ref_list " below.

annotation_set_ref_list

referenced from parameter_annotations_item

appears in the data section

alignment: 4 bytes

Name Format Descrição
size uint size of the list, in entries
list annotation_set_ref_item[size] elements of the list

annotation_set_ref_item format

Name Format Descrição
annotations_off uint offset from the start of the file to the referenced annotation set or 0 if there are no annotations for this element. The offset, if non-zero, should be to a location in the data section. The format of the data is specified by " annotation_set_item " below.

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

Name Format Descrição
size uint size of the set, in entries
entries annotation_off_item[size] elements of the set. The elements must be sorted in increasing order, by type_idx .

annotation_off_item format

Name Format Descrição
annotation_off uint offset from the start of the file to an annotation. The offset should be to a location in the data section, and the format of the data at that location is specified by " annotation_item " below.

annotation_item

referenced from annotation_set_item

appears in the data section

alignment: none (byte-aligned)

Name Format Descrição
visibility ubyte intended visibility of this annotation (see below)
annotation encoded_annotation encoded annotation contents, in the format described by " encoded_annotation format" under " encoded_value encoding" above.

Visibility values

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

Name Value Descrição
VISIBILITY_BUILD 0x00 intended only to be visible at build time (eg, during compilation of other code)
VISIBILITY_RUNTIME 0x01 intended to visible at runtime
VISIBILITY_SYSTEM 0x02 intended to visible at runtime, but only to the underlying system (and not to regular user code)

encoded_array_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

Name Format Descrição
value encoded_array bytes representing the encoded array value, in the format specified by " encoded_array Format" under " encoded_value Encoding" above.

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 .

Name Format Descrição
size uint total size of the section
offsets uint[] array of offsets indexed by class_idx . A zero array entry at index class_idx means that either there is no data for this class_idx , or all hidden API flags are zero. Otherwise the array entry is non-zero and contains an offset from the beginning of the section to an array of hidden API flags for this class_idx .
flags uleb128[] concatenated arrays of hidden API flags for each class. Possible flag values are described in the table below. Flags are encoded in the same order as fields and methods are encoded in class data.

Restriction flag types:

Name Value Descrição
whitelist 0 Interfaces that can be freely used and are supported as part of the officially documented Android framework Package Index .
greylist 1 Non-SDK interfaces that can be used regardless of the application's target API level .
blacklist 2 Non-SDK interfaces that cannot be used regardless of the application's target API level . Accessing one of these interfaces causes a runtime error .
greylist‑max‑o 3 Non-SDK interfaces that can be used for Android 8.x and below unless they are restricted.
greylist‑max‑p 4 Non-SDK interfaces that can be used for Android 9.x unless they are restricted.
greylist‑max‑q 5 Non-SDK interfaces that can be used for Android 10.x unless they are restricted.
greylist‑max‑r 6 Non-SDK interfaces that can be used for Android 11.x unless they are restricted.

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.

Name Format Descrição
value Annotation the default bindings for this annotation, represented as an annotation of this type. The annotation need not include all names defined by the annotation; missing names simply do not have defaults.

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.

Name Format Descrição
value Class the class which most closely lexically scopes this class

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.

Name Format Descrição
value Method the method which most closely lexically scopes this class

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.

Name Format Descrição
name String the originally declared simple name of this class (not including any package prefix). If this class is anonymous, then the name is null .
accessFlags int the originally declared access flags of the class (which may differ from the effective flags because of a mismatch between the execution models of the source language and target virtual machine)

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.)

Name Format Descrição
value Class[] array of the member classes

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.

Name Format Descrição
names String[] The names of formal parameters for the associated method. The array must not be null but must be empty if there are no formal parameters. A value in the array must be null if the formal parameter with that index has no name.
If parameter name strings are empty or contain '.', ';', '[' or '/' then a java.lang.reflect.MalformedParametersException will be thrown at runtime.
accessFlags int[] The access flags of the formal parameters for the associated method. The array must not be null but must be empty if there are no formal parameters.
The value is a bit mask with the following values:
  • 0x0010 : final, the parameter was declared final
  • 0x1000 : synthetic, the parameter was introduced by the compiler
  • 0x8000 : mandated, the parameter is synthetic but also implied by the language specification
If any bits are set outside of this set then a java.lang.reflect.MalformedParametersException will be thrown at runtime.

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.

Name Format Descrição
value String[] the signature of this class or member, as an array of strings that is to be concatenated together

dalvik.annotation.Throws

appears on methods

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

Name Format Descrição
value Class[] the array of exception types thrown