עבודה עם רשימות של סמלים

כדי לצמצם את שטח הפנים של הסמלים והסוגים שצריך לשמור על יציבותם, לליבת 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 או לא צוין ערך, רשימת הסמלים מקבצת סמלים על סמך המודולים של הליבה שמפנים לסמל. אחרת, רשימת הסמלים היא רשימה ממוינת של סמלים שכל המודולים של הליבה משתמשים בהם.

לדוגמה, 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.

צריך להגדיר את המודולים האלה כלא חתומים, אחרת רשימת הסמלים עשויה להיות ריקה. כדי לעשות זאת, מוסיפים את השורה הבאה לקטעי התצורה של הליבה:

# 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

שולחים תיקון עם השינוי ברשימת הסמלים ל-Gerrit של Android Common Kernel כדי שהסמלים החדשים יהיו חלק מ-KMI.

הודעת ה-commit צריכה לכלול רשימה של הסמלים שנוספו או הוסרו. אפשר לכתוב את הרשימה הזו באופן ידני לעדכון של רשימת סמלים קטנה, או להשתמש בדוח $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 לעדכון.

אחרי העדכון של רשימת הסמלים של המכשירים, צריך לשקף את השינויים האלה גם ב-build של 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.