تنسيق Dalvik القابل للتنفيذ

يصف هذا المستند تخطيط ومحتويات ملفات .dex ، والتي تُستخدم للاحتفاظ بمجموعة من تعريفات الفئات والبيانات الملحقة المرتبطة بها.

دليل لأنواع

جنيه 128

LEB128 (" L ittle- E ndian B ase 128 ") هو ترميز متغير الطول لكميات أعداد صحيحة عشوائية موقعة أو بدون إشارة. تم استعارة التنسيق من مواصفات DWARF3 . في ملف .dex ، لا يتم استخدام LEB128 إلا لترميز كميات 32 بت.

تتكون كل قيمة مشفرة LEB128 من واحد إلى خمسة بايتات ، والتي تمثل معًا قيمة 32 بت واحدة. يحتوي كل بايت على مجموعة البت الأكثر أهمية باستثناء البايت الأخير في التسلسل ، والذي يتميز بأهم وحدات البت فيه. السبع بتات المتبقية من كل بايت هي حمولة ، مع أقل سبع بتات دلالة من الكمية في البايت الأول ، والسبع التي تليها في البايت الثاني وهكذا. في حالة توقيع LEB128 ( sleb128 ) ، يتم تمديد إشارة بتة الحمولة الأكثر أهمية من البايت الأخير في التسلسل لإنتاج القيمة النهائية. في الحالة غير الموقعة ( uleb128 ) ، يتم تفسير أي بتات غير ممثلة بشكل صريح على أنها 0 .

يستخدم المتغير uleb128p1 لتمثيل قيمة موقعة ، حيث يكون التمثيل للقيمة زائد واحد مشفر كـ uleb128 . هذا يجعل ترميز -1 (يُعتقد بدلاً من ذلك على أنه القيمة غير الموقعة 0xffffffff ) - ولكن لا يوجد رقم سالب آخر - بايت واحد ، ويكون مفيدًا في تلك الحالات بالضبط حيث يجب أن يكون الرقم الممثل إما غير سالب أو -1 (أو 0xffffffff ) ، وحيث لا يُسمح بقيم سالبة أخرى (أو حيث من غير المحتمل أن تكون هناك حاجة إلى قيم كبيرة غير موقعة).

فيما يلي بعض الأمثلة على التنسيقات:

تخطيط الملف

Bitfield ، سلسلة وتعريفات ثابتة

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"

ملاحظة: تمت إضافة دعم الإصدار 039 من التنسيق في إصدار Android 9.0 ، والذي قدم اثنين من الرموز البايت الجديدة ، و const-method-handle و const-method-type . (تم وصف كل من هذه في ملخص جدول مجموعة الرموز الثنائية .) في Android 10 ، يوسع الإصدار 039 تنسيق ملف DEX ليشمل معلومات API المخفية التي تنطبق فقط على ملفات DEX على مسار فئة التمهيد.

ملاحظة: تمت إضافة دعم الإصدار 038 من التنسيق في إصدار Android 8.0. أضاف الإصدار 038 أكواد بايت جديدة ( invoke-polymorphic invoke-custom ) وبيانات لمقابض الطريقة.

ملاحظة: تمت إضافة دعم الإصدار 037 من التنسيق في إصدار Android 7.0. قبل الإصدار 037 ، استخدمت معظم إصدارات Android الإصدار 035 من التنسيق. الاختلاف الوحيد بين الإصدارين 035 و 037 هو إضافة الطرق الافتراضية وضبط invoke .

ملاحظة: تم استخدام نسختين أقدمتين على الأقل من التنسيق في إصدارات البرامج العامة المتاحة على نطاق واسع. على سبيل المثال ، تم استخدام الإصدار 009 لإصدارات M3 لمنصة Android (نوفمبر - ديسمبر 2007) ، وتم استخدام الإصدار 013 لإصدارات M5 من نظام Android الأساسي (فبراير - مارس 2008). من نواحٍ عديدة ، تختلف هذه الإصدارات السابقة من التنسيق بشكل كبير عن الإصدار الموضح في هذا المستند.

ENDIAN_CONSTANT و REVERSE_ENDIAN_CONSTANT

مضمن في header_item

يتم استخدام الثابت ENDIAN_CONSTANT للإشارة إلى نهاية الملف الذي تم العثور عليه فيه. على الرغم من أن تنسيق .dex القياسي ضئيل للغاية ، إلا أن التطبيقات قد تختار إجراء تبديل البايت. إذا ظهر تنفيذ عبر رأس يكون endian_tag هو REVERSE_ENDIAN_CONSTANT بدلاً من 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

يتم استخدام Bitfields من هذه العلامات للإشارة إلى إمكانية الوصول والخصائص العامة للفئات وأعضاء الفصل.

* يُسمح فقط بتشغيل التعليقات التوضيحية لـ InnerClass ، ويجب ألا يتم تشغيله مطلقًا في class_def_item .

ترميز MUTF-8 (معدل UTF-8)

كامتياز لدعم الإرث الأسهل ، يقوم تنسيق .dex بترميز بيانات السلسلة الخاصة به في نموذج UTF-8 القياسي بحكم الواقع ، والمشار إليه فيما بعد باسم MUTF-8. هذا النموذج مطابق لمعيار UTF-8 ، باستثناء:

• يتم استخدام ترميزات أحادية وثنائية وثلاثية البايت فقط.
• نقاط الرمز في النطاق U+10000 … U+10ffff يتم ترميزها كزوج بديل ، يتم تمثيل كل منها كقيمة مشفرة ثلاثية البايت.
• تم ترميز نقطة الرمز U+0000 في شكل ثنائي البايت.
• يشير البايت الفارغ البسيط (القيمة 0 ) إلى نهاية السلسلة ، كما هو الحال في تفسير لغة C القياسي.

يمكن تلخيص أول عنصرين أعلاه على النحو التالي: MUTF-8 هو تنسيق ترميز لـ UTF-16 ، بدلاً من كونه تنسيق ترميز مباشر أكثر لأحرف Unicode.

يتيح العنصران الأخيران أعلاه إمكانية تضمين نقطة الرمز U+0000 في سلسلة في نفس الوقت ومعالجتها كسلسلة منتهية بقيمة خالية من النمط C.

ومع ذلك ، فإن الترميز الخاص لـ U+0000 يعني أنه ، على عكس UTF-8 العادي ، فإن نتيجة استدعاء دالة C القياسية strcmp() على زوج من سلاسل MUTF-8 لا تشير دائمًا إلى النتيجة الموقعة بشكل صحيح لمقارنة السلاسل غير المتكافئة . عندما يكون الترتيب (وليس المساواة فقط) مصدر قلق ، فإن الطريقة الأكثر مباشرة لمقارنة سلاسل MUTF-8 هي فك تشفيرها حرفًا بحرف ، ومقارنة القيم التي تم فك تشفيرها. (ومع ذلك ، من الممكن أيضًا استخدام تطبيقات أكثر ذكاءً).

يرجى الرجوع إلى معيار Unicode للحصول على مزيد من المعلومات حول ترميز الأحرف. يعد MUTF-8 أقرب إلى ترميز CESU-8 (الأقل شهرة نسبيًا) منه إلى UTF-8 في حد ذاته.

encoded_value ترميز

مضمن في annotation_element و encoded_array_item

encoded_value هي قطعة مشفرة من (تقريبًا) بيانات منظمة بشكل هرمي عشوائية. من المفترض أن يكون الترميز مضغوطًا ومباشرًا لتحليله.

تنسيقات القيمة

encoded_array

encoded_annotation تنسيق

anotation_element format

بناء جملة السلسلة

هناك عدة أنواع من العناصر في ملف .dex والتي تشير في النهاية إلى سلسلة. تشير تعريفات نمط BNF التالية إلى الصيغة المقبولة لهذه السلاسل.

SimpleName

إن SimpleName هو الأساس لبناء جملة أسماء الأشياء الأخرى. يسمح تنسيق .dex بقدر معقول من خطوط العرض هنا (أكثر بكثير من معظم لغات المصدر الشائعة). باختصار ، يتكون الاسم البسيط من أي حرف أبجدي أو رقم أبجدي منخفض ASCII ، وعدد قليل من رموز ASCII المنخفضة ، ومعظم نقاط الرموز غير ASCII التي ليست تحكم أو مسافة أو أحرف خاصة. بدءًا من الإصدار 040 ، يسمح التنسيق بالإضافة إلى ذلك بأحرف المسافات (فئة Unicode Zs ). لاحظ أن نقاط الشفرة البديلة (في النطاق U+d800 + d800… U+dfff ) لا تعتبر أحرف اسم صالحة ، في حد ذاتها ، ولكن أحرف Unicode التكميلية صالحة (والتي يتم تمثيلها بواسطة البديل النهائي لقاعدة SimpleNameChar ) ، وهم يجب تمثيلها في ملف كأزواج من نقاط الرمز البديلة في تشفير MUTF-8.

اسم عضو

المستخدمة من قبل field_id_item و method_id_item

اسم العضو هو اسم عضو في الفصل ، والأعضاء عبارة عن حقول وأساليب وفئات داخلية.

FullClassName

FullClassName هو اسم فئة مؤهل بالكامل ، بما في ذلك محدد حزمة اختياري متبوعًا باسم مطلوب.

النوع

المستخدمة من قبل type_id_item

يعد TypeDescriptor تمثيلًا لأي نوع ، بما في ذلك العناصر الأولية والفئات والمصفوفات void . انظر أدناه لمعرفة معنى الإصدارات المختلفة.

ShortyDescriptor

يستخدمه proto_id_item

يعد ShortyDescriptor تمثيلًا قصيرًا للنموذج الأولي للطريقة ، بما في ذلك أنواع الإرجاع والمعلمات ، باستثناء أنه لا يوجد تمييز بين أنواع المراجع المختلفة (فئة أو مصفوفة). بدلاً من ذلك ، يتم تمثيل جميع أنواع المراجع بحرف 'L' واحد.

TypeDescriptor Semantics

هذا هو معنى كل من متغيرات TypeDescriptor .

العناصر والهياكل ذات الصلة

يتضمن هذا القسم تعريفات لكل عنصر من عناصر المستوى الأعلى التي قد تظهر في ملف .dex .

header_item

يظهر في قسم الرأس

المحاذاة: 4 بايت

map_list

يظهر في قسم البيانات

مشار إليه من header_item

المحاذاة: 4 بايت

هذه قائمة بكامل محتويات الملف ، بالترتيب. يحتوي على بعض التكرار فيما يتعلق بـ header_item ولكن الغرض منه أن يكون نموذجًا سهل الاستخدام للتكرار على ملف بأكمله. يجب أن يظهر نوع معين مرة واحدة على الأكثر في الخريطة ، ولكن لا توجد قيود على أنواع الطلبات التي قد تظهر فيها ، بخلاف القيود التي تتضمنها بقية التنسيق (على سبيل المثال ، يجب أن يظهر قسم header أولاً ، متبوعًا بـ string_ids القسم ، وما إلى ذلك). بالإضافة إلى ذلك ، يجب ترتيب إدخالات الخريطة عن طريق الإزاحة الأولية ويجب ألا تتداخل.

تنسيق map_item

اكتب الرموز

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_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. A method type corresponding to the type of the method name to be resolved (VALUE_METHOD_TYPE).

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

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

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

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

method_handle_item

appears in the method_handles section

alignment: 4 bytes

Method Handle Type Codes

class_data_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

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

encoded_field format

encoded_method format

type_list

referenced from class_def_item and proto_id_item

appears in the data section

alignment: 4 bytes

type_item format

code_item

referenced from encoded_method

appears in the data section

alignment: 4 bytes

try_item format

encoded_catch_handler_list format

encoded_catch_handler format

encoded_type_addr_pair format

debug_info_item

referenced from code_item

appears in the data section

alignment: none (byte-aligned)

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

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

The header is as follows:

The byte code values are as follows:

Special opcodes

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

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

adjusted_opcode = opcode - DBG_FIRST_SPECIAL

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

annotations_directory_item

referenced from class_def_item

appears in the data section

alignment: 4 bytes

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

field_annotation format

method_annotation format

parameter_annotation format

annotation_set_ref_list

referenced from parameter_annotations_item

appears in the data section

alignment: 4 bytes

annotation_set_ref_item format

annotation_set_item

referenced from annotations_directory_item, field_annotations_item, method_annotations_item, and annotation_set_ref_item

appears in the data section

alignment: 4 bytes

annotation_off_item format

annotation_item

referenced from annotation_set_item

appears in the data section

alignment: none (byte-aligned)

Visibility values

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

encoded_array_item

referenced from class_def_item

appears in the data section

alignment: none (byte-aligned)

hiddenapi_class_data_item

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

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

Restriction flag types:

System annotations

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

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

dalvik.annotation.AnnotationDefault

appears on methods in annotation interfaces

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

dalvik.annotation.EnclosingClass

appears on classes

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

dalvik.annotation.EnclosingMethod

appears on classes

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

dalvik.annotation.InnerClass

appears on classes

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

dalvik.annotation.MemberClasses

appears on classes

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

dalvik.annotation.MethodParameters

appears on methods

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

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

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

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

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

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

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

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

dalvik.annotation.Signature

appears on classes, fields, and methods

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

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

dalvik.annotation.Throws

appears on methods

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