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

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

ראו גם את מאמרי העזרה של Kleaf: תמיכה במעקב ABI (GKI) וגם תמיכה במעקב ABI (מכשיר).

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

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

tools/bazel run //common:kernel_aarch64_abi_dist

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

אפשר לציין ארגומנטים נוספים לכלי 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.sh. לדוגמה:

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

הפעולה הזו יוצרת את הליבה ומחלצת את ייצוג ה-ABI אל OUT_DIR (שהיא out_abi כברירת מחדל) והיא שוות ערך לספריית המשנה יעד אחד (//common:kernel_aarch64_abi_dist) של Kleaf (ראו פיתוח ליבה (kernel) וארטיפקטים של 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.