Format Dalvik yang dapat dieksekusi

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

Panduan untuk mengetik

LEB128

LEB128 ("Little-Endian Base 128") adalah enkode panjang variabel untuk kuantitas bilangan bulat bertanda atau tidak bertanda 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 merepresentasikan satu nilai 32-bit. Setiap byte memiliki bit paling signifikan yang ditetapkan, kecuali byte terakhir dalam urutan, yang memiliki bit paling signifikan yang dihapus. Tujuh bit yang tersisa dari setiap byte adalah payload, dengan tujuh bit paling tidak signifikan dari jumlah dalam byte pertama, tujuh bit berikutnya dalam byte kedua, dan seterusnya. Dalam kasus LEB128 bertanda (sleb128), bit payload paling signifikan dari byte terakhir dalam urutan diperluas tanda untuk menghasilkan nilai akhir. Dalam kasus tanpa tanda (uleb128), bit yang tidak direpresentasikan secara eksplisit akan ditafsirkan sebagai 0.

Varian uleb128p1 digunakan untuk merepresentasikan nilai bertanda, dengan representasi nilai ditambah satu yang dienkode sebagai uleb128. Hal ini membuat encoding -1 (atau dapat juga dianggap sebagai nilai yang tidak bertanda 0xffffffff) — tetapi bukan angka negatif lainnya — menjadi satu byte, dan berguna dalam kasus-kasus ketika angka yang ditampilkan harus berupa non-negatif atau -1 (atau 0xffffffff), dan ketika tidak ada nilai negatif lain yang diizinkan (atau ketika nilai besar yang tidak bertanda 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 berupa penggabungan file dalam format sebelumnya, dengan beberapa perbedaan:

• file_size adalah ukuran file logis, bukan file fisik. Objek ini dapat digunakan untuk melakukan iterasi pada semua file logis dalam penampung.
• File dex logis dapat mereferensikan data apa pun yang lebih baru dalam penampung (tetapi tidak yang lebih lama). Hal ini memungkinkan file dex berbagi data, seperti string, di antara keduanya.
• 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 menjelaskan 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 konstanta DEX_FILE_MAGIC adalah daftar byte yang harus muncul di awal file .dex agar dikenali sebagai file tersebut. Nilai sengaja berisi baris baru ("\n" atau 0x0a) dan byte null ("\0" atau 0x00) untuk membantu mendeteksi bentuk kerusakan tertentu. Nilai ini juga mengenkode nomor versi format sebagai tiga digit desimal, yang diharapkan 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 041 bersifat eksperimental dalam rilis Android 16 untuk menguji format penampung. Namun, versi 041 tidak boleh digunakan untuk kode produksi.

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

Catatan: Dukungan untuk format 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 boot.

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 konstanta tersebut ditemukan. Meskipun format .dex standar adalah little-endian, penerapan dapat memilih untuk melakukan pertukaran byte. Jika implementasi menemukan header yang endian_tag-nya adalah REVERSE_ENDIAN_CONSTANT, bukan ENDIAN_CONSTANT, implementasi tersebut akan mengetahui bahwa file telah ditukar byte-nya 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 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 ada 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. Bentuk ini identik 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 ditampilkan 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 secara bersamaan untuk menyertakan titik kode U+0000 dalam string dan tetap memanipulasinya sebagai string yang dihentikan null gaya 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 string tidak sama yang ditandatangani dengan benar. Jika pengurutan (bukan hanya kesamaan) menjadi masalah, cara paling mudah untuk membandingkan string MUTF-8 adalah dengan mendekodenya karakter demi karakter, dan membandingkan nilai yang telah didekode. (Namun, implementasi yang lebih cerdas juga mungkin dilakukan.)

Lihat Standar Unicode untuk mengetahui informasi selengkapnya tentang encoding karakter. MUTF-8 sebenarnya lebih dekat dengan encoding CESU-8 (yang relatif kurang dikenal) daripada UTF-8 itu sendiri.

Encoding encoded_value

Disematkan dalam annotation_element dan encoded_array_item

encoded_value adalah bagian data terstruktur hierarkis (hampir) arbitrer yang dienkode. Encoding ini dimaksudkan agar ringkas dan mudah diurai.

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 sintaks yang dapat diterima untuk string ini.

SimpleName

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

MemberName

digunakan oleh field_id_item dan method_id_item

MemberName adalah nama anggota class, dengan anggota berupa 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 dari jenis apa pun, termasuk primitif, class, array, dan void. Lihat di bawah untuk mengetahui arti berbagai versi.

ShortyDescriptor

Digunakan oleh proto_id_item

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

Semantik TypeDescriptor

Berikut adalah arti setiap varian TypeDescriptor.

Item dan struktur terkait

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

header_item

Muncul di bagian header

Penyelarasan: 4 byte

map_list

Muncul di bagian data

Direferensikan dari header_item

Penyelarasan: 4 byte

Ini adalah daftar seluruh isi file, secara berurutan. Objek ini berisi beberapa redundansi terkait header_item tetapi dimaksudkan sebagai formulir yang mudah digunakan untuk melakukan iterasi pada seluruh file. Jenis tertentu hanya boleh muncul paling banyak satu kali dalam peta, tetapi tidak ada batasan urutan jenis yang dapat muncul, selain batasan yang tersirat dalam format lainnya (misalnya, bagian header harus muncul terlebih dahulu, diikuti dengan bagian string_ids, dll.). Selain itu, entri peta harus diurutkan berdasarkan 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

Penyelarasan: 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

item_situs_panggilan

Muncul di bagian data

Penyelarasan: tidak ada (diselaraskan byte)

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

1. Handle metode yang merepresentasikan metode linker bootstrap (VALUE_METHOD_HANDLE).
2. Nama metode yang harus diselesaikan oleh linker bootstrap (VALUE_STRING).
3. Jenis metode yang sesuai dengan jenis nama metode yang akan diselesaikan (VALUE_METHOD_TYPE).

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

Tuas metode yang merepresentasikan metode linker bootstrap 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

Penyelarasan: 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

Direferensikan 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

Penyelarasan: tidak ada (diselaraskan byte)

Setiap debug_info_item menentukan mesin status byte-coded yang terinspirasi dari DWARF3 yang, saat ditafsirkan, memancarkan tabel posisi dan (berpotensi) informasi variabel lokal untuk code_item. Urutan dimulai dengan header berpanjang variabel (yang 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 merepresentasikan offset instruksi 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 menunjukkan nomor baris sumber yang harus dikaitkan dengan entri tabel posisi berikutnya yang dikeluarkan oleh mesin status. Nilai ini diinisialisasi di header urutan, dan dapat berubah ke arah positif atau negatif, tetapi tidak boleh kurang dari 1. Register source_file mewakili file sumber yang dirujuk oleh entri nomor baris. Diinisialisasi ke nilai source_file_idx di class_def_item. Dua variabel lainnya, prologue_end dan epilogue_begin, adalah tanda boolean (diinisialisasi ke false) yang menunjukkan apakah posisi berikutnya yang dikeluarkan 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.

Header-nya adalah sebagai berikut:

Nilai kode byte adalah sebagai berikut:

Opcodes khusus

Opcode dengan nilai antara 0x0a dan 0xff (inklusif) memindahkan register line dan address dalam jumlah kecil, lalu memancarkan entri tabel posisi baru. Rumus untuk kenaikan 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

Direferensikan 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

Direferensikan dari annotation_set_item

Muncul di bagian data

Penyelarasan: tidak ada (diselaraskan byte)

Nilai visibilitas

Berikut adalah opsi untuk kolom visibility dalam annotation_item:

encoded_array_item

Direferensikan dari class_def_item

Muncul di bagian data

Penyelarasan: 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 boot. 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 informasi reflektif tentang class (dan metode serta kolom). Informasi ini umumnya hanya diakses secara tidak langsung oleh kode klien (non-sistem).

Anotasi sistem ditampilkan 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 bersifat 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 leksikal definisi class lain. Setiap class yang memiliki anotasi ini juga harus memiliki salah satu 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. Keberadaannya 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 suatu 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 dibuat seperti enum, karena metadata parameter menyertakan apakah parameter bersifat sintetis atau wajib.

Anotasi MethodParameters hanya menjelaskan parameter metode individual. Oleh karena itu, compiler dapat menghilangkan 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.

Yaitu: 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 mungkin 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 sebenarnya.

dalvik.annotation.Signature

Muncul di class, kolom, dan metode

Anotasi Signature dilampirkan ke setiap class, kolom, atau metode yang ditentukan dalam jenis yang lebih rumit daripada yang dapat direpresentasikan oleh type_id_item. Format .dex tidak menentukan format tanda tangan; format ini hanya dimaksudkan untuk dapat merepresentasikan tanda tangan apa pun yang diperlukan bahasa sumber agar berhasil menerapkan semantik bahasa tersebut. Oleh karena itu, tanda tangan umumnya tidak diuraikan (atau diverifikasi) oleh implementasi virtual machine. Tanda tangan hanya diserahkan ke API dan alat tingkat 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, dengan secara eksplisit melindungi dirinya sendiri dari kemungkinan menemukan tanda tangan yang tidak valid secara sintaksis.

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

dalvik.annotation.Throws

Muncul di metode

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