הפעלה של ניטור ממשק ABI

בדף הזה מוסבר איך ליצור ייצוגים של ABI של ליבה של Android ולהפעיל מעקב אחרי ABI. התכונה הזו רלוונטית למכשירי Android מגרסה 14 ואילך. לגרסאות נמוכות יותר אפשר לעיין בגרסאות ליבה (kernel) ישנות יותר.

מומלץ גם לעיין במסמכי העזרה של Kleaf: Support ABI monitoring (GKI) ו-Support ABI monitoring (Device).

פיתוח הליבה והייצוג שלה ב-ABI

אחרי הורדת מקורות GKI, מריצים את הפקודה הבאה כדי ליצור את הליבה של GKI ואת הארטיפקטים של ABI:

tools/bazel run //common:kernel_aarch64_abi_dist

הפקודה הזו יוצרת את הייצוג הנוכחי של ABI ומעתיקה אותו ל-out_abi/kernel_aarch64/dist/abi.stg יחד עם הליבה והמודולים שנוצרו.

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

tools/bazel run //common:kernel_aarch64_abi_dist -- --dist_dir=out/dist

ניתוח ההבדלים ב-ABI בין ה-build לבין ייצוג העזר

היעד //common:kernel_aarch64_abi_dist, שמופעל בפקודה שלמעלה, מנתח ומדווח על הבדלים ב-ABI שנמצא בין הייצוג של ה-build לבין הייצוג, שנמצא ב-common/android/abi_gki_aarch64.stg (מוגדר ב-BUILD.bazel). ההבדלים האלה מודפסים בסוף ה-build, כפי שמוצג בדוגמה הבאה:

INFO: From [stg] Comparing Kernel ABI @//common:kernel_aarch64_abi_diff:
INFO: ABI DIFFERENCES HAVE BEEN DETECTED!

הדוח המודפס מגיע מ-artifact של ה-build שנמצא ב-out_abi/kernel_aarch64/dist/abi_stgdiff/abi.report.short, יחד עם דוחות בפורמטים אחרים.

האוטומציה צריכה להשתמש בקוד היציאה של פקודת ה-build, שהוא לא אפס אם נמצאו הבדלים.

לתשומת ליבכם: להסתעפויות של שלב הפיתוח, כולל android-mainline, אין ייצוג של ABI להפניה. בלי זה, //common:kernel_aarch64_abi_dist לא יזהה הבדלים.

עדכון הייצוג של ABI של ההפניה

כל שינוי שמשפיע על ה-ABI של הליבה, כמו עדכון של רשימת הסמלים, צריך למצוא ביטוי בייצוג של ה-ABI של ההפניה (common/android/abi_gki_aarch64.stg, שמוגדר בקובץ BUILD.bazel). כדי לעשות זאת, מריצים את הפקודה הבאה:

​​tools/bazel run //common:kernel_aarch64_abi_update

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

טירגוט לממשקי ABI וטירגוט לפי מכשירים

צריך להגדיר את מעקב ה-ABI רק ליעדי build של הליבה. בהגדרות build מעורבות (כאלה שמגדירות את base_kernel) שמתבצעת בהן הידור ישירות עם הליבה של GKI, צריך רק להוסיף תמיכה במעקב אחר רשימת הסמלים של המכשיר. צריך לעדכן את הגדרת ה-ABI באמצעות ה-build של GKI.

אפשר גם לעיין במסמכי העזרה של Kleaf: Support ABI monitoring (Device).

גרסאות ליבה ישנות יותר

Android 13

הוראות ה-build זהות ברובן ל-Android 14, אבל פורמט ה-ABI הוא XML וייצוג ה-ABI של ההפניה הוא common/android/abi_gki_aarch64.xml.

Android מגרסה 13 ומטה

כמו ב-Android 13, פורמט ה-ABI הוא XML.

בליבות ישנות יותר נעשה שימוש ב-build.sh במקום ב-Kleaf. למעקב ABI צריך להשתמש ב-build_abi.sh, שמקבל את אותם משתני סביבה כדי להתאים אישית את ה-build כ-build.sh. לדוגמה:

BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh

הפקודה הזו יוצרת את הליבה ומחלצת את הייצוג של ה-ABI לתיקיית המשנה OUT_DIR (שנקראת out_abi כברירת מחדל). הפקודה הזו זהה ליעד //common:kernel_aarch64_abi_dist של Kleaf (ראו יצירת ליבות ופריטי ABI).

ייצוג ה-ABI של ההפניה מאוחסן ב-android/abi_gki_aarch64.xml כפי שמוגדר על ידי המשתנה ABI_DEFINITION ב-common/build.config.gki.aarch64.

אם צריך לעדכן את הייצוג של ABI בליבה, הדרך הנוחה ביותר היא להשתמש באפשרויות --update ו---print-report:

BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh --update --print-report

הפקודה --print-report מדפיסה את ההבדלים ב-ABI בין הקובץ כפי שהוא קיים לבין ABI שנוצר לאחרונה.

האפשרות --update מחליפה את הייצוג של ABI של קובץ העזר. הוא גם מבצע עדכון של רשימת הסמלים כשמשתמשים ב-BUILD_CONFIG במכשיר שהוגדר בו KMI_SYMBOL_LIST.