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

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

راجِع أيضًا المستندات المرجعية الخاصة بـ Kleaf: Support ABI monitoring (GKI) و Support ABI monitoring (Device).

إنشاء النواة وتمثيل واجهة التطبيق الثنائية (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 تحتاج فقط إلى إضافة دعم لتتبُّع قائمة رموز الأجهزة. يجب تعديل تعريف واجهة التطبيق الثنائية باستخدام إصدار GKI.

يمكنك أيضًا الاطّلاع على المستندات المرجعية الخاصة بـ Kleaf: Support ABI monitoring (Device).

أداة مراقبة واجهة التطبيق الثنائية (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 وتمثيل واجهة التطبيق الثنائية المرجعية هو 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).

يتم تخزين تمثيل 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) بين الملف كما هو موجود وواجهة تطبيق ثنائية تم إنشاؤها حديثًا.

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