הפעלת מעקב אחר ABI

בדף הזה מוסבר איך ליצור ייצוגים של ABI של ליבה של Android ולהפעיל מעקב אחרי ABI. התכונה הזו רלוונטית למכשירי Android מגרסה 16 ואילך. לגרסאות ישנות יותר, אפשר לעיין במאמר ABI monitor previous kernel versions.

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

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

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

tools/bazel run //common:kernel_aarch64_abi_dist

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

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

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

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

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

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

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

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

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

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

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

tools/bazel run //common:kernel_aarch64_abi_update

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

מעקב אחר ABI וטירגוט לפי מכשיר

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

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

מעקב ABI בגרסאות ליבה קודמות (Android 15 וגרסאות קודמות)

לגרסאות הליבה הקודמות, ההוראות לבניית ABI ולמעקב שונות, כפי שמפורט בהמשך.

Android 15 ו-14

ההוראות דומות בעיקר לאלה של Android 16, מלבד ש-ABI של ההפניה הוא common/android/abi_gki_aarch64.stg ו-$DIST_DIR מוגדר כברירת מחדל כ-out_abi/kernel_aarch64/dist.

Android 13

אפשר ליצור את Android 13 באמצעות Kleaf או באמצעות סקריפטים קודמים ל-build.

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

בהוראות ל-build scripts מדור קודם, ההוראות זהות לאלה של Android 12.

Android מגרסה 12 ומטה

הפורמט של ABI הוא XML והייצוג של ABI העזר הוא common/android/abi_gki_aarch64.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 (ראו יצירת גרסאות build של ליבה ו-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.