Dalvik yürütülebilir biçimi

Bu belge, bir dizi sınıf tanımını ve bunlarla ilişkili ek verileri tutmak için kullanılan .dex dosyalarının düzenini ve içeriğini açıklar.

Türler için rehber

LEB128

LEB128 ("Little-Endian B ase 128 " ) , rastgele işaretli veya işaretsiz tamsayı miktarları için değişken uzunluklu bir kodlamadır. Format, DWARF3 spesifikasyonundan ödünç alınmıştır. Bir .dex dosyasında LEB128 yalnızca 32 bitlik miktarları kodlamak için kullanılır.

Her LEB128 kodlanmış değeri, birlikte tek bir 32 bitlik değeri temsil eden bir ila beş bayttan oluşur. Sıradaki en anlamlı biti net olan son bayt dışında, her bayt en anlamlı bit kümesine sahiptir. Her bir baytın kalan yedi biti, miktarın en az anlamlı yedi biti ilk baytta, sonraki yedi biti ikinci baytta vb. olmak üzere yüktür. İşaretli bir LEB128 ( sleb128 ) durumunda, dizideki son baytın en önemli veri yükü biti, nihai değeri üretmek için işaretle genişletilir. İşaretsiz durumda ( uleb128 ) açıkça temsil edilmeyen bitler 0 olarak yorumlanır.

uleb128p1 varyantı, işaretli bir değeri temsil etmek için kullanılır, burada temsil değer artı bir uleb128 olarak kodlanmıştır. Bu, -1 (alternatif olarak 0xffffffff işaretsiz değeri olarak düşünülür) - ancak başka bir negatif sayı olmayan - tek bir bayt kodlamasını yapar ve tam olarak temsil edilen sayının negatif olmaması veya -1 (veya 0xffffffff ) ve başka hiçbir negatif değere izin verilmeyen (veya büyük işaretsiz değerlere gerek duyulmayan) durumlarda.

İşte bazı biçim örnekleri:

Dosya düzeni

Bitfield, dize ve sabit tanımlar

DEX_FILE_MAGIC

header_item içine gömülü

Sabit dizi/dize DEX_FILE_MAGIC , bir .dex dosyasının bu şekilde tanınması için başında görünmesi gereken baytların listesidir. Değer, belirli bozulma biçimlerinin saptanmasına yardımcı olmak için kasıtlı olarak bir yeni satır ( "\n" veya 0x0a ) ve bir boş bayt ( "\0" veya 0x00 ) içerir. Değer ayrıca bir biçim sürüm numarasını, biçim geliştikçe zaman içinde monoton bir şekilde artması beklenen üç ondalık basamak olarak kodlar.

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

Not: 039 sürümü için destek, const-method-handle ve const-method-type olmak üzere iki yeni bayt kodu sunan Android 9.0 sürümüne eklendi. (Bunların her biri Özet bayt kodu kümesi tablosunda açıklanmıştır.) Android 10'da sürüm 039 , DEX dosya biçimini yalnızca önyükleme sınıfı yolundaki DEX dosyaları için geçerli olan gizli API bilgilerini içerecek şekilde genişletir.

Not: 038 sürümü desteği, Android 8.0 sürümüne eklenmiştir. Sürüm 038 , yeni bayt kodları ( invoke-polymorphic ve invoke-custom ) ve yöntem tanıtıcıları için veriler ekledi.

Not: 037 sürümü desteği, Android 7.0 sürümüne eklenmiştir. 037 sürümünden önce, Android'in çoğu sürümü, biçimin 035 sürümünü kullanıyordu. 035 ve 037 sürümleri arasındaki tek fark, varsayılan yöntemlerin eklenmesi ve invoke ayarlanmasıdır.

Not: Formatın en az birkaç önceki sürümü, yaygın olarak bulunan genel yazılım sürümlerinde kullanılmıştır. Örneğin, Android platformunun M3 sürümleri (Kasım-Aralık 2007) için 009 sürümü ve Android platformunun M5 sürümleri (Şubat-Mart 2008) için 013 sürümü kullanıldı. Biçimin bu önceki sürümleri, birçok açıdan bu belgede açıklanan sürümden önemli ölçüde farklıdır.

ENDIAN_CONSTANT ve REVERSE_ENDIAN_CONSTANT

header_item içine gömülü

ENDIAN_CONSTANT sabiti, içinde bulunduğu dosyanın endianlığını belirtmek için kullanılır. Standart .dex biçimi küçük endian olsa da, uygulamalar bayt değiş tokuşu yapmayı seçebilir. Bir uygulama, endian_tag REVERSE_ENDIAN_CONSTANT yerine ENDIAN_CONSTANT olan bir üstbilgiyle karşılaşırsa, dosyanın beklenen biçimden bayt değiş tokuşu yapıldığını bilir.

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

NO_INDEX

class_def_item ve debug_info_item içine gömülü

NO_INDEX sabiti, bir indeks değerinin olmadığını belirtmek için kullanılır.

Not: Bu değer 0 olarak tanımlanmamıştır, çünkü bu aslında tipik olarak geçerli bir dizindir.

NO_INDEX için seçilen değer, uleb128p1 kodlamasında tek bir bayt olarak gösterilebilir.

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

access_flags tanımları

class_def_item, encoded_field, encoded_method ve InnerClass'a gömülü

Bu bayrakların bit alanları, sınıfların ve sınıf üyelerinin erişilebilirliğini ve genel özelliklerini belirtmek için kullanılır.

* Yalnızca InnerClass ek açıklamaları için izin verilir ve hiçbir zaman class_def_item içinde açık olmamalıdır.

MUTF-8 (Değiştirilmiş UTF-8) Kodlaması

Daha kolay eski desteğin bir imtiyazı olarak, .dex biçimi, dize verilerini, bundan sonra MUTF-8 olarak anılacak olan fiili standart değiştirilmiş UTF-8 biçiminde kodlar. Bu form, aşağıdakiler dışında standart UTF-8 ile aynıdır:

• Yalnızca bir, iki ve üç baytlık kodlamalar kullanılır.
• U+10000 … U+10ffff aralığındaki kod noktaları, her biri üç baytlık kodlanmış bir değer olarak temsil edilen vekil bir çift olarak kodlanır.
• U+0000 kod noktası iki bayt biçiminde kodlanmıştır.
• Düz bir boş bayt (değer 0 ), standart C dili yorumunda olduğu gibi bir dizenin sonunu belirtir.

Yukarıdaki ilk iki öğe şu şekilde özetlenebilir: MUTF-8, Unicode karakterler için daha doğrudan bir kodlama biçimi olmak yerine UTF-16 için bir kodlama biçimidir.

Yukarıdaki son iki öğe, U+0000 kod noktasını bir dizgeye dahil etmeyi ve yine de onu C-stili boş sonlandırılmış bir dizge olarak işlemeyi aynı anda mümkün kılar.

Bununla birlikte, U+0000 özel kodlaması, normal UTF-8'den farklı olarak, bir çift MUTF-8 dizesinde standart C işlevinin strcmp() çağrılmasının sonucunun, her zaman, eşit olmayan dizelerin karşılaştırmasının doğru şekilde imzalanmış sonucunu göstermediği anlamına gelir. . Sıralama (yalnızca eşitlik değil) söz konusu olduğunda, MUTF-8 dizelerini karşılaştırmanın en basit yolu onları karakter karakter çözmek ve kodu çözülen değerleri karşılaştırmaktır. (Ancak, daha akıllı uygulamalar da mümkündür.)

Karakter kodlaması hakkında daha fazla bilgi için lütfen Unicode Standardına bakın. MUTF-8 aslında (nispeten daha az bilinen) CESU-8'i kodlamaya kendi başına UTF-8'den daha yakındır.

kodlanmış_değer kodlaması

annotation_element ve encoding_array_item içine gömülü

Encoding_value, (neredeyse) rastgele hiyerarşik olarak yapılandırılmış verilerin encoded_value bir parçasıdır. Kodlamanın hem kompakt hem de ayrıştırılması kolay olması amaçlanmıştır.

Değer biçimleri

kodlanmış_dizi biçimi

kodlanmış_annotation biçimi

annotation_element biçimi

dize sözdizimi

Bir .dex dosyasında, nihayetinde bir dizgeye atıfta bulunan birkaç çeşit öğe vardır. Aşağıdaki BNF stili tanımlar, bu dizeler için kabul edilebilir sözdizimini gösterir.

BasitAdı

SimpleName , diğer şeylerin adlarının sözdiziminin temelidir. .dex formatı burada oldukça geniş bir alana izin verir (çoğu yaygın kaynak dilden çok daha fazlası). Kısaca, basit bir ad, herhangi bir düşük ASCII alfabetik karakter veya rakamdan, birkaç özel düşük ASCII sembolünden ve kontrol, boşluk veya özel karakter olmayan çoğu ASCII olmayan kod noktasından oluşur. 040 sürümünden başlayarak, biçim ek olarak boşluk karakterlerine izin verir (Unicode Zs kategorisi). Yedek kod noktalarının ( U+d800 … U+dfff ) kendi başına geçerli ad karakterleri olarak kabul edilmediğini, ancak Unicode tamamlayıcı karakterlerinin geçerli olduğunu (bunlar SimpleNameChar için kuralın son alternatifiyle temsil edilir) ve bunların geçerli olduğunu unutmayın. MUTF-8 kodlamasında bir dosyada vekil kod noktaları çiftleri olarak temsil edilmelidir.

Üye adı

field_id_item ve method_id_item tarafından kullanılır

ÜyeAdı , bir sınıfın üyesinin adıdır; üyeler alanlar, yöntemler ve iç sınıflardır.

TamSınıfAdı

FullClassName , isteğe bağlı bir paket belirteci ve ardından gerekli bir ad içeren tam nitelikli bir sınıf adıdır.

TipAçıklayıcı

type_id_item tarafından kullanılır

TypeDescriptor , temel öğeler, sınıflar, diziler ve void dahil olmak üzere herhangi bir türün temsilidir. Çeşitli sürümlerin anlamı için aşağıya bakın.

Kısa Tanımlayıcı

proto_id_item tarafından kullanılır

ShortyDescriptor , çeşitli referans (sınıf veya dizi) türleri arasında hiçbir ayrım olmaması dışında, dönüş ve parametre türleri dahil olmak üzere bir yöntem prototipinin kısa biçimli temsilidir. Bunun yerine, tüm referans türleri tek bir 'L' karakteri ile temsil edilir.

TipAçıklayıcı Semantik

TypeDescriptor değişkenlerinin her birinin anlamı budur.

Öğeler ve ilgili yapılar

Bu bölüm, bir .dex dosyasında görünebilecek her bir üst düzey öğenin tanımlarını içerir.

başlık_öğesi

başlık bölümünde görünür

hizalama: 4 bayt

map_list

veri bölümünde görünür

header_item'den referans alındı

hizalama: 4 bayt

Bu, bir dosyanın tüm içeriğinin sırayla bir listesidir. header_item ile ilgili olarak biraz fazlalık içerir, ancak tüm dosya üzerinde yineleme yapmak için kullanımı kolay bir form olması amaçlanmıştır. Belirli bir tür, bir haritada en fazla bir kez görünmelidir, ancak biçimin geri kalanının ima ettiği kısıtlamalar dışında, hangi düzen türlerinin görünebileceği konusunda herhangi bir kısıtlama yoktur (örneğin, önce bir header bölümü görünmelidir, ardından bir string_ids gelmelidir). bölüm vb.). Ek olarak, harita girişleri ilk uzaklığa göre sıralanmalı ve çakışmamalıdır.

map_item biçimi

Tip Kodları

string_id_item

string_ids bölümünde görünür

hizalama: 4 bayt

string_data_item

veri bölümünde görünür

hizalama: yok (bayt hizalı)

type_id_item

type_ids bölümünde görünür

hizalama: 4 bayt

proto_id_item

proto_ids bölümünde görünür

hizalama: 4 bayt

field_id_item

field_ids bölümünde görünür

hizalama: 4 bayt

method_id_item

method_ids bölümünde görünür

hizalama: 4 bayt

class_def_item

class_defs bölümünde görünür

hizalama: 4 bayt

call_site_id_item

call_site_ids bölümünde görünür

hizalama: 4 bayt

call_site_item

veri bölümünde görünür

hizalama: yok (bayt hizalı)

call_site_item, öğeleri bir önyükleme bağlayıcı yöntemine sağlanan bağımsız değişkenlere karşılık gelen bir kodlanmış_array_itemdir. İlk üç argüman:

1. Önyükleme bağlayıcı yöntemini (VALUE_METHOD_HANDLE) temsil eden bir yöntem tanıtıcısı.
2. Önyükleme bağlayıcısının çözümlemesi gereken bir yöntem adı (VALUE_STRING).
3. A method type corresponding to the type of the method name to be resolved (VALUE_METHOD_TYPE).

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

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

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

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

method_handle_item

appears in the method_handles section

alignment: 4 bytes

Method Handle Type Codes

class_data_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

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

encoded_field format

encoded_method format

type_list

referenced from class_def_item and proto_id_item

appears in the data section

alignment: 4 bytes

type_item format

code_item

referenced from encoded_method

appears in the data section

alignment: 4 bytes

try_item format

encoded_catch_handler_list format

encoded_catch_handler format

encoded_type_addr_pair format

debug_info_item

referenced from code_item

appears in the data section

alignment: none (byte-aligned)

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

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

The header is as follows:

The byte code values are as follows:

Special opcodes

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

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

adjusted_opcode = opcode - DBG_FIRST_SPECIAL

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

annotations_directory_item

referenced from class_def_item

appears in the data section

alignment: 4 bytes

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

field_annotation format

method_annotation format

parameter_annotation format

annotation_set_ref_list

referenced from parameter_annotations_item

appears in the data section

alignment: 4 bytes

annotation_set_ref_item format

annotation_set_item

referenced from annotations_directory_item, field_annotations_item, method_annotations_item, and annotation_set_ref_item

appears in the data section

alignment: 4 bytes

annotation_off_item format

annotation_item

referenced from annotation_set_item

appears in the data section

alignment: none (byte-aligned)

Visibility values

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

encoded_array_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

hiddenapi_class_data_item

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

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

Restriction flag types:

System annotations

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

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

dalvik.annotation.AnnotationDefault

appears on methods in annotation interfaces

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

dalvik.annotation.EnclosingClass

appears on classes

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

dalvik.annotation.EnclosingMethod

appears on classes

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

dalvik.annotation.InnerClass

appears on classes

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

dalvik.annotation.MemberClasses

appears on classes

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

dalvik.annotation.MethodParameters

appears on methods

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

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

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

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

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

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

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

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

dalvik.annotation.Signature

appears on classes, fields, and methods

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

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

dalvik.annotation.Throws

appears on methods

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