הפעלת מעקב אחר 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 בין הגרסה לבין ייצוג של קובץ עזר

היעד //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, שהוא לא אפס אם נמצאו הבדלים.

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

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

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

tools/bazel run //common:kernel_aarch64_abi_update

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

מעקב אחרי ממשק ה-ABI ומכשירי היעד

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

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

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

בגרסאות קודמות של ליבת Linux, ההוראות לבנייה ולמעקב אחר 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 של הליבה, הדרך הכי נוחה לעשות זאת היא באמצעות האפשרויות --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 מוגדר.