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

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

אחרי שמעדכנים את רשימת סמלי המכשירים, צריך לשקף את השינויים האלה גם ב-GKI build (common/build.config.gki.aarch64):