تشغيل ميزة "مراقبة واجهة التطبيق الثنائية"

توضّح هذه الصفحة كيفية إنشاء تمثيلات لواجهة ABI لنواة Android وتنفيذ عملية مراقبة لواجهة ABI. تنطبق هذه الميزة على الإصدار 16 من نظام التشغيل Android والإصدارات الأحدث. بالنسبة إلى الإصدارات الأقل، يُرجى الرجوع إلى إصدارات النواة السابقة في أداة مراقبة توافق التطبيقات مع واجهة ABI.

يمكنك أيضًا الاطّلاع على المستندات المرجعية الخاصة بـ Kleaf: دعم رصد واجهة التطبيق الثنائية (ABI) (نواة GKI) و دعم رصد واجهة التطبيق الثنائية (ABI) (الأجهزة).

إنشاء النواة وتمثيل واجهة التطبيق الثنائية (ABI)

بعد تنزيل مصادر GKI، نفِّذ الأمر التالي لإنشاء نواة GKI وعناصر ABI:

tools/bazel run //common:kernel_aarch64_abi_dist

ينشئ هذا الأمر تمثيلاً لواجهة التطبيق الثنائية (ABI) الحالية وينسخه إلى $DIST_DIR/abi.stg مع النواة والوحدات النمطية التي تم إنشاؤها. تكون القيمة التلقائية لـ $DIST_DIR هي out_abi/kernel_aarch64_abi_dist/dist.

يمكنك تحديد وسيطات إضافية لأدوات ABI في نهاية الأمر بعد --. على سبيل المثال، لتغيير وجهة ABI وإنشاء عناصر، يمكنك استخدام الخيار --destdir:

tools/bazel run //common:kernel_aarch64_abi_dist -- --destdir=out/dist

تحليل الاختلافات في واجهة التطبيق الثنائية (ABI) بين الإصدار وتمثيل مرجعي

يحلّل هدف //common:kernel_aarch64_abi_dist، الذي يتم تنفيذه في الأمر السابق، أي اختلافات في واجهة التطبيق الثنائية (ABI) تم العثور عليها بين الإصدار وتمثيل المرجع المتوفّر في common/gki/aarch64/abi.stg (المحدّد في BUILD.bazel)، ويبلغ عنها. ويتم عرض هذه الاختلافات في نهاية عملية الإنشاء، كما هو موضّح في المثال التالي:

INFO: From [stg] Comparing Kernel ABI @//common:kernel_aarch64_abi_diff:
INFO: ABI DIFFERENCES HAVE BEEN DETECTED!

يأتي التقرير المطبوع من عنصر البناء الذي يقع في $DIST_DIR/abi_stgdiff/abi.report.short بالإضافة إلى التقارير بتنسيقات أخرى.

يجب أن تستخدم عملية التشغيل الآلي رمز الخروج الخاص بأمر الإنشاء، والذي يكون قيمة غير صفرية في حال العثور على اختلافات.

يُرجى العِلم أنّ فروع مرحلة التطوير، بما في ذلك android-mainline، لا تتضمّن تمثيلاً مرجعيًا لواجهة التطبيق الثنائية (ABI). وبدونه، لن يرصد //common:kernel_aarch64_abi_dist أي اختلافات.

تعديل تمثيل ABI المرجعي

يجب أن ينعكس أي تغيير يؤثر في واجهة ABI للنواة، مثل تعديل قائمة الرموز، في تمثيل واجهة ABI المرجعية (common/gki/aarch64/abi.stg، المحدّدة في BUILD.bazel). لإجراء ذلك، عليك تنفيذ الأمر التالي:

tools/bazel run //common:kernel_aarch64_abi_update

ينفّذ هذا الأمر كل ما ورد في الخطوة تحليل اختلافات واجهة التطبيق الثنائية (ABI)، بالإضافة إلى تعديل التمثيل المرجعي في المصادر. يمكن بعد ذلك تحميل واجهة ABI المعدَّلة في عملية الإرسال نفسها التي تم فيها إجراء التغيير. أدرِج اختلافات ABI من التقرير في $DIST_DIR/abi_stgdiff/abi.report.short في رسالة الالتزام.

مراقبة واجهة التطبيق الثنائية (ABI) واستهداف الأجهزة

يجب إعداد ميزة تتبُّع واجهة التطبيق الثنائية (ABI) فقط لاستهدافات إنشاء النواة الأساسية. إنّ إعدادات الإصدار المختلطة (التي تحدّد base_kernel) التي يتم تجميعها مباشرةً باستخدام نواة GKI تحتاج فقط إلى إضافة دعم لتتبُّع قائمة رموز الأجهزة. يجب تعديل تعريف واجهة التطبيق الثنائية (ABI) باستخدام إصدار GKI.

يمكنك أيضًا الاطّلاع على المستندات المرجعية الخاصة بـ Kleaf: دعم رصد واجهة التطبيق الثنائية (ABI).

مراقبة إصدارات النواة السابقة لواجهة التطبيق الثنائية (ABI) (الإصدار 15 من نظام التشغيل Android والإصدارات الأقدم)

تختلف تعليمات إنشاء ومراقبة واجهة ABI في إصدارات النواة السابقة على النحو التالي.

‫Android 15 و14

تتشابه التعليمات إلى حد كبير مع تعليمات Android 16، باستثناء أنّ التمثيل المرجعي لواجهة التطبيق الثنائية (ABI) هو common/android/abi_gki_aarch64.stg و$DIST_DIR ويتم ضبطه تلقائيًا على out_abi/kernel_aarch64/dist.

Android 13

يمكن إنشاء إصدار Android 13 باستخدام Kleaf أو باستخدام نصوص برمجية قديمة للإنشاء.

بالنسبة إلى Kleaf، تكون التعليمات هي نفسها التعليمات الخاصة بنظام التشغيل Android 14، باستثناء أنّ تنسيق ABI هو XML وتمثيل ABI المرجعي هو common/android/abi_gki_aarch64.xml.

بالنسبة إلى نصوص البرامج القديمة، تكون التعليمات هي نفسها في Android 12.

الإصدار 12 من نظام التشغيل Android والإصدارات الأقدم

تنسيق ABI هو XML، وتمثيل ABI المرجعي هو common/android/abi_gki_aarch64.xml

تستخدم هذه النواة build.sh بدلاً من Kleaf. بالنسبة إلى مراقبة واجهة التطبيق الثنائية (ABI)، عليك استخدام build_abi.sh، الذي يقبل متغيرات البيئة نفسها لتخصيص الإصدار مثل build.sh. على سبيل المثال:

BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh

يؤدي ذلك إلى إنشاء النواة واستخراج تمثيل واجهة التطبيق الثنائية (ABI) إلى الدليل الفرعي OUT_DIR (وهو out_abi تلقائيًا)، وهو ما يعادل هدف //common:kernel_aarch64_abi_dist في Kleaf (راجِع إنشاء عناصر النواة وواجهة التطبيق الثنائية).

يتم تخزين تمثيل ABI المرجعي في android/abi_gki_aarch64.xml كما هو محدّد بواسطة المتغيّر ABI_DEFINITION في common/build.config.gki.aarch64.

إذا كنت بحاجة إلى تعديل تمثيل ABI للنواة، فإنّ أسهل طريقة هي استخدام الخيارَين --update و--print-report:

BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh --update --print-report

تعرض الأداة --print-report الاختلافات في واجهة التطبيق الثنائية (ABI) بين الملف كما هو موجود وواجهة ABI تم إنشاؤها حديثًا.

يؤدي الخيار --update إلى الكتابة فوق تمثيل ABI المرجعي. ويتم أيضًا إجراء تعديل قائمة الرموز عند استخدام BUILD_CONFIG لجهاز تم ضبط KMI_SYMBOL_LIST عليه.