תמיכה בגודלי דפים של 16KB

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

Historically, Android has only supported 4 KB memory page sizes, which has optimized system memory performance for the average amount of total memory that Android devices have typically had. Beginning with Android 15, AOSP supports devices that are configured to use a page size of 16 KB (16 KB devices). If your app uses any NDK libraries, either directly or indirectly through an SDK, then you will need to rebuild your app for it to work on these 16 KB devices.

As device manufacturers continue to build devices with larger amounts of physical memory (RAM), many of these devices will adopt 16 KB (and eventually greater) page sizes to optimize the device's performance. Adding support for 16 KB page size devices enables your app to run on these devices and helps your app benefit from the associated performance improvements. Without recompiling, apps might not work on 16 KB devices when they are productionized in future Android releases.

To help you add support for your app, we've provided guidance on how to check if your app is impacted, how to rebuild your app (if applicable), and how to test your app in a 16 KB environment using emulators (including Android 15 system images for the Android Emulator).

יתרונות ושיפור בביצועים

Devices configured with 16 KB page sizes use slightly more memory on average, but also gain various performance improvements for both the system and apps:

• Lower app launch times while the system is under memory pressure: 3.16% lower on average, with more significant improvements (up to 30%) for some apps that we tested
• Reduced power draw during app launch: 4.56% reduction on average
• Faster camera launch: 4.48% faster hot starts on average, and 6.60% faster cold starts on average
• Improved system boot time: improved by 8% (approximately 950 milliseconds) on average

These improvements are based on our initial testing, and results on actual devices will likely differ. We'll provide additional analysis of potential gains for apps as we continue our testing.

איך בודקים אם האפליקציה שלכם מושפעת

If your app uses any native code, then you should rebuild your app with support for 16 KB devices. If you are unsure if your app uses native code, you can use the APK Analyzer to identify whether any native code is present and then check the alignment of ELF segments for any shared libraries that you find.

If your app only uses code written in the Java programming language or in Kotlin, including all libraries or SDKs, then your app already supports 16 KB devices. Nevertheless, we recommend that you test your app in a 16 KB environment to verify that there are no unexpected regressions in app behavior.

האם באפליקציה שלכם נעשה שימוש בקוד מקורי?

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

• האפליקציה שלכם משתמשת בקוד C/C++ (מקומי). אם האפליקציה שלכם משתמשת ב-Android NDK, היא משתמשת בקוד מקורי.
• האפליקציה מקשרת לספריות מקומיות או יחסי תלות של צד שלישי (כמו ערכות SDK) שמשתמשים בהן.
• האפליקציה שלכם נוצרה על ידי כלי לפיתוח אפליקציות של צד שלישי שמשתמש בספריות מקומיות במכשיר.

זיהוי ספריות מקוריות באמצעות הכלי לניתוח APK

APK Analyzer הוא כלי שמאפשר להעריך היבטים שונים של קובץ APK שנוצר. כדי לבדוק אם האפליקציה שלכם משתמשת בקוד מקורי (ללא קשר לכך שהיא תואמת לדפים בגודל 16KB):

1. פותחים את Android Studio, לוחצים על File > Open (קובץ > פתיחה) ובוחרים פרויקט כלשהו.

2. בסרגל התפריטים, לוחצים על Build‏ > Analyze APK…

   

3. בוחרים את קובץ ה-APK שרוצים לנתח.

4. בודקים בתיקייה lib, שמארחת קבצים של אובייקטים משותפים (.so), אם יש כאלה. אם יש קבצים של אובייקטים משותפים, האפליקציה משתמשת בקוד מקורי. אם אין קובצי אובייקטים משותפים או שאין תיקייה lib, האפליקציה לא משתמשת בקוד מקורי.

   

בדיקת ההתאמה של פלחי ELF בספריות משותפות

בכל ספרייה משותפת, צריך לוודא שהפלחים של ה-ELF בספריות המשותפות מותאמים בצורה נכונה באמצעות התאמה של 16 KB ELF. אם אתם מפתחים ב-Linux או ב-macOS, תוכלו להשתמש בסקריפט check_elf_alignment.sh כפי שמתואר בקטע הבא. אפשר גם להשתמש בכלי שורת הפקודה ישירות.

שימוש בסקריפט check_elf_alignment.sh (Linux או macOS)

כדי לבדוק את ההתאמה של פלחים של ELF באמצעות הסקריפט check_elf_alignment.sh:

1. שומרים את הסקריפט check_elf_alignment.sh בקובץ.

2. מריצים את הסקריפט בקובץ ה-APK של האפליקציה:

   check_elf_alignment.sh APK_NAME.apk
   

   הפלט של הסקריפט הוא ALIGNED או UNALIGNED לכל arm64-v8a הספריות המשותפות.

3. אם ספריות משותפות מסוג arm64-v8a או x86_64 הן בגרסה UNALIGNED, תצטרכו לעדכן את האריזה של הספריות האלה, ואז לערוך קומפילציה מחדש של האפליקציה ולבדוק אותה מחדש לפי השלבים שמפורטים בקטע הזה.

שימוש בכלי שורת הפקודה ישירות

כדי לבדוק את ההתאמה של פלחי ELF באמצעות כלים ישירות בשורת הפקודה:

1. מוודאים ש-Android SDK Build-Tools בגרסה 35.0.0 ואילך ו-Android NDK מותקנים באמצעות SDK Manager ב-Android Studio או באמצעות הכלי בשורת הפקודה sdkmanager.

2. לחלץ את קובץ ה-APK של האפליקציה:

   Linux או macOS

   unzip APK_NAME.apk -d /tmp/my_apk_out
   

   Windows‏ (PowerShell)

   Expand-Archive -Path .\APK_NAME.apk -DestinationPath ~\tmp\my_apk_out
   

3. בספרייה הזמנית שאליה חילוץ את קובץ ה-APK, בודקים את התוכן של הספרייה lib כדי למצוא קבצים של אובייקטים משותפים (.so). אלה אותם קובצי אובייקטים משותפים שראיתם בזמן זיהוי ספריות מקומיות באמצעות APK Analyzer. מריצים את הפקודה הבאה בכל קובץ אובייקט משותף:

   Linux או macOS

   SDK_ROOT_LOCATION/Android/sdk/ndk/NDK_VERSION/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-objdump -p SHARED_OBJECT_FILE.so | grep LOAD
   

   Windows‏ (PowerShell)

   SDK_ROOT_LOCATION\Android\sdk\ndk\NDK_VERSION\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-objdump.exe -p SHARED_OBJECT_FILE.so | Select-String -Pattern "LOAD"
   

   כאשר SDK_ROOT_LOCATION הוא הנתיב לספרייה שבה התקנתם את Android SDK, SHARED_OBJECT_FILE הוא שם קובץ האובייקט המשותף שאתם בודקים ו-NDK_VERSION הוא גרסת Android NDK שהותקנה (לדוגמה, 28.0.12433566). הפלט ייראה בערך כך לכל קובץ שתבדקו:

   LOAD off    0x0000000000000000 vaddr 0x0000000000000000 paddr 0x0000000000000000 align 2**14
   LOAD off    0x0000000000042a90 vaddr 0x0000000000043a90 paddr 0x0000000000043a90 align 2**14
   LOAD off    0x0000000000046230 vaddr 0x0000000000048230 paddr 0x0000000000048230 align 2**14
   

4. בודקים את שורות הפלט כדי לוודא שבקטעי העומס אין ערכים קטנים מ-2**14. אם יש קטעי עומס עם הערכים 2**13, 2**12 או ערכים נמוכים יותר, תצטרכו לעדכן את האריזה של הספריות האלה, ואז לערוך קומפילציה מחדש של האפליקציה ולבצע בדיקה חוזרת לפי השלבים שמפורטים בקטע הזה.

5. בשלב הבא, מריצים את כלי שורת הפקודה zipalign בקובץ ה-APK של האפליקציה:

   Linux או macOS

   SDK_ROOT_LOCATION/Android/sdk/build-tools/35.0.0/zipalign -v -c -P 16 4 APK_NAME.apk
   

   Windows‏ (PowerShell)

   SDK_ROOT_LOCATION\Android\sdk\build-tools\35.0.0\zipalign.exe -v -c -P 16 4 APK_NAME.apk
   

   כאשר SDK_ROOT_LOCATION הוא הנתיב לספרייה שבה התקנתם את Android SDK, ו-APK_NAME הוא שם קובץ ה-APK של האפליקציה. אם כל הספריות המשותפות מותאמות בצורה נכונה, בשורה האחרונה של הפלט יופיע הכיתוב 'Verification successful'.

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

פיתוח אפליקציה עם תמיכה במכשירים בנפח 16KB

אם האפליקציה שלכם משתמשת בקוד מקורי, עליכם לבצע את השלבים שמפורטים בקטעים הבאים כדי לוודא שהאפליקציה תומכת במכשירים בנפח 16 KB:

1. עדכון האריזה של הספריות המשותפות
2. הדרכה ל-GCC: איך מקמפלים אפליקציות עם יישור ELF בגודל 16KB
3. תיקון קוד ופתרון בעיות בסביבת זמן הריצה
4. בדיקת ערכות SDK לתמיכה ב-16KB

עדכון האריזה של הספריות המשותפות

מומלץ לשדרג ל-AGP בגרסה 8.5.1 ואילך ולהשתמש בספריות משותפות לא דחוסות.

AGP מגרסה 8.5.1 ואילך

במכשירים עם 16KB, אפליקציות שכוללות ספריות משותפות לא דחוסות צריכות להתאים אותן לגבול של 16KB בפורמט zip. לשם כך, צריך לשדרג את Android Gradle Plugin‏ (AGP) לגרסה 8.5.1 ואילך. פרטים על תהליך השדרוג מופיעים בקטע Android Plugin Upgrade Assistant.

AGP מגרסה 8.5 ומטה

אם אתם לא יכולים לשדרג את AGP לגרסה 8.5.1 ואילך, האפשרות החלופית היא לעבור לשימוש בספריות משותפות דחוסות. כדי למנוע בעיות בהתקנת האפליקציה עם ספריות משותפות לא מותאמות, צריך לעדכן את ההגדרות של Gradle כך ש-Gradle ידחוס את הספריות המשותפות בזמן האריזה של האפליקציה.

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging true
      }
  }
}

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging = true
      }
  }
}

איך מקמפלים את האפליקציה באמצעות התאמה של ELF בגודל 16KB

כדי שהאפליקציה תפעל במכשירים עם 16KB, צריך לבצע התאמה נכונה של קטעי ה-ELF בספריות המשותפות באמצעות התאמה של 16KB ELF.

למפתחי משחקים: אם המשחק שלכם פועל על מנוע המשחקים של Unity, תוכלו לעיין במדריך של Unity. אם המשחק שלכם פועל על גבי Unreal game engine, תוכלו לעיין במדריך של Unreal. למנועי משחקים מקומיים, ממשיכים במדריך הזה.

כדי לקמפל את האפליקציה באמצעות התאמה של ELF בגודל 16 KB, פועלים לפי השלבים שמפורטים באחד מהקטעים הבאים, בהתאם לגרסה של Android NDK שבה אתם משתמשים.

Android NDK r28 ואילך

ב-NDK מגרסה r28 ואילך, הידור מתבצע בהתאמה ל-16KB כברירת מחדל.

Android NDK r27

כדי לתמוך בתכנות של ספריות משותפות בגודל 16KB עם Android NDK בגרסה r27 ואילך, צריך לעדכן את הדגלים ndk-build,‏ build.gradle,‏ build.gradle.kts או את הדגלים של הקישור באופן הבא:

APP_SUPPORT_FLEXIBLE_PAGE_SIZES := true

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
      }
    }
  }
}

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments += listOf("-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON")
      }
    }
  }
}

-Wl,-z,max-page-size=16384

Android NDK r26 וגרסאות קודמות

כדי לתמוך בתכנות של ספריות משותפות שתואמות ל-16KB באמצעות Android NDK בגרסה r26 ואילך, צריך לעדכן את ההגדרה של ndk-build או cmake באופן הבא:

LOCAL_LDFLAGS += "-Wl,-z,max-page-size=16384"

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE "-Wl,-z,max-page-size=16384")

תיקון קוד ופתרון בעיות בסביבת זמן הריצה

גם אם האפליקציה מותאמת לגודל דף של 16KB, יכולות להיות באפליקציה שגיאות אם בחלקים מסוימים בקוד מוגדרת הנחה שמכשיר מסוים משתמש בגודל דף ספציפי. כדי למנוע זאת, צריך לבצע את השלבים הבאים:

1. מסירים יחסי תלות שמוגדרים בקוד ומפנים לקבוע PAGE_SIZE, או אירועים לוגיים בקוד שמניחים שגודל הדף של המכשיר הוא 4KB (4096).

   במקום זאת, צריך להשתמש ב-getpagesize() או ב-sysconf(_SC_PAGESIZE).

2. מחפשים שימושים ב-mmap() ובממשקי API אחרים שדורשים ארגונו של ארגומנטים בהתאם לדף, ומחליפים אותם בחלופות במקרה הצורך.

במקרים מסוימים, אם באפליקציה נעשה שימוש ב-PAGE_SIZE כערך נוח שלא קשור לגודל הדף הבסיסי, הדבר לא יגרום לשגיאות באפליקציה כשמשתמשים בה במצב 16KB. עם זאת, אם הערך הזה מועבר לליבה עם mmap בלי MAP_FIXED, הליבה עדיין משתמשת בדף שלם, וכך מתבזבזת קצת זיכרון. לכן, הערך של PAGE_SIZE לא מוגדר כשמפעילים את המצב של 16KB ב-NDK בגרסה 27 ואילך.

אם האפליקציה משתמשת ב-PAGE_SIZE באופן הזה ואף פעם לא מעבירה את הערך הזה ישירות לליבה, במקום להשתמש ב-PAGE_SIZE, צריך ליצור משתנה חדש עם שם חדש כדי לשקף את העובדה שהוא משמש למטרות אחרות ולא משקף דף זיכרון אמיתי.

בדיקת ערכות ה-SDK לתמיכה ב-16KB

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

בדיקת האפליקציה בסביבה של 16 KB

אחרי שתיצרו את האפליקציה עם תמיכה במכשירים בנפח 16KB, כדאי לבדוק את האפליקציה בסביבה בנפח 16KB כדי לראות אם יש בה נסיגה לאחור. לשם כך, בצע את הצעדים הבאים:

1. מגדירים את Android 15 SDK.

2. מגדירים אחת מסביבות הבדיקה הבאות:

   • הגדרת Android Emulator באמצעות קובץ אימג' של מערכת Android 15 בגודל 16KB
   • הפעלת מצב 16KB במכשיר באמצעות אפשרויות למפתחים
   • שימוש ב-Cuttlefish עם גודל דף של 16KB ב-ARM64
   • הדמיה של Cuttlefish עם גודל דף של 16KB ב-x86-64

3. מפעילים את מכשיר הבדיקה ומריצים את הפקודה הבאה כדי לוודא שהוא משתמש בסביבה של 16 KB:

   adb shell getconf PAGE_SIZE
   

   הפקודה אמורה להחזיר את הערך 16384.

4. מריצים את הפקודה הבאה zipalign כדי לוודא שהאפליקציה מותאמת ל-16KB, כאשר APK_NAME הוא השם של קובץ ה-APK של האפליקציה:

   zipalign -c -P 16 -v 4 APK_NAME.apk
   

5. בודקים היטב את האפליקציה ומתמקדים באזורים שעשויים להיות מושפעים משינוי של מופעי קוד שמפנים לגדלים ספציפיים של דפים.

הגדרת Android Emulator באמצעות קובץ אימג' של מערכת Android 15 בגודל 16KB

כדי להגדיר סביבה של 16 KB באמצעות Android Emulator:

1. קובצי אימג' של מערכת אמולטור של Android 15 בגודל 16KB תואמים ל-Android Studio Jellyfish | 2023.3.1 ואילך. עם זאת, כדי ליהנות מחוויית השימוש הטובה ביותר כשעובדים עם מכשירים בנפח 16KB, מומלץ להשתמש ב-Android Studio Ladybug | 2024.2.1 ואילך.

   אנחנו תמיד עובדים על תכונות חדשות, לכן מומלץ להוריד גרסאות חדשות יותר או את גרסת הבטא האחרונה של Android Studio כשהן זמינות.

   חשוב לזכור שאפשר להשאיר את הגרסה הקיימת של Android Studio מותקנת, כי אפשר להתקין כמה גרסאות במקביל.

2. ב-Android Studio, לוחצים על Tools (כלים) > SDK Manager (מנהל SDK).

3. בכרטיסייה SDK Platforms, מסמנים את התיבה Show Package Details, מרחיבים את הקטע Android VanillaIceCream ואילך ובוחרים אחת או את שתי קובצי האימג' של מערכת האמולטור הבאים, בהתאם למכשירים הווירטואליים שרוצים ליצור:

   • Google APIs Experimental 16 KB Page Size ARM 64 v8a System Image
   • Google APIs Experimental 16 KB Page Size Intel x86_64 Atom System Image

   

4. לוחצים על אישור > בסדר כדי להוריד את קובצי האימג' של המערכת שבחרתם.

5. פועלים לפי השלבים להגדרת מכשיר וירטואלי ל-Android 15, וכשמופיעה בקשה לבחור קובץ אימג' של מערכת, בוחרים את קובץ האימג' בגודל 16KB שהורדתם. אם היא לא מומלצת באופן אוטומטי, תוכלו למצוא את קובץ האימג' של המערכת בגודל 16KB בכרטיסייה תמונות אחרות.

   

שלבים נוספים לגרסאות מסוימות של מכונות וירטואליות ולתמונות מערכת

ב-Android Emulator בגרסאות 35.1.5 עד 35.1.20, ולפני גרסה 4 של קובצי האימג' של מערכת Android 15.0 עם דפים בגודל 16KB שמוצעים ב-SDK Manager, כדי לדמות סביבה של 16KB במערכות x86_64, צריך לבצע גם את השלבים הבאים. אין צורך לבצע את השלבים האלה אחרי גרסה 35.1.21, ובגרסה 4 ואילך של קובצי האימג' של מערכת Android 15.0 עם דפים בגודל 16KB.

1. במנהל המכשירים, לוחצים על 3 הנקודות לצד התמונה בגודל 16KB ואז על הצגה בדיסק.
2. בתיקייה הזו, מחפשים את הקובץ config.ini.

3. מוסיפים את השורה הבאה לקובץ config.ini ושומרים את השינויים:

   kernel.parameters = androidboot.page_shift=14
   

4. כדי לאמת את השינויים, מריצים את הפקודה הבאה, והיא אמורה להחזיר את הערך 16384:

   adb shell getconf PAGE_SIZE
   

הפעלת האמולטור

אחרי שמסיימים להגדיר את Android Emulator ואת המכשירים הווירטואליים, מפעילים את הסימולטור מתפריט המכשיר היעד או משורת הפקודה.

Enable 16 KB mode on a device using developer options

Toggle the Boot with 16KB page size developer option to boot a device in 16 KB mode.

Starting with Android 15 QPR1, you can use the developer option that's available on certain devices to boot the device in 16 KB mode and perform on-device testing.

This developer option is available on the following devices:

• Pixel 8 and 8 Pro (with Android 15 QPR1 or higher)

  Warning: Due to a known issue with Android 15 QPR2 Beta 3, the touchscreen doesn't work on Pixel 8 devices after installing Android 15 QPR2 Beta 3 and booting the device in 16 KB mode. This issue doesn't affect Pixel 8 Pro devices.

• Pixel 8a (with Android 15 QPR1 or higher)

  Warning: Due to a known issue with Android 15 QPR2 Beta 3, the touchscreen doesn't work on Pixel 8a devices after installing Android 15 QPR2 Beta 3 and booting the device in 16 KB mode.

• Pixel 9, 9 Pro, and 9 Pro XL (with Android 15 QPR2 Beta 2 or higher)