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

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

اطّلِع أيضًا على المستندات المرجعية لـ 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 وإنشاء العناصر، يمكنك استخدام الخيار --dist_dir:

tools/bazel run //common:kernel_aarch64_abi_dist -- --dist_dir=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 مع التقارير بتنسيقات أخرى.

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

يُرجى العِلم أنّه لا تتوفّر تمثيلات لملف ABI المرجعي في مشاريع مرحلة التطوير، بما في ذلك الإصدار android-mainline. بدون ذلك، لن يرصد //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" إلا لاستهدافات إنشاء النواة الأساسية. بالنسبة إلى ملفّات برمجية مبرمجَة باستخدام إعدادات مختلطة للبناء (تلك التي تحدّد base_kernel) والتي يتم تجميعها مباشرةً باستخدام ملف برمجي لنظام التشغيل GKI، ما عليك سوى إضافة إمكانية تتبُّع قائمة رموزها. يجب تعديل تعريف ABI باستخدام إصدار GKI.

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

مراقبة واجهة ABI لإصدارات kernel السابقة (Android 15 والإصدارات الأقدم)

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

Android 15 و14

تتطابق التعليمات في معظمها مع تعليمات Android 16، باستثناء أنّ تمثيل IDE المرجعي هو 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).

يتم تخزين تمثيل 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 عليه.