فرمت اجرایی دالویک

با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

این سند طرح و محتویات فایل‌های .dex را توصیف می‌کند که برای نگهداری مجموعه‌ای از تعاریف کلاس و داده‌های کمکی مرتبط با آنها استفاده می‌شوند.

راهنمای انواع

LEB128

LEB128 (" L ittle- Endian B ase 128 ") یک رمزگذاری با طول متغیر برای مقادیر عدد صحیح با امضا یا بدون علامت دلخواه است. فرمت از مشخصات DWARF3 به عاریت گرفته شده است. در یک فایل .dex ، LEB128 فقط برای رمزگذاری مقادیر 32 بیتی استفاده می شود.

هر مقدار رمزگذاری شده LEB128 از یک تا پنج بایت تشکیل شده است که با هم یک مقدار 32 بیتی واحد را نشان می دهد. هر بایت دارای مهم ترین مجموعه بیت خود به جز بایت نهایی در دنباله است که مهم ترین بیت خود را روشن می کند. هفت بیت باقیمانده از هر بایت محموله است، با کمترین هفت بیت از مقدار در بایت اول، هفت بیت بعدی در بایت دوم و غیره. در مورد یک LEB128 امضا شده ( sleb128 )، مهم‌ترین بیت بار از بایت نهایی در دنباله به منظور تولید مقدار نهایی با علامت تمدید می‌شود. در حالت بدون علامت ( uleb128 )، هر بیتی که صریحاً نشان داده نشده باشد، به عنوان 0 تفسیر می شود.

نوع uleb128p1 برای نشان دادن یک مقدار علامت‌دار استفاده می‌شود، جایی که نمایش مقدار به اضافه یک به‌عنوان uleb128 کدگذاری شده است. این باعث می‌شود رمزگذاری -1 (که به‌عنوان مقدار بدون علامت 0xffffffff در نظر گرفته می‌شود) - اما هیچ عدد منفی دیگری - یک بایت واحد نیست، و دقیقاً در مواردی مفید است که عدد ارائه‌شده باید غیر منفی یا -1 (یا 0xffffffff ) باشد، و در جایی که مقادیر منفی دیگری مجاز نیستند (یا جایی که مقادیر بزرگ بدون علامت لازم است).

در اینجا چند نمونه از فرمت ها آورده شده است:

طرح بندی فایل

قالب کانتینر

نسخه 41 فرمت کانتینری جدیدی را برای داده های DEX با هدف صرفه جویی در فضا معرفی می کند. این فرمت کانتینری اجازه می دهد تا چندین فایل DEX منطقی در یک فایل فیزیکی واحد ترکیب شوند. فرمت جدید عمدتاً فقط الحاق ساده فایل ها در قالب قبلی است، با برخی تفاوت ها:

• file_size اندازه فایل منطقی است، نه فایل فیزیکی. می توان از آن برای تکرار روی تمام فایل های منطقی موجود در کانتینر استفاده کرد.
• فایل های منطقی dex ممکن است به هر داده بعدی در ظرف (اما نه قبل از آن) اشاره کنند. این به فایل‌های dex اجازه می‌دهد تا داده‌هایی مانند رشته‌ها را بین خود به اشتراک بگذارند.
• همه افست ها نسبت به فایل فیزیکی هستند. هیچ افست نسبت به هدر نیست. این تضمین می کند که بخش هایی با افست می توانند بین فایل های منطقی به اشتراک گذاشته شوند.
• هدر دو فیلد جدید برای توصیف محدوده های ظرف اضافه می کند. این یک بررسی سازگاری اضافی است و انتقال کد به قالب جدید را آسان‌تر می‌کند.
• data_size و data_off اکنون استفاده نشده است. داده ها می توانند در چندین فایل منطقی پخش شوند و لازم نیست به هم پیوسته باشند.

بیت فیلد، رشته و تعاریف ثابت

DEX_FILE_MAGIC

در header_item تعبیه شده است

آرایه/رشته ثابت DEX_FILE_MAGIC لیست بایت هایی است که باید در ابتدای یک فایل .dex ظاهر شود تا بتوان آن را به عنوان آن تشخیص داد. این مقدار عمداً حاوی یک خط جدید ( "\n" یا 0x0a ) و یک بایت تهی ( "\0" یا 0x00 ) است تا به شناسایی اشکال خاصی از فساد کمک کند. این مقدار همچنین یک شماره نسخه قالب را به صورت سه رقم اعشاری رمزگذاری می‌کند، که انتظار می‌رود در طول زمان و با تکامل قالب به طور یکنواخت افزایش یابد.

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

توجه: پشتیبانی از نسخه 040 فرمت در نسخه Android 10.0 اضافه شد که مجموعه کاراکترهای مجاز را در SimpleNames گسترش داد.

توجه: پشتیبانی از فرمت 039 در نسخه اندروید 9.0 اضافه شد که دو بایت کد جدید const-method-handle و const-method-type معرفی کرد. (اینها هر کدام در جدول خلاصه مجموعه بایت کد توضیح داده شده اند.) در اندروید 10، نسخه 039 فرمت فایل DEX را به گونه ای گسترش می دهد که اطلاعات API مخفی را شامل شود که فقط برای فایل های DEX در مسیر کلاس بوت قابل استفاده است.

توجه: پشتیبانی از فرمت 038 در نسخه اندروید 8.0 اضافه شده است. نسخه 038 کدهای بایت جدیدی ( invoke-polymorphic و invoke-custom ) و داده ها را برای دسته های متد اضافه کرد.

توجه: پشتیبانی از فرمت 037 در نسخه اندروید 7.0 اضافه شده است. قبل از نسخه 037 اکثر نسخه های اندروید از نسخه 035 فرمت استفاده می کردند. تنها تفاوت بین نسخه های 035 و 037 اضافه کردن روش های پیش فرض و تنظیم invoke است.

توجه: حداقل چند نسخه قبلی این قالب در نسخه‌های نرم‌افزاری عمومی در دسترس استفاده شده است. برای مثال، نسخه 009 برای نسخه های M3 پلتفرم اندروید (نوامبر تا دسامبر 2007) و نسخه 013 برای نسخه های M5 پلتفرم اندروید (فوریه تا مارس 2008) استفاده شد. از چند جهت، این نسخه‌های قبلی فرمت به طور قابل توجهی با نسخه توصیف‌شده در این سند متفاوت است.

ENDIAN_CONSTANT و REVERSE_ENDIAN_CONSTANT

در header_item تعبیه شده است

ثابت ENDIAN_CONSTANT برای نشان دادن endianness فایلی که در آن یافت می شود استفاده می شود. اگرچه فرمت استاندارد .dex بسیار کم است، اما ممکن است پیاده سازی ها مبادله بایت را انتخاب کنند. اگر پیاده‌سازی به سرآیندی برخورد کند که endian_tag آن به جای ENDIAN_CONSTANT REVERSE_ENDIAN_CONSTANT باشد، متوجه می‌شود که فایل از فرم مورد انتظار بایت تعویض شده است.

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

NO_INDEX

در class_def_item و debug_info_item تعبیه شده است

ثابت NO_INDEX برای نشان دادن عدم وجود مقدار شاخص استفاده می شود.

توجه: این مقدار 0 تعریف نشده است، زیرا در واقع یک شاخص معتبر است.

مقدار انتخاب شده برای NO_INDEX به صورت یک بایت در کدگذاری uleb128p1 قابل نمایش است.

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

تعاریف access_flags

تعبیه شده در class_def_item، encoded_field، encoded_method و InnerClass

فیلدهای بیتی این پرچم ها برای نشان دادن قابلیت دسترسی و ویژگی های کلی کلاس ها و اعضای کلاس استفاده می شوند.

* فقط برای حاشیه نویسی های InnerClass مجاز است و هرگز نباید در یک class_def_item روشن باشد.

رمزگذاری UTF-8 اصلاح شده

به عنوان امتیازی برای پشتیبانی آسان تر قدیمی، فرمت .dex داده های رشته ای خود را در یک فرم استاندارد تغییر یافته UTF-8 که از این به بعد MUTF-8 نامیده می شود، رمزگذاری می کند. این فرم با استاندارد UTF-8 یکسان است، به جز:

• فقط از کدهای یک، دو و سه بایتی استفاده می شود.
• نقاط کد در محدوده U+10000 … U+10ffff به عنوان یک جفت جایگزین رمزگذاری می‌شوند که هر کدام به صورت یک مقدار رمزگذاری شده سه بایتی نمایش داده می‌شوند.
• نقطه کد U+0000 به صورت دو بایتی کدگذاری شده است.
• یک بایت تهی ساده (مقدار 0 ) پایان یک رشته را نشان می دهد، همانطور که تفسیر زبان استاندارد C است.

دو مورد اول در بالا را می توان به این صورت خلاصه کرد: MUTF-8 یک فرمت رمزگذاری برای UTF-16 است، به جای اینکه یک فرمت رمزگذاری مستقیم تر برای کاراکترهای یونیکد باشد.

دو مورد آخر بالا به طور همزمان امکان گنجاندن نقطه کد U+0000 را در یک رشته و همچنان آن را به عنوان یک رشته تهی به سبک C دستکاری می کنند.

با این حال، رمزگذاری ویژه U+0000 به این معنی است که بر خلاف UTF-8 معمولی، نتیجه فراخوانی تابع استاندارد C strcmp() روی یک جفت رشته MUTF-8 همیشه نشان دهنده نتیجه امضا شده مناسب از مقایسه رشته های نابرابر نیست. هنگامی که مرتب سازی (نه فقط برابری) یک نگرانی است، ساده ترین راه برای مقایسه رشته های MUTF-8 رمزگشایی آنها کاراکتر به کاراکتر و مقایسه مقادیر رمزگشایی شده است. (با این حال، پیاده سازی های هوشمندانه تری نیز امکان پذیر است.)

لطفاً برای اطلاعات بیشتر در مورد رمزگذاری کاراکتر به استاندارد یونیکد مراجعه کنید. MUTF-8 در واقع به رمزگذاری (نسبتا کمتر شناخته شده) CESU-8 نزدیکتر از UTF-8 فی نفسه است.

رمزگذاری encoded_value

در annotation_element و encoded_array_item تعبیه شده است

encoded_value قطعه ای رمزگذاری شده از داده های (تقریباً) دلخواه با ساختار سلسله مراتبی است. رمزگذاری قرار است هم فشرده و هم ساده برای تجزیه باشد.

فرمت های ارزش

فرمت encoded_array

فرمت encoded_annotation

فرمت annotation_element

نحو رشته

انواع مختلفی از آیتم در یک فایل .dex وجود دارد که در نهایت به یک رشته اشاره دارد. تعاریف زیر به سبک BNF بیانگر نحو قابل قبول برای این رشته ها است.

SimpleName

یک SimpleName مبنایی برای نحو نام چیزهای دیگر است. قالب .dex در اینجا اجازه می دهد تا عرض جغرافیایی مناسبی داشته باشید (بسیار بیشتر از اکثر زبان های مبدأ رایج). به طور خلاصه، یک نام ساده شامل هر کاراکتر یا رقم الفبایی کم ASCII، چند نماد خاص با ASCII پایین، و اکثر نقاط کد غیر ASCII است که کنترل، فاصله یا کاراکترهای خاص نیستند. با شروع از نسخه 040 فرمت علاوه بر این به کاراکترهای فاصله (دسته یونیکد Zs ) اجازه می دهد. توجه داشته باشید که نقاط کد جایگزین (در محدوده U+d800 … U+dfff ) به خودی خود کاراکترهای نام معتبر در نظر گرفته نمی‌شوند، اما نویسه‌های تکمیلی یونیکد معتبر هستند (که با جایگزین نهایی قانون برای SimpleNameChar نشان داده می‌شوند)، و باید در یک فایل به‌عنوان جفت نقاط کد جایگزین8 در MUTF- نمایش داده شوند.

نام عضو

توسط field_id_item و method_id_item استفاده می شود

MemberName نام یکی از اعضای یک کلاس است که اعضای آن فیلدها، متدها و کلاس های داخلی هستند.

FullClassName

FullClassName یک نام کلاس کاملاً واجد شرایط است، شامل یک مشخص کننده بسته اختیاری و به دنبال آن یک نام ضروری است.

TypeDescriptor

مورد استفاده توسط type_id_item

TypeDescriptor نمایش هر نوع از جمله اولیه، کلاس ها، آرایه ها و void است. برای معنی نسخه های مختلف به زیر مراجعه کنید.

ShortyDescriptor

استفاده شده توسط proto_id_item

ShortyDescriptor نمایش فرم کوتاه نمونه اولیه متد، شامل انواع برگشتی و پارامتر است، با این تفاوت که بین انواع مرجع (کلاس یا آرایه) تفاوتی وجود ندارد. در عوض، همه انواع مرجع با یک کاراکتر 'L' نشان داده می شوند.

معناشناسی TypeDescriptor

این معنای هر یک از انواع TypeDescriptor است.

اقلام و ساختارهای مرتبط

این بخش شامل تعاریفی برای هر یک از موارد سطح بالایی است که ممکن است در یک فایل .dex ظاهر شوند.

header_item

در قسمت هدر ظاهر می شود

تراز: 4 بایت

map_list

در بخش داده ظاهر می شود

از header_item ارجاع شده است

تراز: 4 بایت

این لیستی از کل محتویات یک فایل به ترتیب است. این شامل مقداری افزونگی با توجه به header_item است، اما در نظر گرفته شده است که فرمی آسان برای استفاده برای تکرار در کل فایل باشد. یک نوع معین باید حداکثر یک بار در نقشه ظاهر شود، اما هیچ محدودیتی برای اینکه انواع ترتیب ممکن است در آن ظاهر شوند وجود ندارد، به غیر از محدودیت‌هایی که در بقیه قالب‌ها وجود دارد (مثلاً یک بخش header باید ابتدا ظاهر شود، سپس یک بخش string_ids و غیره). علاوه بر این، ورودی های نقشه باید بر اساس افست اولیه مرتب شوند و نباید با هم تداخل داشته باشند.

قالب نقشه_آیتم

کدها را تایپ کنید

string_id_item

در بخش string_ids ظاهر می شود

تراز: 4 بایت

string_data_item

در بخش داده ظاهر می شود

تراز: هیچ (تراز بایت)

type_id_item

در قسمت type_ids ظاهر می شود

تراز: 4 بایت

proto_id_item

در بخش proto_ids ظاهر می شود

تراز: 4 بایت

field_id_item

در قسمت field_ids ظاهر می شود

تراز: 4 بایت

method_id_item

در قسمت method_ids ظاهر می شود

تراز: 4 بایت

class_def_item

در بخش class_defs ظاهر می شود

تراز: 4 بایت

call_site_id_item

در بخش call_site_ids ظاهر می شود

تراز: 4 بایت

call_site_item

در بخش داده ظاهر می شود

تراز: هیچ (بایت تراز)

call_site_item یک encoded_array_item است که عناصر آن با آرگومان های ارائه شده به یک روش پیوند دهنده بوت استرپ مطابقت دارد. سه استدلال اول عبارتند از:

1. دسته روش که نشان دهنده روش پیوند دهنده بوت استرپ (Value_Method_Handle) است.
2. یک نام متد که پیوند دهنده بوت استرپ باید حل کند (Value_String).
3. یک نوع متد متناسب با نوع نام روش حل شده (Value_Method_Type).

هرگونه آرگومان اضافی مقادیر ثابت است که به روش پیوند Bootstrap منتقل می شوند. این استدلال ها به ترتیب و بدون هیچ نوع تبدیل منتقل می شوند.

دسته روش که نشان دهنده روش اتصال دهنده bootstrap است باید دارای نوع برگشتی java.lang.invoke.CallSite باشد. سه نوع پارامتر اول عبارتند از:

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

انواع پارامتر هر آرگومان اضافی از مقادیر ثابت آنها تعیین می شود.

method_handle_item

در بخش Method_Handles ظاهر می شود

تراز: 4 بایت

کدهای نوع دسته روش

class_data_item

ارجاع شده از class_def_item

در بخش داده ظاهر می شود

تراز: هیچکدام (بایت هماهنگ)

توجه: همه موارد field_id و method_id همه عناصر باید به همان کلاس تعریف کننده مراجعه کنند.

قالب ended_field

قالب ended_method

لیست_ه

ارجاع شده از class_def_item و proto_id_item

در بخش داده ظاهر می شود

تراز: 4 بایت

قالب_تیم

code_item

ارجاع شده از encoded_method

در بخش داده ظاهر می شود

تراز: 4 بایت

قالب try_item

قالب ended_catch_handler_list

قالب ended_catch_handler

قالب ended_type_addr_pair

debug_info_item

از code_item ارجاع شده است

در بخش داده ظاهر می شود

تراز: هیچکدام (بایت هماهنگ)

هر debug_info_item یک دستگاه حالت کدگذاری شده با کادوی با الهام از DWARF3 را تعریف می کند که در صورت تفسیر ، جدول موقعیت ها و (به طور بالقوه) اطلاعات متغیر محلی را برای یک code_item منتشر می کند. دنباله با یک هدر با طول متغیر شروع می شود (طول آن به تعداد پارامترهای روش بستگی دارد) ، توسط دستگاه های دستگاه BYTECODES دنبال می شود و با یک بایت DBG_END_SEQUENCE به پایان می رسد.

دستگاه دولتی از پنج ثبت نام تشکیل شده است. ثبت address نشان دهنده جبران دستورالعمل در insns_item مرتبط در واحدهای کد 16 بیتی است. ثبت address در ابتدای هر دنباله debug_info از 0 شروع می شود و فقط باید یکنواخت افزایش یابد. ثبت line نشان دهنده آنچه شماره خط منبع باید با ورودی جدول موقعیت های بعدی ساطع شده توسط دستگاه دولتی همراه باشد. این در هدر دنباله آغاز می شود و ممکن است در جهت های مثبت یا منفی تغییر کند اما هرگز نباید کمتر از 1 باشد. رجیستری source_file فایل منبع را نشان می دهد که ورودی های شماره خط به آن مراجعه می کنند. این به مقدار source_file_idx در class_def_item اولیه می شود. دو متغیر دیگر ، prologue_end و epilogue_begin ، پرچم های بولی هستند (به صورت false ) که نشان می دهد موقعیت بعدی ساطع شده باید یک روش پیشرو یا اپیولوژ در نظر گرفته شود. دستگاه دولتی همچنین باید نام و نوع آخرین متغیر محلی را در هر ثبت برای کد DBG_RESTART_LOCAL ردیابی کند.

هدر به شرح زیر است:

مقادیر کد بایت به شرح زیر است:

کد های خاص

Opcodes با مقادیر بین 0x0a و 0xff (فراگیر) هر دو line و address را با مقدار کمی منتقل می کنند و سپس یک جدول موقعیت جدید را منتشر می کنند. فرمول افزایش به شرح زیر است:

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

ارجاع شده از class_def_item

در بخش داده ظاهر می شود

تراز: 4 بایت

توجه: همه موارد field_id و method_id همه عناصر باید به همان کلاس تعریف کننده مراجعه کنند.

FIELD_ANNOTATION

قالب_نوتینگ

فرمت پارامتر_نوتیک

Annotation_Set_Ref_List

ارجاع شده از parameter_annotations_item

در بخش داده ظاهر می شود

تراز: 4 بایت

Annotation_set_ref_item فرمت

Annotation_set_item

ارجاع شده از Annotations_directory_item ، field_annotations_item ، method_annotations_item ، و حاشیه نویسی_Set_Ref_Item

در بخش داده ظاهر می شود

تراز: 4 بایت

Annotation_Off_Item

حاشیه نویسی_ITEM

ارجاع شده از Annotation_set_item

در بخش داده ظاهر می شود

تراز: هیچکدام (بایت هماهنگ)

مقادیر دید

این گزینه ها برای قسمت visibility در annotation_item است:

ended_array_item

ارجاع شده از class_def_item

در بخش داده ظاهر می شود

تراز: هیچکدام (بایت هماهنگ)

hiddenapi_class_data_item

این بخش شامل داده هایی در مورد رابط های محدود شده توسط هر کلاس است.

توجه: ویژگی API پنهان در Android 10.0 معرفی شده است و فقط برای پرونده های DEX کلاس در مسیر کلاس بوت کاربرد دارد. لیست پرچم های شرح داده شده در زیر ممکن است در نسخه های آینده اندروید گسترش یابد. برای اطلاعات بیشتر ، به محدودیت های رابط های غیر SDK مراجعه کنید.

انواع پرچم محدودیت:

حاشیه نویسی سیستم

حاشیه نویسی سیستم برای نشان دادن قطعات مختلف اطلاعات بازتابی در مورد کلاس ها (و روش ها و زمینه ها) استفاده می شود. این اطلاعات به طور کلی فقط به طور غیرمستقیم توسط کد مشتری (غیر سیستم) قابل دسترسی است.

حاشیه نویسی سیستم در پرونده های .dex به عنوان حاشیه نویسی با دیدنی در VISIBILITY_SYSTEM نشان داده شده است.

dalvik.annotation.annotationDefault

در روشهای رابط حاشیه نویسی ظاهر می شود

حاشیه نویسی AnnotationDefault به هر رابط حاشیه نویسی پیوست شده است که مایل به نشان دادن اتصالات پیش فرض است.

dalvik.annotation.enclosingclass

در کلاس ها ظاهر می شود

حاشیه نویسی EnclosingClass به هر کلاس متصل می شود که یا به عنوان عضو کلاس دیگری ، به خودی خود تعریف می شود ، یا ناشناس است اما در یک بدنه روش تعریف نشده است (به عنوان مثال ، یک کلاس داخلی مصنوعی). هر کلاس که این حاشیه نویسی را داشته باشد نیز باید حاشیه نویسی InnerClass داشته باشد. علاوه بر این ، یک کلاس نباید هم دارای یک EnclosingClass و هم حاشیه EnclosingMethod باشد.

dalvik.annotation.enclosingmethod

در کلاس ها ظاهر می شود

حاشیه نویسی EnclosingMethod به هر کلاس وصل شده است که در داخل یک بدنه روش تعریف شده است. هر کلاس که این حاشیه نویسی را داشته باشد نیز باید حاشیه نویسی InnerClass داشته باشد. علاوه بر این ، یک کلاس نباید هم دارای یک EnclosingClass و هم حاشیه EnclosingMethod باشد.

dalvik.annotation.innerclass

در کلاس ها ظاهر می شود

حاشیه نویسی InnerClass به هر کلاس متصل می شود که در دامنه واژگانی تعریف کلاس دیگر تعریف شده است. هر کلاس که این حاشیه نویسی را داشته باشد نیز باید دارای حاشیه نویسی EnclosingClass یا حاشیه نویسی EnclosingMethod باشد.

dalvik.annotation.MemberClasses

در کلاس ها ظاهر می شود

حاشیه نویسی MemberClasses به هر کلاس متصل می شود که کلاس های عضو را اعلام می کند. (کلاس عضو یک کلاس داخلی مستقیم است که نام دارد.)

dalvik.annotation.methodparameters

در روش ها ظاهر می شود

توجه: این حاشیه نویسی پس از Android 7.1 اضافه شد. حضور آن در نسخه های قبلی اندرویدی نادیده گرفته می شود.

حاشیه نویسی MethodParameters اختیاری است و می تواند برای ارائه ابرداده پارامتر مانند نام پارامترها و اصلاح کننده ها استفاده شود.

هنگامی که ابرداده پارامتر در زمان اجرا لازم نیست ، حاشیه نویسی را می توان با خیال راحت از یک روش یا سازنده حذف کرد. java.lang.reflect.Parameter.isNamePresent() می تواند برای بررسی اینکه آیا ابرداده برای یک پارامتر وجود دارد ، استفاده شود و روش های بازتاب مرتبط مانند java.lang.reflect.Parameter.getName() اگر اطلاعات موجود نباشد به رفتار پیش فرض در زمان اجرا باز می گردد.

در صورت شامل ابرداده پارامتر ، کامپایلرها باید اطلاعاتی را برای کلاسهای تولید شده مانند عناصر شامل شوند ، زیرا ابرداده پارامتر شامل این است که آیا یک پارامتر مصنوعی یا اجباری است یا خیر.

حاشیه نویسی MethodParameters فقط پارامترهای روش فردی را توصیف می کند. بنابراین ، کامپایلرها ممکن است حاشیه نویسی را کاملاً برای سازندگان و روشهایی که هیچ پارامتری ندارند ، به دلیل اندازه کد و راندمان زمان اجرا حذف کنند.

آرایه های مستند شده در زیر باید به همان اندازه برای ساختار method_id_item DEX مرتبط با روش باشد ، در غیر این صورت یک java.lang.reflect.MalformedParametersException در زمان اجرا پرتاب می شود.

یعنی: method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size باید همان names().length و accessFlags().length .

از آنجا که MethodParameters تمام پارامترهای روش رسمی را توصیف می کند ، حتی آنهایی که به طور صریح یا ضمنی در کد منبع اعلام نشده اند ، اندازه آرایه ها ممکن است با امضای یا سایر اطلاعات ابرداده متفاوت باشد که فقط بر روی پارامترهای صریح اعلام شده در کد منبع استوار است. MethodParameters همچنین هیچ اطلاعاتی در مورد پارامترهای گیرنده حاشیه نویسی نوع که در امضای روش واقعی وجود ندارند ، شامل نمی شود.

dalvik.annotation.Signature

در کلاس ها ، زمینه ها و روش ها ظاهر می شود

حاشیه نویسی Signature به هر کلاس ، فیلد یا روشی که از نظر نوع پیچیده تری تعریف شده است از آنچه توسط یک type_id_item قابل نمایش است ، ضمیمه شده است. قالب .dex فرمت امضاها را تعریف نمی کند. این صرفاً به معنای این است که بتوانیم هرگونه امضایی را که یک زبان منبع برای اجرای موفقیت آمیز معناشناسی آن زبان نیاز دارد ، نشان دهد. به این ترتیب ، امضاها به طور کلی توسط پیاده سازی دستگاه های مجازی تجزیه نمی شوند (یا تأیید می شوند). امضاها به سادگی به API ها و ابزارهای سطح بالاتر (مانند اشکال زدایی) واگذار می شوند. بنابراین ، هرگونه استفاده از امضای باید نوشته شود تا هیچ فرضیه ای در مورد فقط دریافت امضاهای معتبر انجام ندهد ، و صریحاً خود را در برابر احتمال ورود به امضای غیرقانونی به صورت غیرقانونی محافظت می کند.

از آنجا که رشته های امضای تمایل به محتوای تکثیر زیادی دارند ، حاشیه نویسی Signature به عنوان مجموعه ای از رشته ها تعریف می شود ، جایی که عناصر تکراری به طور طبیعی به همان داده های اساسی اشاره می کنند و امضای آن برای هماهنگی همه رشته های موجود در آرایه است. هیچ قانونی در مورد چگونگی جدا کردن یک امضا به رشته های جداگانه وجود ندارد. این کاملاً مربوط به ابزارهایی است که پرونده های .dex را تولید می کنند.

dalvik.annotation.throws

در روش ها ظاهر می شود

حاشیه نویسی Throws به هر روش متصل می شود که اعلام می شود یک یا چند نوع استثنا را پرتاب می کند.

این سند طرح و محتوای پرونده های .dex را که برای نگه داشتن مجموعه ای از تعاریف کلاس و داده های کمکی مرتبط با آنها استفاده می شود ، توصیف می کند.

راهنمای انواع

LEB128

LEB128 (" l ittle- e ndian b ase 128 ") یک رمزگذاری طول متغیر برای مقادیر عدد صحیح امضا شده خودسرانه یا بدون امضا است. این قالب از مشخصات DWARF3 وام گرفته شد. در یک پرونده .dex ، LEB128 فقط برای رمزگذاری مقادیر 32 بیتی استفاده می شود.

هر مقدار رمزگذاری شده LEB128 از یک تا پنج بایت تشکیل شده است که در کنار هم یک مقدار 32 بیتی واحد را نشان می دهد. هر بایت دارای مهمترین مجموعه بیت خود است به جز بایت نهایی در دنباله ، که مهمترین آن را واضح ترین دارد. هفت بیت باقیمانده از هر بایت بار ، با حداقل هفت بیت قابل توجه در مقدار در بایت اول ، هفت بعدی در بایت دوم و غیره. در مورد یک LEB128 امضا شده ( sleb128 ) ، مهمترین بار بارگذاری بایت نهایی در دنباله برای تولید مقدار نهایی امضا شده است. در مورد بدون امضا ( uleb128 ) ، هر بیتی که به صراحت نشان داده نمی شود به عنوان 0 تعبیر می شود.

از نوع uleb128p1 برای نشان دادن یک مقدار امضا شده استفاده می شود ، جایی که بازنمایی از مقدار به علاوه یک رمزگذاری شده به عنوان uleb128 است. این باعث می شود رمزگذاری -1 (در عوض به عنوان مقدار بدون امضا 0xffffffff ) -اما هیچ عدد منفی دیگر -یک بایت واحد -و دقیقاً در مواردی که شماره نماینده باید غیر منفی باشد یا -1 (یا 0xffffffff ) مفید باشد ، و در جایی که مقادیر منفی دیگری مجاز نیست (یا در مواردی که مقادیر بزرگ غیرمجاز باشد) مفید است.

در اینجا چند نمونه از قالب ها آورده شده است:

طرح بندی فایل

قالب کانتینر

Version 41 introduces a new container format for DEX data with the goal to save space. This container format allows several logical DEX files to be combined into a single physical file. The new format is mostly just naive concatenation of files in the previous format, with some differences:

• The file_size is the size of the logical file, not the physical file. It can be used to iterate over all the logical files in the container.
• Logical dex files may reference any later data in the container (but not earlier). This allows dex files to share data, such as strings, between them.
• All offsets are relative to the physical file. No offset is relative to the header. This is ensures that sections with offsets can be shared between logical files.
• The header adds two new fields to describe the bounds of the container. This is an additional consistency check and makes porting code to the new format easier.
• The data_size and data_off are now unused. Data can be spread across multiple logical files and does not have to be contiguous.

Bitfield, string, and constant definitions

DEX_FILE_MAGIC

Embedded in header_item

The constant array/string DEX_FILE_MAGIC is the list of bytes that must appear at the beginning of a .dex file in order for it to be recognized as such. The value intentionally contains a newline ( "\n" or 0x0a ) and a null byte ( "\0" or 0x00 ) in order to help in the detection of certain forms of corruption. The value also encodes a format version number as three decimal digits, which is expected to increase monotonically over time as the format evolves.

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

Note: Support for version 040 of the format was added in the Android 10.0 release, which extended the set of allowed characters in SimpleNames .

Note: Support for version 039 of the format was added in the Android 9.0 release, which introduced two new bytecodes, const-method-handle and const-method-type . (These are each described in the Summary of bytecode set table.) In Android 10, version 039 extends the DEX file format to include hidden API information that's only applicable to DEX files on the boot class path.

Note: Support for version 038 of the format was added in the Android 8.0 release. Version 038 added new bytecodes ( invoke-polymorphic and invoke-custom ) and data for method handles.

Note: Support for version 037 of the format was added in the Android 7.0 release. Prior to version 037 most versions of Android have used version 035 of the format. The only difference between versions 035 and 037 is the addition of default methods and the adjustment of the invoke .

Note: At least a couple earlier versions of the format have been used in widely available public software releases. For example, version 009 was used for the M3 releases of the Android platform (November–December 2007), and version 013 was used for the M5 releases of the Android platform (February–March 2008). In several respects, these earlier versions of the format differ significantly from the version described in this document.

ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT

Embedded in header_item

The constant ENDIAN_CONSTANT is used to indicate the endianness of the file in which it is found. Although the standard .dex format is little-endian, implementations may choose to perform byte-swapping. Should an implementation come across a header whose endian_tag is REVERSE_ENDIAN_CONSTANT instead of ENDIAN_CONSTANT , it would know that the file has been byte-swapped from the expected form.

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

NO_INDEX

Embedded in class_def_item and debug_info_item

The constant NO_INDEX is used to indicate that an index value is absent.

Note: This value isn't defined to be 0 , because that is in fact typically a valid index.

The chosen value for NO_INDEX is representable as a single byte in the uleb128p1 encoding.

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

access_flags definitions

Embedded in class_def_item, encoded_field, encoded_method, and InnerClass

Bitfields of these flags are used to indicate the accessibility and overall properties of classes and class members.

* Only allowed on for InnerClass annotations, and must not ever be on in a class_def_item .

Modified UTF-8 encoding

As a concession to easier legacy support, the .dex format encodes its string data in a de facto standard modified UTF-8 form, hereafter referred to as MUTF-8. This form is identical to standard UTF-8, except:

• Only the one-, two-, and three-byte encodings are used.
• Code points in the range U+10000 … U+10ffff are encoded as a surrogate pair, each of which is represented as a three-byte encoded value.
• The code point U+0000 is encoded in two-byte form.
• A plain null byte (value 0 ) indicates the end of a string, as is the standard C language interpretation.

The first two items above can be summarized as: MUTF-8 is an encoding format for UTF-16, instead of being a more direct encoding format for Unicode characters.

The final two items above make it simultaneously possible to include the code point U+0000 in a string and still manipulate it as a C-style null-terminated string.

However, the special encoding of U+0000 means that, unlike normal UTF-8, the result of calling the standard C function strcmp() on a pair of MUTF-8 strings does not always indicate the properly signed result of comparison of unequal strings. When ordering (not just equality) is a concern, the most straightforward way to compare MUTF-8 strings is to decode them character by character, and compare the decoded values. (However, more clever implementations are also possible.)

Please refer to The Unicode Standard for further information about character encoding. MUTF-8 is actually closer to the (relatively less well-known) encoding CESU-8 than to UTF-8 per se.

encoded_value encoding

Embedded in annotation_element and encoded_array_item

An encoded_value is an encoded piece of (nearly) arbitrary hierarchically structured data. The encoding is meant to be both compact and straightforward to parse.

Value formats

encoded_array format

encoded_annotation format

annotation_element format

String syntax

There are several kinds of item in a .dex file which ultimately refer to a string. The following BNF-style definitions indicate the acceptable syntax for these strings.

SimpleName

A SimpleName is the basis for the syntax of the names of other things. The .dex format allows a fair amount of latitude here (much more than most common source languages). In brief, a simple name consists of any low-ASCII alphabetic character or digit, a few specific low-ASCII symbols, and most non-ASCII code points that are not control, space, or special characters. Starting from version 040 the format additionally allows space characters (Unicode Zs category). Note that surrogate code points (in the range U+d800 … U+dfff ) are not considered valid name characters, per se, but Unicode supplemental characters are valid (which are represented by the final alternative of the rule for SimpleNameChar ), and they should be represented in a file as pairs of surrogate code points in the MUTF-8 encoding.

MemberName

used by field_id_item and method_id_item

A MemberName is the name of a member of a class, members being fields, methods, and inner classes.

FullClassName

A FullClassName is a fully qualified class name, including an optional package specifier followed by a required name.

TypeDescriptor

Used by type_id_item

A TypeDescriptor is the representation of any type, including primitives, classes, arrays, and void . See below for the meaning of the various versions.

ShortyDescriptor

Used by proto_id_item

A ShortyDescriptor is the short form representation of a method prototype, including return and parameter types, except that there is no distinction between various reference (class or array) types. Instead, all reference types are represented by a single 'L' character.

TypeDescriptor semantics

This is the meaning of each of the variants of TypeDescriptor .

Items and related structures

This section includes definitions for each of the top-level items that may appear in a .dex file.

header_item

Appears in the header section

Alignment: 4 bytes

map_list

Appears in the data section

Referenced from header_item

Alignment: 4 bytes

This is a list of the entire contents of a file, in order. It contains some redundancy with respect to the header_item but is intended to be an easy form to use to iterate over an entire file. A given type must appear at most once in a map, but there is no restriction on what order types may appear in, other than the restrictions implied by the rest of the format (eg, a header section must appear first, followed by a string_ids section, etc.). Additionally, the map entries must be ordered by initial offset and must not overlap.

map_item format

Type codes

string_id_item

Appears in the string_ids section

Alignment: 4 bytes

string_data_item

Appears in the data section

Alignment: none (byte-aligned)

type_id_item

Appears in the type_ids section

Alignment: 4 bytes

proto_id_item

Appears in the proto_ids section

Alignment: 4 bytes

field_id_item

Appears in the field_ids section

Alignment: 4 bytes

method_id_item

Appears in the method_ids section

Alignment: 4 bytes

class_def_item

Appears in the class_defs section

Alignment: 4 bytes

call_site_id_item

Appears in the call_site_ids section

Alignment: 4 bytes

call_site_item

Appears in the data section

Alignment: none (byte aligned)

The call_site_item is an encoded_array_item whose elements correspond to the arguments provided to a bootstrap linker method. The first three arguments are:

1. A method handle representing the bootstrap linker method (VALUE_METHOD_HANDLE).
2. A method name that the bootstrap linker should resolve (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 and method_id instances 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 and method_id instances 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.

This document describes the layout and contents of .dex files, which are used to hold a set of class definitions and their associated adjunct data.

Guide to types

LEB128

LEB128 (" L ittle- E ndian B ase 128 ") is a variable-length encoding for arbitrary signed or unsigned integer quantities. The format was borrowed from the DWARF3 specification. In a .dex file, LEB128 is only ever used to encode 32-bit quantities.

Each LEB128 encoded value consists of one to five bytes, which together represent a single 32-bit value. Each byte has its most significant bit set except for the final byte in the sequence, which has its most significant bit clear. The remaining seven bits of each byte are payload, with the least significant seven bits of the quantity in the first byte, the next seven in the second byte and so on. In the case of a signed LEB128 ( sleb128 ), the most significant payload bit of the final byte in the sequence is sign-extended to produce the final value. In the unsigned case ( uleb128 ), any bits not explicitly represented are interpreted as 0 .

The variant uleb128p1 is used to represent a signed value, where the representation is of the value plus one encoded as a uleb128 . This makes the encoding of -1 (alternatively thought of as the unsigned value 0xffffffff ) — but no other negative number — a single byte, and is useful in exactly those cases where the represented number must either be non-negative or -1 (or 0xffffffff ), and where no other negative values are allowed (or where large unsigned values are unlikely to be needed).

Here are some examples of the formats:

طرح بندی فایل

قالب کانتینر

Version 41 introduces a new container format for DEX data with the goal to save space. This container format allows several logical DEX files to be combined into a single physical file. The new format is mostly just naive concatenation of files in the previous format, with some differences:

• The file_size is the size of the logical file, not the physical file. It can be used to iterate over all the logical files in the container.
• Logical dex files may reference any later data in the container (but not earlier). This allows dex files to share data, such as strings, between them.
• All offsets are relative to the physical file. No offset is relative to the header. This is ensures that sections with offsets can be shared between logical files.
• The header adds two new fields to describe the bounds of the container. This is an additional consistency check and makes porting code to the new format easier.
• The data_size and data_off are now unused. Data can be spread across multiple logical files and does not have to be contiguous.

Bitfield, string, and constant definitions

DEX_FILE_MAGIC

Embedded in header_item

The constant array/string DEX_FILE_MAGIC is the list of bytes that must appear at the beginning of a .dex file in order for it to be recognized as such. The value intentionally contains a newline ( "\n" or 0x0a ) and a null byte ( "\0" or 0x00 ) in order to help in the detection of certain forms of corruption. The value also encodes a format version number as three decimal digits, which is expected to increase monotonically over time as the format evolves.

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

Note: Support for version 040 of the format was added in the Android 10.0 release, which extended the set of allowed characters in SimpleNames .

Note: Support for version 039 of the format was added in the Android 9.0 release, which introduced two new bytecodes, const-method-handle and const-method-type . (These are each described in the Summary of bytecode set table.) In Android 10, version 039 extends the DEX file format to include hidden API information that's only applicable to DEX files on the boot class path.

Note: Support for version 038 of the format was added in the Android 8.0 release. Version 038 added new bytecodes ( invoke-polymorphic and invoke-custom ) and data for method handles.

Note: Support for version 037 of the format was added in the Android 7.0 release. Prior to version 037 most versions of Android have used version 035 of the format. The only difference between versions 035 and 037 is the addition of default methods and the adjustment of the invoke .

Note: At least a couple earlier versions of the format have been used in widely available public software releases. For example, version 009 was used for the M3 releases of the Android platform (November–December 2007), and version 013 was used for the M5 releases of the Android platform (February–March 2008). In several respects, these earlier versions of the format differ significantly from the version described in this document.

ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT

Embedded in header_item

The constant ENDIAN_CONSTANT is used to indicate the endianness of the file in which it is found. Although the standard .dex format is little-endian, implementations may choose to perform byte-swapping. Should an implementation come across a header whose endian_tag is REVERSE_ENDIAN_CONSTANT instead of ENDIAN_CONSTANT , it would know that the file has been byte-swapped from the expected form.

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

NO_INDEX

Embedded in class_def_item and debug_info_item

The constant NO_INDEX is used to indicate that an index value is absent.

Note: This value isn't defined to be 0 , because that is in fact typically a valid index.

The chosen value for NO_INDEX is representable as a single byte in the uleb128p1 encoding.

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

access_flags definitions

Embedded in class_def_item, encoded_field, encoded_method, and InnerClass

Bitfields of these flags are used to indicate the accessibility and overall properties of classes and class members.

* Only allowed on for InnerClass annotations, and must not ever be on in a class_def_item .

Modified UTF-8 encoding

As a concession to easier legacy support, the .dex format encodes its string data in a de facto standard modified UTF-8 form, hereafter referred to as MUTF-8. This form is identical to standard UTF-8, except:

• Only the one-, two-, and three-byte encodings are used.
• Code points in the range U+10000 … U+10ffff are encoded as a surrogate pair, each of which is represented as a three-byte encoded value.
• The code point U+0000 is encoded in two-byte form.
• A plain null byte (value 0 ) indicates the end of a string, as is the standard C language interpretation.

The first two items above can be summarized as: MUTF-8 is an encoding format for UTF-16, instead of being a more direct encoding format for Unicode characters.

The final two items above make it simultaneously possible to include the code point U+0000 in a string and still manipulate it as a C-style null-terminated string.

However, the special encoding of U+0000 means that, unlike normal UTF-8, the result of calling the standard C function strcmp() on a pair of MUTF-8 strings does not always indicate the properly signed result of comparison of unequal strings. When ordering (not just equality) is a concern, the most straightforward way to compare MUTF-8 strings is to decode them character by character, and compare the decoded values. (However, more clever implementations are also possible.)

Please refer to The Unicode Standard for further information about character encoding. MUTF-8 is actually closer to the (relatively less well-known) encoding CESU-8 than to UTF-8 per se.

encoded_value encoding

Embedded in annotation_element and encoded_array_item

An encoded_value is an encoded piece of (nearly) arbitrary hierarchically structured data. The encoding is meant to be both compact and straightforward to parse.

Value formats

encoded_array format

encoded_annotation format

annotation_element format

String syntax

There are several kinds of item in a .dex file which ultimately refer to a string. The following BNF-style definitions indicate the acceptable syntax for these strings.

SimpleName

A SimpleName is the basis for the syntax of the names of other things. The .dex format allows a fair amount of latitude here (much more than most common source languages). In brief, a simple name consists of any low-ASCII alphabetic character or digit, a few specific low-ASCII symbols, and most non-ASCII code points that are not control, space, or special characters. Starting from version 040 the format additionally allows space characters (Unicode Zs category). Note that surrogate code points (in the range U+d800 … U+dfff ) are not considered valid name characters, per se, but Unicode supplemental characters are valid (which are represented by the final alternative of the rule for SimpleNameChar ), and they should be represented in a file as pairs of surrogate code points in the MUTF-8 encoding.

MemberName

used by field_id_item and method_id_item

A MemberName is the name of a member of a class, members being fields, methods, and inner classes.

FullClassName

A FullClassName is a fully qualified class name, including an optional package specifier followed by a required name.

TypeDescriptor

Used by type_id_item

A TypeDescriptor is the representation of any type, including primitives, classes, arrays, and void . See below for the meaning of the various versions.

ShortyDescriptor

Used by proto_id_item

A ShortyDescriptor is the short form representation of a method prototype, including return and parameter types, except that there is no distinction between various reference (class or array) types. Instead, all reference types are represented by a single 'L' character.

TypeDescriptor semantics

This is the meaning of each of the variants of TypeDescriptor .

Items and related structures

This section includes definitions for each of the top-level items that may appear in a .dex file.

header_item

Appears in the header section

Alignment: 4 bytes

map_list

Appears in the data section

Referenced from header_item

Alignment: 4 bytes

This is a list of the entire contents of a file, in order. It contains some redundancy with respect to the header_item but is intended to be an easy form to use to iterate over an entire file. A given type must appear at most once in a map, but there is no restriction on what order types may appear in, other than the restrictions implied by the rest of the format (eg, a header section must appear first, followed by a string_ids section, etc.). Additionally, the map entries must be ordered by initial offset and must not overlap.

map_item format

Type codes

string_id_item

Appears in the string_ids section

Alignment: 4 bytes

string_data_item

Appears in the data section

Alignment: none (byte-aligned)

type_id_item

Appears in the type_ids section

Alignment: 4 bytes

proto_id_item

Appears in the proto_ids section

Alignment: 4 bytes

field_id_item

Appears in the field_ids section

Alignment: 4 bytes

method_id_item

Appears in the method_ids section

Alignment: 4 bytes

class_def_item

Appears in the class_defs section

Alignment: 4 bytes

call_site_id_item

Appears in the call_site_ids section

Alignment: 4 bytes

call_site_item

Appears in the data section

Alignment: none (byte aligned)

The call_site_item is an encoded_array_item whose elements correspond to the arguments provided to a bootstrap linker method. The first three arguments are:

1. A method handle representing the bootstrap linker method (VALUE_METHOD_HANDLE).
2. A method name that the bootstrap linker should resolve (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 and method_id instances 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 and method_id instances 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.