التعامل مع قوائم الرموز

لتقليل مساحة الرموز والأنواع التي يجب الحفاظ على ثباتها، توفّر نواة GKI إمكانات للحد من الرموز التي يتم تصديرها إلى الرموز التي تحتاج إليها الوحدات فقط. بالنسبة إلى الوحدات المجمّعة خارجيًا، ستحتاج إلى قائمة بالرموز المستخدَمة للسماح بتصديرها بواسطة نواة GKI. على سبيل المثال، يتم تخزين الرموز المستخدَمة من قِبل الوحدات في Cuttlefish في android/abi_gki_aarch64_virtual_device.

إضافة هدف لإنشاء قائمة الرموز

يتم إنشاء قوائم الرموز بواسطة استهداف kernel_abi. أضِف هذا الاستهداف إلى الجهاز BUILD.bazel باستخدام الخيارات التالية:

• name

  يجب أن يكون بالتنسيق <kernel_build>_abi.

• kernel_build

  يجب أن يحتوي على اسم الجهاز المستهدَف kernel_build.

يمكنك أيضًا استخدام الخيارات التالية:

• kernel_modules

  قائمة بالاستهدافات للوحدات خارج الشجرة يجب عدم تضمين الوحدات المدمجة في الشجرة هنا. راجِع القسم إعداد الوحدات داخل الأشجار لاستخراج الرموز.

• kmi_symbol_list_add_only

  يمنع هذا الخيار إزالة الرموز غير المستخدَمة. يُسمح بإزالة الرموز فقط في أوقات محدَّدة أثناء تثبيت مقياس KMI، ولا يُسمح بذلك بعد تجميد مؤشر KMI.

  ويُفيد ذلك أيضًا عند استخدام قائمة الرموز نفسها مع أجهزة مختلفة متعددة. بهذه الطريقة، لن تزيل الرموز التي يستخدمها الجهاز "أ" وليس الجهاز "ب".

• module_grouping

  إذا كان الرمز True أو غير محدّد، تعمل قائمة الرموز على تجميع الرموز استنادًا إلى وحدات kernel التي تشير إلى الرمز. بخلاف ذلك، تكون قائمة الرموز قائمة مرتّبة للرموز المستخدَمة من قِبل جميع وحدات kernel.

راجِع ملف common-modules/virtual-device/BUILD.bazel مثلاً:

kernel_abi(
    name = "virtual_device_aarch64_abi",
    kernel_build = ":virtual_device_aarch64",
    kernel_modules = [
        ":virtual_device_aarch64_external_modules",
    ],
    kmi_symbol_list_add_only = True,
)

اطّلِع أيضًا على المستندات المرجعية حول استهداف kernel_abi في Kleaf.

تحضير الوحدات داخل الشجرة لاستخراج الرموز

لإعداد الوحدات داخل الشجرة لاستخراج الرموز، يجب إدراج الوحدات داخل الشجرة الخاصة بالمورّد في سمة module_outs لاستهداف kernel_build. يمكنك الاطّلاع على _VIRT_COMMON_MODULES وطريقة استخدامه كمثال. لا تُدرِج وحدات GKI في هذه القائمة.

اضبط هذه الوحدات لتكون غير موقَّعة، وإلا قد تكون قائمة الرموز فارغة. لإجراء ذلك، أضِف هذا السطر إلى أجزاء ملف تكوين kernel:

# CONFIG_MODULE_SIG_ALL is not set

يمكنك الاطّلاع على common-modules/virtual-device/virtual_device_core.fragment على سبيل المثال.

إضافة قائمة رموز الجهاز إلى إصدار نواة الجهاز

أضِف السمة kmi_symbol_list إلى الاستهداف kernel_build المحدّد في الجهاز BUILD.bazel. ويجب أن يكون اسم قائمة الرموز بالتنسيق //common:android/abi_gki_<arch>_<device>. راجِع common-modules/virtual-device/BUILD.bazel، على سبيل المثال:

kernel_build(
    name = "virtual_device_aarch64",
    base_kernel = "//common:kernel_aarch64",
    kmi_symbol_list = "//common:android/abi_gki_aarch64_virtual_device",
    ...
    module_outs = _VIRT_COMMON_MODULES + _VIRT_AARCH64_MODULES,
)

إنشاء قائمة رموز أولية وإرسالها

أنشئ قائمة رموز فارغة في common/android/abi_gki_<arch>_<device>. بالنسبة للمثال أعلاه سيكون الأمر:

touch common/android/abi_gki_aarch64_virtual_device

أضِف هذا الملف إلى additional_kmi_symbol_lists من إصدار نواة GKI الأساسية. على سبيل المثال، تتم إضافة //common:android/abi_gki_aarch64_virtual_device إلى مجموعة الملفات aarch64_additional_kmi_symbol_lists، التي تمّ الإعلان عنها في common/BUILD.bazel.

عدِّل قائمة رموز الجهاز لملء قائمة الرموز الجديدة ونقلها إلى مستودع Android Common Kernel.

تعديل قائمة رموز الأجهزة

يجب تضمين جميع رموز النواة الأساسية المستخدَمة من قِبل الوحدات في module_outs من kernel_build و kernel_modules من kernel_abi في قائمة الرموز. ويمكن إجراء ذلك من خلال تنفيذ استهداف kernel_abi باستخدام اللاحقة _update_symbol_list. على سبيل المثال، يعدِّل الأمر التالي قائمة الرموز لـ //common-modules/virtual-device:virtual_device_aarch64:

tools/bazel run //common-modules/virtual-device:virtual_device_aarch64_abi_update_symbol_list

إرسال تعديل قائمة الرموز إلى ACK

أرسِل تصحيحًا يتضمّن تغيير قائمة الرموز إلى Android Common Kernel gerrit لجعل الرموز الجديدة جزءًا من KMI.

يجب أن تتضمّن رسالة الإضافة أو التعديل قائمة بالرموز المُضافة أو المُزالة. يمكنك كتابة هذه القائمة يدويًا لتعديل قائمة الرموز الصغيرة أو استخدام تقرير$DIST_DIR/abi.report.short بعد تعديل تمثيل ABI المرجعي.

على الرغم من أنّه ليس من الضروري تعديل تمثيل ABI المرجعي قبل إرسال تعديل قائمة الرموز، قد يؤدي ذلك إلى إزالة خطوات إضافية قبل الإرسال وجعل التغيير جاهزًا للإرسال بشكل أسرع. وفي جميع الأحوال، يتم التحقّق من هذه السمة وتعديلها إذا لزم الأمر أثناء عملية التقديم المُسبَق.

الإصدارات القديمة (Android 12 والإصدارات الأقدم)

يمكنك استخدام أداة build_abi.sh على النحو التالي:

BUILD_CONFIG=path/to/build.config.device build/build_abi.sh --update-symbol-list

في هذا المثال، يجب أن تتضمّن build.config.device خيارات الضبط التالية:

• vmlinux

  يجب أن تكون جزءًا من قائمة FILES. ويمكن تنفيذ ذلك من خلال تضمين build.config.aarch64.

• KMI_SYMBOL_LIST

  يجب ضبطه والإشارة إلى قائمة رموز KMI لتحديثها.

بعد تعديل قائمة رموز الأجهزة، عليك أيضًا تطبيق هذه التغييرات في إصدار GKI (common/build.config.gki.aarch64):

• انسخ قائمة الرموز المعدّلة إلى common/android/abi_gki_aarch64_<device>.

• تأكَّد من تضمين android/abi_gki_aarch64_<device> في ADDITIONAL_KMI_SYMBOL_LISTS في common/build.config.gki.aarch64.

• أرسِل تعديل قائمة الرموز إلى ACK.