אכיפה של ממשקי מחיצות של מוצרים

ב-Android 11, המחיצה product מנותקת מהמחיצות system ו-vendor, כך שהיא עצמאית מהן. במסגרת השינויים האלה, עכשיו אפשר לשלוט בגישה של המחיצה product לממשקים מקומיים ולממשקי Java (בדומה לאופן שבו אכיפת הממשק פועלת במחיצות vendor).

אכיפת ממשקים מקומיים

כדי להפעיל את אכיפת הממשק המקורי, מגדירים את PRODUCT_PRODUCT_VNDK_VERSION לערך current. (הגרסת מוגדרת באופן אוטומטי ל-current כשרמת ה-API של המשלוח ליעד גבוהה מ-29). אכיפה מאפשרת:

  • מודולים מקומיים במחיצה product לקישור:
    • באופן סטטי או דינמי למודול אחרים במחיצה product שכוללים ספריות סטטיות, ספריות משותפות או ספריות כותרות.
    • באופן דינמי לספריות VNDK במחיצה system.
  • ספריות JNI ב-APKs לא מקוובצים במחיצה product כדי לקשר לספריות ב-/product/lib או ב-/product/lib64 (בנוסף לספריות NDK).

האכיפה לא מאפשרת קישורים אחרים למחיצות מלבד המחיצה product.

אכיפה בזמן ה-build (Android.bp)

ב-Android 11, מודולים של מערכת יכולים ליצור וריאנט של קובץ אימג' של מוצר, בנוסף לווריאציות של קובץ אימג' ליבה וקובץ אימג' של ספק. כשאכיפה של ממשק מקורי מופעלת (PRODUCT_PRODUCT_VNDK_VERSION מוגדר ל-current):

  • מודולים מקומיים במחיצה product נמצאים בגרסת המוצר במקום בגרסת הליבה.

  • מודולים עם product_available: true בקובצי Android.bp שלהם זמינים לווריאנט המוצר.

  • ספריות או קבצים בינאריים שצוין בהם product_specific: true יכולים לקשר לספריות אחרות שצוין בהן product_specific: true או product_available: true בקבצים שלהן מסוג Android.bp.

  • בספריות VNDK צריך להופיע product_available: true בקובצי Android.bp שלהן, כדי שקבצים בינאריים של product יוכלו לקשר לספריות VNDK.

בטבלה הבאה מפורט סיכום של המאפיינים Android.bp שמשמשים ליצירת וריאנטים של תמונות.

מאפיינים ב-Android.bp הווריאציות נוצרו
לפני האכיפה אחרי האכיפה
ברירת מחדל (ללא) הליבה
(כולל /system, ‏ /system_ext ו-/product)		 core
(כולל /system ו-/system_ext אבל לא /product)
system_ext_specific: true core core
product_specific: true core מכפלה
vendor: true ספק ספק
vendor_available: true core, vendor core, vendor
product_available: true לא רלוונטי core, product
vendor_available: true וגם product_available: true לא רלוונטי core, ‏ product, ‏ vendor
system_ext_specific: true וגם vendor_available: true core, vendor core, vendor
product_specific: true וגם vendor_available: true core, vendor מוצר, ספק

אכיפה בזמן ה-build (Android.mk)

כשאכיפת הממשק המקורי מופעלת, למודוליים מקומיים שמותקנים במחיצה product יש סוג קישור native:product שיכול לקשר רק למודוליים אחרים מסוג native:product או native:vndk. ניסיון לקשר למודולים אחרים מלבד אלה יגרום למערכת ה-build ליצור שגיאה בבדיקת סוג הקישור.

אכיפה בזמן ריצה

כשאכיפת הממשק המקורי מופעלת, הגדרת הקישור של ה-linker של Bionic לא מאפשרת לתהליכי המערכת להשתמש בספריות product, ויוצרת קטע product לתהליכי product שלא יכולים לקשר לספריות מחוץ למחיצה product (עם זאת, תהליכים כאלה יכולים לקשר לספריות VNDK). ניסיונות להפר את הגדרת הקישור בסביבת זמן הריצה גורמים לכך שהתהליך נכשל ומונפקת הודעת השגיאה CANNOT LINK EXECUTABLE.

אכיפת ממשקי Java

כדי להפעיל את אכיפת הממשק של Java, מגדירים את הערך של PRODUCT_ENFORCE_PRODUCT_PARTITION_INTERFACE ל-true. (הערך מוגדר באופן אוטומטי ל-true כשרמת ה-API של שירותי המשלוח ליעד גבוהה מ-29). כשהאכיפה מופעלת, היא מאפשרת או אוסרת את הגישה הבאה:

API /system /system_ext /product /vendor /data
Public API
‎@SystemApi
@hide API

כמו במחיצה vendor, אפליקציה או ספריית Java במחיצה product יכולות להשתמש רק בממשקי API ציבוריים וממשקי API של מערכת. אסור לקשר לספרייה שמשתמשת בממשקי API מוסתרים. ההגבלה הזו כוללת קישור בזמן ה-build והשתקפות בזמן הריצה.

אכיפה בזמן ה-build

בזמן ה-build, ה-Make וה-Soong בודקים את השדות platform_apis ו-sdk_version כדי לוודא שממשקי ה-API המוסתרים לא נמצאים בשימוש במודולים של Java במחיצה product. השדה sdk_version של אפליקציות במחיצה product חייב להיות מלא ב-current, ב-system_current או בגרסת API מספרית, והשדה platform_apis חייב להיות ריק.

אכיפה בזמן ריצה

סביבת זמן הריצה של Android מאמתת שאפליקציות במחיצה product לא משתמשות בממשקי API מוסתרים, כולל שיקוף (reflection). פרטים נוספים זמינים במאמר הגבלות על ממשקים שאינם SDK.

הפעלת אכיפה של ממשק המוצר

כדי להפעיל את האכיפה של ממשק המוצר, פועלים לפי השלבים שמפורטים בקטע הזה.

שלב משימה חובה
1 מגדירים קובץ makefile משלכם למערכת שמציין את החבילות למחיצה system, ואז מגדירים את בדיקת הדרישה לנתיב של הארטיפקטים ב-device.mk (כדי למנוע התקנה של מודולים שאינם מערכת במחיצה system). לא
2 ניקוי רשימת ההיתרים. לא
3 אכיפה של ממשקים מקומיים וזיהוי כשלים בקישורים בסביבת זמן הריצה (אפשר להריץ במקביל לאכיפה של Java). Y
4 אכיפה של ממשקי Java ואימות התנהגות בזמן ריצה (אפשר להריץ במקביל לאכיפה המקורית). Y
5 בודקים את ההתנהגויות בזמן הריצה. Y
6 מעדכנים את device.mk באמצעות אכיפה של ממשק המוצר. Y

שלב 1: יוצרים קובץ makefile ומפעילים בדיקה של נתיב הארטיפקט

בשלב הזה מגדירים את קובץ ה-makefile‏ system.

  1. יוצרים קובץ makefile שמגדיר את החבילות למחיצה system. לדוגמה, יוצרים קובץ oem_system.mk עם הפרטים הבאים:

    $(call inherit-product, $(SRC_TARGET_DIR)/product/handheld_system.mk)
$(call inherit-product, $(SRC_TARGET_DIR)/product/telephony_system.mk)

# Applications
PRODUCT_PACKAGES += \
    CommonSystemApp1 \
    CommonSystemApp2 \
    CommonSystemApp3 \

# Binaries
PRODUCT_PACKAGES += \
    CommonSystemBin1 \
    CommonSystemBin2 \
    CommonSystemBin3 \

# Libraries
PRODUCT_PACKAGES += \
    CommonSystemLib1 \
    CommonSystemLib2 \
    CommonSystemLib3 \

PRODUCT_SYSTEM_NAME := oem_system
PRODUCT_SYSTEM_BRAND := Android
PRODUCT_SYSTEM_MANUFACTURER := Android
PRODUCT_SYSTEM_MODEL := oem_system
PRODUCT_SYSTEM_DEVICE := generic

# For system-as-root devices, system.img should be mounted at /, so we
# include ROOT here.
_my_paths := \
 $(TARGET_COPY_OUT_ROOT)/ \
 $(TARGET_COPY_OUT_SYSTEM)/ \

$(call require-artifacts-in-path, $(_my_paths),)

  2. בקובץ device.mk, יורשים את קובץ ה-makefile המשותף למחיצה system ומפעילים את הבדיקה של דרישות הנתיב לארטיפקט. לדוגמה:

    $(call inherit-product, $(SRC_TARGET_DIR)/product/oem_system.mk)

# Enable artifact path requirements checking
PRODUCT_ENFORCE_ARTIFACT_PATH_REQUIREMENTS := strict

מידע על הדרישות לגבי נתיב הארטיפקט

כשהערך של PRODUCT_ENFORCE_ARTIFACT_PATH_REQUIREMENTS מוגדר כ-true או כ-strict, מערכת ה-build מונעת התקנה של חבילות שהוגדרו בקובצי makefile אחרים בנתיב שהוגדרו ב-require-artifacts-in-path ו מונעת התקנה של ארטיפקטים מחוץ לנתיב שהוגדרו ב-require-artifacts-in-path על ידי חבילות שהוגדרו בקובץ ה-makefile הנוכחי.

בדוגמה שלמעלה, כשהערך של PRODUCT_ENFORCE_ARTIFACT_PATH_REQUIREMENTS מוגדר כ-strict, קובצי makefile מחוץ ל-oem_system.mk לא יכולים לכלול מודולים שהותקנו במחיצה root או system. כדי לכלול את המודולים האלה, צריך להגדיר אותם בקובץ oem_system.mk עצמו או בקובץ makefile שכלול. ניסיונות להתקין מודולים בנתיבים אסורים גורמים לשיבושים ב-build. כדי לתקן את ההפסקות, מבצעים אחת מהפעולות הבאות:

  • אפשרות 1: כוללים את מודול המערכת בקובצי ה-makefile שכלולים ב-oem_system.mk. כך מתקיים הדרישה לגבי נתיב הארטיפקט (כי המודוליים קיימים עכשיו בקובץ makefile שכלול), וכך אפשר להתקין את הקבצים בקבוצת הנתיבים שמופיעה בקובץ require-artifacts-in-path.

  • אפשרות 2: מתקינים מודולים במחיצה system_ext או product (ולא מתקינים מודולים במחיצה system).

  • אפשרות 3: מוסיפים מודולים ל-PRODUCT_ARTIFACT_PATH_REQUIREMENT_ALLOWED_LIST. ברשימה הזו מפורטים המודולים שמותר להתקין.

שלב 2: מרוקנים את רשימת ההיתרים

בשלב הזה, משאירים את PRODUCT_ARTIFACT_PATH_REQUIREMENT_ALLOWED_LIST ריק כדי שכל המכשירים שמשתפים את oem_system.mk יוכלו לשתף גם תמונה אחת של system. כדי לרוקן את רשימת ההיתרים, מעבירים את המודולים ברשימה למחיצה system_ext או product, או מוסיפים אותם לקובצי make של system. השלב הזה הוא אופציונלי כי לא צריך להגדיר קובץ system משותף כדי להפעיל אכיפה של ממשק המוצר. עם זאת, ריקון רשימת ההיתרים עוזר להגדיר את הגבול של system באמצעות system_ext.

שלב 3: אכיפה של ממשקים מקומיים

בשלב הזה מגדירים את PRODUCT_PRODUCT_VNDK_VERSION := current, מחפשים שגיאות ב-build ובזמן הריצה ומתקנים אותן. כדי לבדוק את האתחול והיומנים של המכשיר ולמצוא ולתקן כשלים בקישורים בסביבת זמן הריצה:

  1. מגדירים את PRODUCT_PRODUCT_VNDK_VERSION := current.

  2. יוצרים את המכשיר ומחפשים שגיאות ב-build. סביר להניח שתראו כמה שגיאות ב-build בגלל וריאציות חסרות של מוצרים או וריאציות ליבה. הפסקות נפוצות כוללות:

    • כל מודול hidl_interface שיש לו product_specific: true לא יהיה זמין למודולים מערכתיים. כדי לתקן את הבעיה, מחליפים את product_specific: true ב-system_ext_specific: true.
    • יכול להיות שבמודולים חסרה הווריאציה של המוצר שנדרשת למודול המוצר. כדי לפתור את הבעיה, צריך להגדיר את המודול הזה כזמין למחיצה product באמצעות ההגדרה product_available: true, או להעביר את המודול למחיצה product באמצעות ההגדרה product_specific: true.

  3. פותרים שגיאות ב-build ומוודאים שה-build של המכשיר הצליח.

  4. מעבירים את התמונה באמצעות Flash ומחפשים שגיאות זמן ריצה בהפעלה וביומני המכשיר.

    • אם התג linker ביומן של מקרה הבדיקה מציג את ההודעה CANNOT LINK EXECUTABLE, בקובץ ה-make חסר יחסי תלות (והוא לא תועד בזמן ה-build).
    • כדי לבדוק את זה ממערכת ה-build, מוסיפים את הספרייה הנדרשת לשדה shared_libs: או required:.

  5. פותרים את יחסי התלות החסרים לפי ההנחיות שלמעלה.

שלב 4: אכיפה של ממשקי Java

בשלב הזה מגדירים את PRODUCT_ENFORCE_PRODUCT_PARTITION_INTERFACE := true, ואז מאתרים את שגיאות ה-build שנוצרו ותוקנים אותן. מחפשים שני סוגים ספציפיים של שגיאות:

  • שגיאות שקשורות לסוג הקישור השגיאה הזו מציינת שאפליקציה מקשרת למודולים של Java עם sdk_version רחב יותר. כדי לפתור את הבעיה, אפשר להרחיב את sdk_version של האפליקציה או להגביל את sdk_version של הספרייה. שגיאה לדוגמה:

    error: frameworks/base/packages/SystemUI/Android.bp:138:1: module "SystemUI" variant "android_common": compiles against system API, but dependency "telephony-common" is compiling against private API.Adjust sdk_version: property of the source or target module so that target module is built with the same or smaller API set than the source.

  • שגיאות בסמל השגיאה הזו מציינת שאי אפשר למצוא סמל כי הוא נמצא ב-API מוסתר. כדי לפתור את הבעיה, צריך להשתמש ב-API גלוי (לא מוסתר) או למצוא חלופה. שגיאה לדוגמה:

    frameworks/opt/net/voip/src/java/com/android/server/sip/SipSessionGroup.java:1051: error: cannot find symbol
            ProxyAuthenticate proxyAuth = (ProxyAuthenticate)response.getHeader(
                                           ^
  symbol:   class ProxyAuthenticate
  location: class SipSessionGroup.SipSessionImpl

שלב 5: בדיקת התנהגויות בזמן ריצה

בשלב הזה בודקים שההתנהגות בזמן הריצה היא כצפוי. באפליקציות שאפשר לנפות בהן באגים, אפשר לעקוב אחרי השימוש ב-API מוסתר באמצעות יומן באמצעות StrictMode.detectNonSdkApiUsage (שמייצר יומן כשהאפליקציה משתמשת ב-API מוסתר). לחלופין, אפשר להשתמש בכלי הניתוח הסטטי veridex כדי לקבל את סוג השימוש (קישור או שיקוף), רמת ההגבלה וסטאק הקריאות.

  • תחביר Veridex:

    ./art/tools/veridex/appcompat.sh --dex-file={apk file}

  • דוגמה לתוצאה של Veridex:

    #1: Linking greylist-max-o Landroid/animation/AnimationHandler;-><init>()V use(s):
       Lcom/android/systemui/pip/phone/PipMotionHelper;-><init>(Landroid/content/Context;Landroid/app/IActivityManager;Landroid/app/IActivityTaskManager;Lcom/android/systemui/pip/phone/PipMenuActivityController;Lcom/android/internal/policy/PipSnapAlgorithm;Lcom/android/systemui/statusbar/FlingAnimationUtils;)V

#1332: Reflection greylist Landroid/app/Activity;->mMainThread use(s):
       Landroidx/core/app/ActivityRecreator;->getMainThreadField()Ljava/lang/reflect/Field;

לפרטים על השימוש ב-Veridex, אפשר לעיין במאמר בדיקה באמצעות הכלי של Veridex.

שלב 6: מעדכנים את device.mk

אחרי שמתקנים את כל הכישלונות בזמן ה-build ובזמן הריצה, ומוודאים שההתנהגויות בזמן הריצה תואמות לציפיות, מגדירים את הפרמטרים הבאים ב-device.mk:

  • PRODUCT_PRODUCT_VNDK_VERSION := current
  • PRODUCT_ENFORCE_PRODUCT_PARTITION_INTERFACE := true