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

כדי לצמצם את שטח הפנים של הסמלים והסוגים שצריך לשמור על יציבותם, לליבת GKI יש יכולות להגביל את הסמלים המיוצאים רק לאלה שנדרשים על ידי מודולים. במודולים שעברו קומפילציה חיצונית, צריך שתהיה רשימה של הסמלים שבשימוש כדי לאפשר לייצא אותם על ידי ליבת GKI. לדוגמה, סמלים שמשמשים מודולים של Cuttlefish מאוחסנים ב-gki/aarch64/symbols/virtual_device.

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

רשימות של סמלים נוצרות על ידי יעד kernel_abi. מוסיפים את יעד ההמרה הזה למכשיר BUILD.bazel עם האפשרויות הבאות:

  • name

    הפורמט הנדרש הוא <kernel_build>_abi.

  • kernel_build

    צריך להכיל את שם יעד המכשיר kernel_build.

אפשר גם להשתמש באפשרויות הבאות:

  • kernel_modules

    רשימה של יעדים למודולים out-of-tree. אין לכלול כאן מודולים בתוך העץ. אפשר לעיין במאמר בנושא הכנת מודולים בתוך העץ לחילוץ סמלים.

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

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

# CONFIG_MODULE_SIG_ALL is not set

לדוגמה, ראו common-modules/virtual-device/virtual_device_core.fragment.

הוספת רשימת סמלים של מכשיר ל-build של ליבת המכשיר

מוסיפים את מאפיין kmi_symbol_list ליעד kernel_build שמוגדר במכשיר BUILD.bazel. שם רשימת הסמלים צריך להיות בפורמט //common:gki/<arch>/symbols/<device>.

לדוגמה, ראו common-modules/virtual-device/BUILD.bazel:

kernel_build(
    name = "virtual_device_aarch64",
    base_kernel = "//common:kernel_aarch64",
    kmi_symbol_list = "//common:gki/aarch64/symbols/virtual_device",
    ...
    module_outs = _VIRT_COMMON_MODULES + _VIRT_AARCH64_MODULES,
)

יצירה ושליחה של רשימת סמלים ראשונית

תצור רשימה ריקה של סמלים בcommon/gki/<arch>/symbols/<device>. בדוגמה שלמעלה, הפקודה תהיה:

touch common/gki/aarch64/symbols/virtual_device

מוסיפים את הקובץ הזה ל-additional_kmi_symbol_lists של גרסת הבסיס של ליבת GKI. לדוגמה, //common:gki/aarch64/symbols/virtual_device נוסף לקבוצת הקבצים aarch64_additional_kmi_symbol_lists, שהוגדרה ב-common/BUILD.bazel.

מעדכנים את רשימת הסמלים של המכשירים כדי למלא את רשימת הסמלים החדשה ושולחים אותה למאגר של ליבת Android הנפוצה.

עדכון רשימת סמלי מכשירים

כל הסמלים של ליבת המערכת שמשמשים מודולים ב-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

כדי שהסמלים החדשים יהיו חלק מ-KMI, צריך לשלוח תיקון עם השינוי ברשימת הסמלים אל הליבה המשותפת של Android ב-Gerrit.

הודעת השמירה צריכה לכלול רשימה של סמלים שנוספו או הוסרו. אפשר לכתוב את הרשימה הזו ידנית כדי לעדכן רשימה קטנה של סמלים, או להשתמש בדוח $DIST_DIR/abi_stgdiff/abi.report.short אחרי עדכון הייצוג של ממשק ה-ABI של ההפניה.

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

עבודה עם רשימות של סמלים (Android 13)

‫Android 13 תומך גם ב-Kleaf וגם בסקריפטים ישנים של build, כך שאפשר לנהל רשימות של סמלים כמו שמתואר בקטעים הקודמים או כמו שמתואר בקטע הבא.

עבודה עם רשימות של סמלים (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):

  • מעתיקים את רשימת הסמלים המעודכנת אל common/android/abi_gki_aarch64_<device>.

  • בודקים ש-android/abi_gki_aarch64_<device> כלול ב-ADDITIONAL_KMI_SYMBOL_LISTS ב-common/build.config.gki.aarch64.

  • שליחת עדכון של רשימת הסמלים ל-ACK.