تفعيل تتبُّع واجهات التطبيق الثنائية (ABI)

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

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

إنشاء النواة وتمثيل واجهة ABI

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

tools/bazel run //common:kernel_aarch64_abi_dist

ينشئ هذا الأمر تمثيل ABI الحالي وينسخه إلى out_abi/kernel_aarch64/dist/abi.stg مع النواة والوحدات المُنشأة.

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

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

تحليل الاختلافات في ABI بين الإصدار وتمثيل مرجعي

يُحلِّل هدف //common:kernel_aarch64_abi_dist، الذي تم تنفيذه في الأمر أعلاه، ويُبلغ عن أي اختلافات في ABI تم العثور عليها بين الإصدار والتمثيل المرجعي الموجود في common/android/abi_gki_aarch64.stg (المحدَّد في BUILD.bazel). ويتم طباعة هذه الاختلافات في نهاية عملية الإنشاء، كما هو موضَّح في المثال التالي:

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

يأتي التقرير المطبوع من عنصر الإنشاء الذي يقع في out_abi/kernel_aarch64/dist/abi_stgdiff/abi.report.short مع التقارير بالتنسيقات الأخرى.

يجب أن تستخدم العملية المبرمَجة رمز الخروج لأمر الإنشاء، والذي لا يساوي صفرًا إذا تم العثور على اختلافات.

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

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

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

​​tools/bazel run //common:kernel_aarch64_abi_update

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

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

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

اطّلِع أيضًا على المستندات المرجعية لواجهة Kleaf: إتاحة مراقبة ABI (الجهاز).

إصدارات النواة القديمة

Android 13

تعليمات التصميم هي نفسها تقريبًا في الإصدار Android 14، باستثناء أنّ تنسيق ABI هو XML ومرجع ABI المرجعي هو common/android/abi_gki_aarch64.xml.

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

كما هو الحال في Android 13، يكون تنسيق ABI هو 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 بين الملف كما هو وملف ABI تم إنشاؤه حديثًا.

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