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

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

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

בניית הליבה והייצוג שלה ב-ABI

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

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, אפשר להשתמש באפשרות --destdir:

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

ניתוח ההבדלים ב-ABI בין ה-build לבין ייצוג של הפניה

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

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

הדוח המודפס מגיע מארטיפקט הבנייה שנמצא במיקום $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 מעורבות (שמוגדר בהן base_kernel) שעוברות קומפילציה ישירות עם ליבת GKI צריכות להוסיף תמיכה במעקב אחר רשימת הסמלים של המכשיר. מומלץ לעדכן את הגדרת ה-ABI באמצעות ה-GKI build.

אפשר גם לעיין במסמכי העזר של Kleaf: תמיכה במעקב אחר ABI (מכשיר).

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

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

‫Android מגרסה 14 ומגרסה 15

ההוראות דומות ברובן לאלה של 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, ההוראות זהות לאלה של 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 (ראו בניית ליבת המערכת וארטיפקטים של ABI).

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

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