Format Dalvik yang dapat dieksekusi

Dokumen ini menjelaskan tata letak dan konten file .dex, yang digunakan untuk menyimpan sekumpulan definisi class dan data tambahan terkaitnya.

Panduan jenis

LEB128

LEB128 ("Little-Endian Base 128") adalah enkode panjang variabel untuk jumlah bilangan bulat bertanda atau tanpa tanda arbitrer. Format ini dipinjam dari spesifikasi DWARF3. Dalam file .dex, LEB128 hanya digunakan untuk mengenkode kuantitas 32-bit.

Setiap nilai yang dienkode LEB128 terdiri dari satu hingga lima byte, yang bersama-sama mewakili satu nilai 32-bit. Setiap byte memiliki bit paling signifikan yang ditetapkan kecuali untuk byte terakhir dalam urutan, yang memiliki bit paling signifikan yang jelas. Tujuh bit yang tersisa dari setiap byte adalah payload, dengan tujuh bit yang paling tidak signifikan dari kuantitas dalam byte pertama, tujuh bit berikutnya dalam byte kedua, dan seterusnya. Dalam kasus LEB128 yang ditandatangani (sleb128), bit payload paling signifikan dari byte terakhir dalam urutan diperluas tanda untuk menghasilkan nilai akhir. Dalam kasus tanpa tanda tangan (uleb128), setiap bit yang tidak direpresentasikan secara eksplisit akan ditafsirkan sebagai 0.

Varian uleb128p1 digunakan untuk mewakili nilai yang ditandatangani, dengan representasi nilai plus satu yang dienkode sebagai uleb128. Hal ini membuat encoding -1 (atau dianggap sebagai nilai tanpa tanda tangan 0xffffffff) — tetapi tidak ada angka negatif lainnya — menjadi satu byte, dan berguna persis dalam kasus ketika angka yang direpresentasikan harus non-negatif atau -1 (atau 0xffffffff), dan tidak ada nilai negatif lainnya yang diizinkan (atau jika nilai besar tanpa tanda tangan tidak mungkin diperlukan).

Berikut beberapa contoh formatnya:

Tata letak file

Format penampung

Versi 41 memperkenalkan format penampung baru untuk data DEX dengan tujuan menghemat ruang. Format penampung ini memungkinkan beberapa file DEX logis digabungkan menjadi satu file fisik. Format baru sebagian besar hanya merupakan penyambungan file yang sederhana dalam format sebelumnya, dengan beberapa perbedaan:

• file_size adalah ukuran file logis, bukan file fisik. Fungsi ini dapat digunakan untuk melakukan iterasi pada semua file logis dalam penampung.
• File dex logis dapat mereferensikan data yang lebih baru di penampung (tetapi tidak lebih lama). Hal ini memungkinkan file dex berbagi data, seperti string, di antara file tersebut.
• Semua offset bersifat relatif terhadap file fisik. Tidak ada offset yang relatif terhadap header. Hal ini memastikan bahwa bagian dengan offset dapat dibagikan di antara file logis.
• Header menambahkan dua kolom baru untuk mendeskripsikan batas penampung. Ini adalah pemeriksaan konsistensi tambahan dan mempermudah porting kode ke format baru.
• data_size dan data_off sekarang tidak digunakan. Data dapat tersebar di beberapa file logis dan tidak harus berdekatan.

Definisi bitfield, string, dan konstanta

DEX_FILE_MAGIC

Disematkan di header_item

Array/string konstan DEX_FILE_MAGIC adalah daftar byte yang harus muncul di awal file .dex agar dapat dikenali sebagai file tersebut. Nilai ini sengaja berisi baris baru ("\n" atau 0x0a) dan byte null ("\0" atau 0x00) untuk membantu dalam mendeteksi bentuk kerusakan tertentu. Nilai ini juga mengenkode nomor versi format sebagai tiga digit desimal, yang diperkirakan akan meningkat secara monoton dari waktu ke waktu seiring berkembangnya format.

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

Catatan: Dukungan untuk format versi 040 ditambahkan dalam rilis Android 10.0, yang memperluas kumpulan karakter yang diizinkan di SimpleNames.

Catatan: Dukungan untuk format versi 039 ditambahkan dalam rilis Android 9.0, yang memperkenalkan dua bytecode baru, const-method-handle dan const-method-type. (Masing-masing dijelaskan dalam tabel Ringkasan set bytecode.) Di Android 10, versi 039 memperluas format file DEX untuk menyertakan informasi API tersembunyi yang hanya berlaku untuk file DEX di jalur class booting.

Catatan: Dukungan untuk format versi 038 ditambahkan dalam rilis Android 8.0. Versi 038 menambahkan bytecode baru (invoke-polymorphic dan invoke-custom) serta data untuk handle metode.

Catatan: Dukungan untuk format versi 037 ditambahkan dalam rilis Android 7.0. Sebelum versi 037, sebagian besar versi Android telah menggunakan format versi 035. Satu-satunya perbedaan antara versi 035 dan 037 adalah penambahan metode default dan penyesuaian invoke.

Catatan: Setidaknya beberapa versi format sebelumnya telah digunakan dalam rilis software publik yang tersedia secara luas. Misalnya, versi 009 digunakan untuk rilis M3 platform Android (November–Desember 2007), dan versi 013 digunakan untuk rilis M5 platform Android (Februari–Maret 2008). Dalam beberapa hal, versi format sebelumnya ini sangat berbeda dengan versi yang dijelaskan dalam dokumen ini.

ENDIAN_CONSTANT dan REVERSE_ENDIAN_CONSTANT

Disematkan di header_item

Konstanta ENDIAN_CONSTANT digunakan untuk menunjukkan endianness file tempat file tersebut ditemukan. Meskipun format .dex standar adalah little-endian, implementasi dapat memilih untuk melakukan pertukaran byte. Jika implementasi menemukan header yang endian_tag-nya adalah REVERSE_ENDIAN_CONSTANT, bukan ENDIAN_CONSTANT, implementasi akan mengetahui bahwa file telah ditukar byte dari bentuk yang diharapkan.

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

NO_INDEX

Disematkan dalam class_def_item dan debug_info_item

Konstanta NO_INDEX digunakan untuk menunjukkan bahwa nilai indeks tidak ada.

Catatan: Nilai ini tidak ditentukan sebagai 0, karena sebenarnya biasanya merupakan indeks yang valid.

Nilai yang dipilih untuk NO_INDEX dapat direpresentasikan sebagai satu byte dalam encoding uleb128p1.

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

Definisi access_flags

Disematkan di class_def_item, encoded_field, encoded_method, dan InnerClass

Bitfield tanda ini digunakan untuk menunjukkan aksesibilitas dan properti keseluruhan class dan anggota class.

* Hanya diizinkan untuk anotasi InnerClass, dan tidak boleh diaktifkan di class_def_item.

Encoding UTF-8 yang diubah

Sebagai konsesi untuk dukungan lama yang lebih mudah, format .dex mengenkode data stringnya dalam bentuk UTF-8 modifikasi standar de facto, yang selanjutnya disebut sebagai MUTF-8. Format ini sama dengan UTF-8 standar, kecuali:

• Hanya encoding satu, dua, dan tiga byte yang digunakan.
• Titik kode dalam rentang U+10000 … U+10ffff dienkode sebagai pasangan pengganti, yang masing-masing direpresentasikan sebagai nilai yang dienkode tiga byte.
• Titik kode U+0000 dienkode dalam bentuk dua byte.
• Byte null biasa (nilai 0) menunjukkan akhir string, seperti interpretasi bahasa C standar.

Dua item pertama di atas dapat diringkas sebagai: MUTF-8 adalah format encoding untuk UTF-16, bukan format encoding yang lebih langsung untuk karakter Unicode.

Dua item terakhir di atas memungkinkan untuk menyertakan titik kode U+0000 dalam string dan masih memanipulasinya sebagai string yang diakhiri null bergaya C.

Namun, encoding khusus U+0000 berarti bahwa, tidak seperti UTF-8 normal, hasil pemanggilan fungsi C standar strcmp() pada sepasang string MUTF-8 tidak selalu menunjukkan hasil perbandingan yang ditandatangani dengan benar dari string tidak sama. Jika pengurutan (bukan hanya kesetaraan) menjadi masalah, cara paling sederhana untuk membandingkan string MUTF-8 adalah dengan mendekodenya karakter demi karakter, dan membandingkan nilai yang didekode. (Namun, implementasi yang lebih cerdas juga memungkinkan.)

Lihat Standar Unicode untuk informasi lebih lanjut tentang encoding karakter. MUTF-8 sebenarnya lebih dekat dengan encoding CESU-8 (yang relatif kurang dikenal) daripada UTF-8 secara umum.

encoding encoded_value

Disematkan dalam annotation_element dan encoded_array_item

encoded_value adalah bagian data terstruktur hierarkis (hampir) arbitrer yang dienkode. Encoding dimaksudkan untuk ringkas dan mudah diuraikan.

Format nilai

Format encoded_array

format encoded_annotation

format annotation_element

Sintaksis string

Ada beberapa jenis item dalam file .dex yang pada akhirnya merujuk ke string. Definisi gaya BNF berikut menunjukkan sintaksis yang dapat diterima untuk string ini.

SimpleName

SimpleName adalah dasar untuk sintaksis nama hal lainnya. Format .dex memungkinkan cukup banyak kebebasan di sini (jauh lebih banyak daripada sebagian besar bahasa sumber umum). Singkatnya, nama sederhana terdiri dari karakter alfabet atau angka ASCII rendah, beberapa simbol ASCII rendah tertentu, dan sebagian besar titik kode non-ASCII yang bukan karakter kontrol, spasi, atau karakter khusus. Mulai dari versi 040, format ini juga mengizinkan karakter spasi (kategori Zs Unicode). Perhatikan bahwa titik kode pengganti (dalam rentang U+d800 … U+dfff) tidak dianggap sebagai karakter nama yang valid, tetapi karakter tambahan Unicode valid (yang direpresentasikan oleh alternatif akhir aturan untuk SimpleNameChar), dan harus direpresentasikan dalam file sebagai pasangan titik kode pengganti dalam encoding MUTF-8.

MemberName

digunakan oleh field_id_item dan method_id_item

MemberName adalah nama anggota class, anggota adalah kolom, metode, dan class dalam.

FullClassName

FullClassName adalah nama class yang sepenuhnya memenuhi syarat, termasuk penentu paket opsional yang diikuti dengan nama yang diperlukan.

TypeDescriptor

Digunakan oleh type_id_item

TypeDescriptor adalah representasi jenis apa pun, termasuk primitif, class, array, dan void. Lihat di bawah untuk mengetahui makna berbagai versi.

ShortyDescriptor

Digunakan oleh proto_id_item

ShortyDescriptor adalah representasi bentuk singkat dari prototipe metode, termasuk jenis nilai yang ditampilkan dan parameter, kecuali bahwa tidak ada perbedaan antara berbagai jenis referensi (class atau array). Sebagai gantinya, semua jenis referensi diwakili oleh satu karakter 'L'.

Semantik TypeDescriptor

Ini adalah arti dari setiap varian TypeDescriptor.

Item dan struktur terkait

Bagian ini mencakup definisi untuk setiap item tingkat atas yang dapat muncul dalam file .dex.

header_item

Muncul di bagian header

Penyelarasan: 4 byte

map_list

Muncul di bagian data

Dirujuk dari header_item

Penyelarasan: 4 byte

Ini adalah daftar seluruh konten file, secara berurutan. Fungsi ini berisi beberapa redundansi sehubungan dengan header_item, tetapi dimaksudkan untuk menjadi bentuk yang mudah digunakan untuk melakukan iterasi di seluruh file. Jenis tertentu harus muncul maksimal sekali dalam peta, tetapi tidak ada batasan jenis urutan yang dapat muncul, selain batasan yang tersirat oleh format lainnya (misalnya, bagian header harus muncul terlebih dahulu, diikuti dengan bagian string_ids, dll.). Selain itu, entri peta harus diurutkan menurut offset awal dan tidak boleh tumpang-tindih.

format map_item

Kode jenis

string_id_item

Muncul di bagian string_ids

Penyelarasan: 4 byte

string_data_item

Muncul di bagian data

Perataan: tidak ada (diselaraskan byte)

type_id_item

Muncul di bagian type_ids

Penyelarasan: 4 byte

proto_id_item

Muncul di bagian proto_ids

Penyelarasan: 4 byte

field_id_item

Muncul di bagian field_ids

Penyelarasan: 4 byte

method_id_item

Muncul di bagian method_ids

Penyelarasan: 4 byte

class_def_item

Muncul di bagian class_defs

Penyelarasan: 4 byte

call_site_id_item

Muncul di bagian call_site_ids

Penyelarasan: 4 byte

call_site_item

Muncul di bagian data

Alignment: none (byte aligned)

call_site_item adalah encoded_array_item yang elemennya sesuai dengan argumen yang diberikan ke metode bootstrap linker. Tiga argumen pertama adalah:

1. Handle metode yang mewakili metode bootstrap linker (VALUE_METHOD_HANDLE).
2. Nama metode yang harus di-resolve oleh linker bootstrap (VALUE_STRING).
3. Jenis metode yang sesuai dengan jenis nama metode yang akan di-resolve (VALUE_METHOD_TYPE).

Setiap argumen tambahan adalah nilai konstan yang diteruskan ke metode bootstrap linker. Argumen ini diteruskan secara berurutan dan tanpa konversi jenis apa pun.

Handle metode yang mewakili metode bootstrap linker harus memiliki jenis nilai yang ditampilkan java.lang.invoke.CallSite. Tiga jenis parameter pertama adalah:

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

Jenis parameter argumen tambahan ditentukan dari nilai konstannya.

method_handle_item

Muncul di bagian method_handles

Penyelarasan: 4 byte

Kode jenis handle metode

class_data_item

Dirujuk dari class_def_item

Muncul di bagian data

Perataan: tidak ada (diselaraskan byte)

Catatan: Semua instance field_id dan method_id elemen harus merujuk ke class penentu yang sama.

format encoded_field

format encoded_method

type_list

Dirujuk dari class_def_item dan proto_id_item

Muncul di bagian data

Penyelarasan: 4 byte

format type_item

code_item

Dirujuk dari encoded_method

Muncul di bagian data

Penyelarasan: 4 byte

format try_item

format encoded_catch_handler_list

format encoded_catch_handler

Format encoded_type_addr_pair

debug_info_item

Dirujuk dari code_item

Muncul di bagian data

Perataan: tidak ada (diselaraskan byte)

Setiap debug_info_item menentukan mesin status berenkode byte yang terinspirasi DWARF3 yang, saat ditafsirkan, memunculkan tabel posisi dan (berpotensi) informasi variabel lokal untuk code_item. Urutan dimulai dengan header panjang variabel (panjangnya bergantung pada jumlah parameter metode), diikuti dengan bytecode mesin status, dan diakhiri dengan byte DBG_END_SEQUENCE.

Mesin status terdiri dari lima register. Register address mewakili offset petunjuk dalam insns_item terkait dalam unit kode 16-bit. Register address dimulai dari 0 di awal setiap urutan debug_info dan hanya boleh meningkat secara monoton. Register line mewakili nomor baris sumber yang harus dikaitkan dengan entri tabel posisi berikutnya yang dikeluarkan oleh mesin status. Ini diinisialisasi di header urutan, dan dapat berubah dalam arah positif atau negatif, tetapi tidak boleh kurang dari 1. Register source_file mewakili file sumber yang dirujuk oleh entri nomor baris. Ini diinisialisasi ke nilai source_file_idx di class_def_item. Dua variabel lainnya, prologue_end dan epilogue_begin, adalah flag boolean (diinisialisasi ke false) yang menunjukkan apakah posisi berikutnya yang ditampilkan harus dianggap sebagai prolog atau epilog metode. Mesin status juga harus melacak nama dan jenis variabel lokal terakhir yang aktif di setiap register untuk kode DBG_RESTART_LOCAL.

Headernya adalah sebagai berikut:

Nilai kode byte adalah sebagai berikut:

Opcode khusus

Opcode dengan nilai antara 0x0a dan 0xff (inklusif) memindahkan register line dan address dengan jumlah kecil, lalu memunculkan entri tabel posisi baru. Rumus untuk inkremen adalah sebagai berikut:

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

Dirujuk dari class_def_item

Muncul di bagian data

Penyelarasan: 4 byte

Catatan: Semua instance field_id dan method_id elemen harus merujuk ke class penentu yang sama.

format field_annotation

format method_annotation

format parameter_annotation

annotation_set_ref_list

Dirujuk dari parameter_annotations_item

Muncul di bagian data

Penyelarasan: 4 byte

format annotation_set_ref_item

annotation_set_item

Dirujuk dari annotations_directory_item, field_annotations_item, method_annotations_item, dan annotation_set_ref_item

Muncul di bagian data

Penyelarasan: 4 byte

format annotation_off_item

annotation_item

Dirujuk dari annotation_set_item

Muncul di bagian data

Perataan: tidak ada (diselaraskan byte)

Nilai visibilitas

Berikut adalah opsi untuk kolom visibility dalam annotation_item:

encoded_array_item

Dirujuk dari class_def_item

Muncul di bagian data

Perataan: tidak ada (diselaraskan byte)

hiddenapi_class_data_item

Bagian ini berisi data tentang antarmuka terbatas yang digunakan oleh setiap class.

Catatan: Fitur API tersembunyi diperkenalkan di Android 10.0 dan hanya berlaku untuk file DEX class di jalur class booting. Daftar flag yang dijelaskan di bawah dapat diperluas dalam rilis Android mendatang. Untuk mengetahui informasi selengkapnya, lihat pembatasan pada antarmuka non-SDK.

Jenis tanda pembatasan:

Anotasi sistem

Anotasi sistem digunakan untuk merepresentasikan berbagai bagian informasi reflektif tentang class (dan metode serta kolom). Informasi ini umumnya hanya diakses secara tidak langsung oleh kode klien (non-sistem).

Anotasi sistem direpresentasikan dalam file .dex sebagai anotasi dengan visibilitas yang ditetapkan ke VISIBILITY_SYSTEM.

dalvik.annotation.AnnotationDefault

Muncul pada metode di antarmuka anotasi

Anotasi AnnotationDefault dilampirkan ke setiap antarmuka anotasi yang ingin menunjukkan binding default.

dalvik.annotation.EnclosingClass

Muncul di kelas

Anotasi EnclosingClass dilampirkan ke setiap class yang ditentukan sebagai anggota class lain, atau anonim, tetapi tidak ditentukan dalam isi metode (misalnya, class dalam sintetis). Setiap class yang memiliki anotasi ini juga harus memiliki anotasi InnerClass. Selain itu, class tidak boleh memiliki anotasi EnclosingClass dan EnclosingMethod.

dalvik.annotation.EnclosingMethod

Muncul di kelas

Anotasi EnclosingMethod dilampirkan ke setiap class yang ditentukan di dalam isi metode. Setiap class yang memiliki anotasi ini juga harus memiliki anotasi InnerClass. Selain itu, class tidak boleh memiliki anotasi EnclosingClass dan EnclosingMethod.

dalvik.annotation.InnerClass

Muncul di kelas

Anotasi InnerClass dilampirkan ke setiap class yang ditentukan dalam cakupan leksik dari definisi class lain. Setiap class yang memiliki anotasi ini juga harus memiliki anotasi EnclosingClass atau anotasi EnclosingMethod.

dalvik.annotation.MemberClasses

Muncul di kelas

Anotasi MemberClasses dilampirkan ke setiap class yang mendeklarasikan class anggota. (Class anggota adalah class dalam langsung yang memiliki nama.)

dalvik.annotation.MethodParameters

Muncul di metode

Catatan: Anotasi ini ditambahkan setelah Android 7.1. Kehadirannya di rilis Android sebelumnya akan diabaikan.

Anotasi MethodParameters bersifat opsional dan dapat digunakan untuk memberikan metadata parameter seperti nama dan pengubah parameter.

Anotasi dapat dihilangkan dari metode atau konstruktor dengan aman jika metadata parameter tidak diperlukan saat runtime. java.lang.reflect.Parameter.isNamePresent() dapat digunakan untuk memeriksa apakah metadata ada untuk parameter, dan metode refleksi terkait seperti java.lang.reflect.Parameter.getName() akan kembali ke perilaku default saat runtime jika informasi tidak ada.

Saat menyertakan metadata parameter, compiler harus menyertakan informasi untuk class yang dihasilkan seperti enum, karena metadata parameter menyertakan apakah parameter bersifat sintetis atau diwajibkan.

Anotasi MethodParameters hanya menjelaskan parameter metode individual. Oleh karena itu, compiler dapat menghapus anotasi sepenuhnya untuk konstruktor dan metode yang tidak memiliki parameter, demi ukuran kode dan efisiensi runtime.

Array yang didokumentasikan di bawah harus berukuran sama dengan struktur dex method_id_item yang terkait dengan metode. Jika tidak, java.lang.reflect.MalformedParametersException akan ditampilkan saat runtime.

Artinya: method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size harus sama dengan names().length dan accessFlags().length.

Karena MethodParameters menjelaskan semua parameter metode formal, bahkan yang tidak dideklarasikan secara eksplisit atau implisit dalam kode sumber, ukuran array dapat berbeda dari informasi Signature atau metadata lainnya yang hanya didasarkan pada parameter eksplisit yang dideklarasikan dalam kode sumber. MethodParameters juga tidak akan menyertakan informasi apa pun tentang parameter penerima anotasi jenis yang tidak ada dalam tanda tangan metode yang sebenarnya.

dalvik.annotation.Signature

Muncul di class, kolom, dan metode

Anotasi Signature dilampirkan ke setiap class, kolom, atau metode yang ditentukan dalam hal jenis yang lebih rumit daripada yang dapat direpresentasikan oleh type_id_item. Format .dex tidak menentukan format untuk tanda tangan; format ini hanya dimaksudkan agar dapat merepresentasikan tanda tangan apa pun yang diperlukan bahasa sumber untuk keberhasilan penerapan semantik bahasa tersebut. Dengan demikian, tanda tangan umumnya tidak diuraikan (atau diverifikasi) oleh implementasi virtual machine. Tanda tangan hanya akan diteruskan ke API dan alat level yang lebih tinggi (seperti debugger). Oleh karena itu, setiap penggunaan tanda tangan harus ditulis agar tidak membuat asumsi apa pun tentang hanya menerima tanda tangan yang valid, yang secara eksplisit menjaga dirinya dari kemungkinan menemukan tanda tangan yang tidak valid secara sintaksis.

Karena string tanda tangan cenderung memiliki banyak konten duplikat, anotasi Signature ditentukan sebagai array string, dengan elemen duplikat secara alami merujuk ke data dasar yang sama, dan tanda tangan dianggap sebagai penyambungan semua string dalam array. Tidak ada aturan tentang cara memisahkan tanda tangan menjadi string terpisah; hal ini sepenuhnya bergantung pada alat yang membuat file .dex.

dalvik.annotation.Throws

Muncul di metode

Anotasi Throws dilampirkan ke setiap metode yang dideklarasikan untuk menampilkan satu atau beberapa jenis pengecualian.