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

لتقليل مساحة الرموز والأنواع التي يجب الحفاظ على ثباتها، تتوفّر في نواة 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

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

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

  • 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.