از 27 مارس 2025، توصیه می کنیم از android-latest-release به جای aosp-main برای ساختن و کمک به AOSP استفاده کنید. برای اطلاعات بیشتر، به تغییرات AOSP مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

تصاویر سیستم عمومی

یک تصویر سیستم عمومی (GSI) یک تصویر سیستم با پیکربندی‌های تنظیم‌شده برای دستگاه‌های اندروید است. این یک پیاده‌سازی خالص اندروید با کد پروژه متن‌باز اندروید (AOSP) اصلاح‌نشده در نظر گرفته می‌شود که هر دستگاه اندرویدی که اندروید ۹ یا بالاتر را اجرا می‌کند می‌تواند با موفقیت آن را اجرا کند.

GSIها برای اجرای تست‌های VTS و CTS-on-GSI استفاده می‌شوند. تصویر سیستم یک دستگاه اندروید با یک GSI جایگزین می‌شود و سپس با مجموعه تست فروشنده (VTS) و مجموعه تست سازگاری (CTS) آزمایش می‌شود تا اطمینان حاصل شود که دستگاه رابط‌های فروشنده را به درستی با آخرین نسخه اندروید پیاده‌سازی می‌کند.

برای شروع کار با GSIها، بخش‌های زیر را برای جزئیات بیشتر در مورد پیکربندی‌های GSI (و واریانس‌های مجاز) و انواع آنها بررسی کنید. وقتی آماده استفاده از GSI شدید، GSI را برای دستگاه هدف خود دانلود و بسازید ، سپس GSI را روی یک دستگاه اندروید فلش کنید .

پیکربندی و واریانس‌های GSI

پیکربندی فعلی Android GSI به شرح زیر است:

Treble. GSI شامل پشتیبانی کامل از تغییرات معماری مبتنی بر AIDL/HIDL (که با نام Treble نیز شناخته می‌شود) است، از جمله پشتیبانی از رابط‌های AIDL و رابط‌های HIDL . می‌توانید از GSI در هر دستگاه اندرویدی که از رابط‌های فروشنده AIDL/HIDL استفاده می‌کند، استفاده کنید. (برای جزئیات بیشتر، به منابع معماری مراجعه کنید.)
سیستم فایل. GSI از سیستم فایل ext4 استفاده می‌کند.

GSI فعلی اندروید شامل تغییرات عمده زیر است:

معماری CPU. پشتیبانی از دستورالعمل‌های مختلف CPU (ARM، x86 و غیره) و بیت‌های CPU (32 بیتی یا 64 بیتی).

اهداف GSI برای آزمایش‌های انطباق با Treble

GSI مورد استفاده برای آزمایش انطباق با نسخه اندرویدی که دستگاه با آن راه اندازی می شود، تعیین می شود.

نوع دستگاه	هدف ساخت
دستگاه‌هایی که با اندروید ۱۵ عرضه می‌شوند	`gsi_$arch-user` (امضا شده)
دستگاه‌هایی که با اندروید ۱۴ عرضه می‌شوند	`gsi_$arch-user` (امضا شده)
دستگاه‌هایی که با اندروید ۱۳ عرضه می‌شوند	`gsi_$arch-user` (امضا شده)
دستگاه‌هایی که با اندروید ۱۲L عرضه می‌شوند	`gsi_$arch-user` (امضا شده)
دستگاه‌هایی که با اندروید ۱۲ عرضه می‌شوند	`gsi_$arch-user` (امضا شده)
دستگاه‌هایی که با اندروید ۱۱ عرضه می‌شوند	`gsi_$arch-user` (امضا شده)

همه GSIها از کدبیس اندروید ۱۲ ساخته شده‌اند و هر معماری CPU یک فایل باینری GSI متناظر دارد (به لیست اهداف ساخت در بخش Building GSIها مراجعه کنید).

تغییرات GSI اندروید ۱۲

دستگاه‌هایی که با اندروید ۱۲ عرضه می‌شوند یا به آن به‌روزرسانی می‌شوند، باید برای آزمایش انطباق از GSIهای اندروید ۱۲ استفاده کنند. این شامل تغییرات عمده زیر نسبت به GSIهای قبلی است:

نام هدف. نام هدف GSI برای تست‌های انطباق به gsi_$arch تغییر یافته است. GSI با نام هدف aosp_$arch برای توسعه‌دهندگان برنامه‌های اندروید حفظ شده است. طرح تست CTS-on-GSI نیز برای تست رابط فروشنده کاهش یافته است.
GSI قدیمی به تدریج کنار گذاشته می‌شود. GSI 12 راه‌حل‌های جایگزین برای دستگاه‌های اندروید ۸.۰ یا ۸.۱ که به طور کامل Treblized نشده‌اند را حذف می‌کند.
Userdebug SEPolicy. فایل GSI gsi_$arch حاوی userdebug_plat_sepolicy.cil است. هنگام فلش کردن vendor_boot-debug.img یا boot-debug.img مخصوص OEM، /system/bin/init userdebug_plat_sepolicy.cil از GSI system.img بارگذاری می‌کند. برای جزئیات بیشتر به VTS Testing با Debug Ramdisk مراجعه کنید.

تغییرات GSI اندروید ۱۱

دستگاه‌هایی که با اندروید ۱۱ عرضه می‌شوند یا به آن به‌روزرسانی می‌شوند، باید برای آزمایش انطباق از GSIهای اندروید ۱۱ استفاده کنند. این شامل تغییرات عمده زیر نسبت به GSIهای قبلی است:

محتویات system_ext. اندروید ۱۱ یک پارتیشن جدید system_ext تعریف می‌کند. GSI محتویات افزونه سیستم را در پوشه system/system_ext قرار می‌دهد.
APEXها. GSI شامل APEXهای مسطح و فشرده است. اینکه کدام یک استفاده شود توسط ویژگی سیستم ro.apex.updatable در پارتیشن vendor در زمان اجرا تعیین می‌شود. مرجع پیکربندی سیستم برای پشتیبانی از به‌روزرسانی‌های APEX برای جزئیات.

تغییرات GSI اندروید ۱۰

دستگاه‌هایی که با اندروید ۱۰ عرضه می‌شوند یا به آن به‌روزرسانی می‌شوند، باید برای آزمایش انطباق از GSIهای اندروید ۱۰ استفاده کنند. این شامل تغییرات عمده زیر نسبت به GSIهای قبلی است:

ساخت کاربر. GSI از اندروید ۱۰ ساخت کاربر دارد. در اندروید ۱۰، می‌توان از GSI ساخت کاربر در تست انطباق CTS-on-GSI/VTS استفاده کرد. برای جزئیات بیشتر به تست VTS با Debug Ramdisk مراجعه کنید.
فرمت Unsparsed. فایل‌های GSI با هدف aosp_$arch با فرمت Unsparsed ساخته شده‌اند. در صورت لزوم می‌توانید img2simg برای تبدیل یک GSI Unsparsed به فرمت Sparse استفاده کنید.
سیستم به عنوان ریشه. هدف ساخت GSI قدیمی با نام aosp_$arch_a از رده خارج شده است. برای دستگاه‌هایی که از اندروید ۸ یا ۸.۱ به اندروید ۱۰ با ramdisk و بدون system-as-root ارتقا یافته‌اند، از GSI قدیمی aosp_$arch_ab استفاده کنید. init ارتقا یافته در ramdisk از فایل system.img سیستم عامل اصلی (OEM) با طرح‌بندی system-as-root پشتیبانی می‌کند.
تأیید بوت. با استفاده از GSI فقط باید دستگاه را باز کنید. غیرفعال کردن تأیید بوت ضروری نیست.

تغییرات GSI اندروید ۹

دستگاه‌هایی که با اندروید ۹ عرضه می‌شوند یا به آن به‌روزرسانی می‌شوند، باید از GSIهای اندروید ۹ برای آزمایش انطباق استفاده کنند. این شامل تغییرات عمده زیر نسبت به GSIهای قبلی است:

GSI و شبیه‌ساز را ادغام می‌کند. GSIها از روی تصاویر سیستم محصولات شبیه‌ساز، به عنوان مثال، aosp_arm64 و aosp_x86 ساخته می‌شوند.
سیستم به عنوان ریشه. در نسخه‌های قبلی اندروید، دستگاه‌هایی که از به‌روزرسانی‌های A/B پشتیبانی نمی‌کردند، می‌توانستند تصویر سیستم را در دایرکتوری /system نصب کنند. در اندروید ۹، ریشه تصویر سیستم به عنوان ریشه دستگاه نصب می‌شود.
رابط اتصال ۶۴ بیتی. در اندروید ۸.x، GSI های ۳۲ بیتی از رابط اتصال ۳۲ بیتی استفاده می‌کردند. اندروید ۹ از رابط اتصال ۳۲ بیتی پشتیبانی نمی‌کند، بنابراین هم GSI های ۳۲ بیتی و هم GSI های ۶۴ بیتی از رابط اتصال ۶۴ بیتی استفاده می‌کنند.
اجرای VNDK. در اندروید ۸.۱، VNDK اختیاری بود. از اندروید ۹ به بعد، VNDK اجباری شده است، بنابراین BOARD_VNDK_VERSION باید تنظیم شود.
ویژگی سیستم سازگار. اندروید ۹ بررسی دسترسی برای یک ویژگی سیستم سازگار ( PRODUCT_COMPATIBLE_PROPERTY_OVERRIDE := true ) را فعال می‌کند.

تغییرات کلیدی اندروید ۹

در نسخه‌های قبلی اندروید، دستگاه‌هایی که Keymaster 3 یا پایین‌تر را اجرا می‌کردند، ملزم بودند که اطلاعات نسخه ( ro.build.version.release و ro.build.version.security_patch ) گزارش شده توسط سیستم عامل در حال اجرا را با اطلاعات نسخه گزارش شده توسط بوت لودر مطابقت دهند. چنین اطلاعاتی معمولاً از هدر تصویر بوت به دست می‌آمد.

در اندروید ۹ و بالاتر، این الزام تغییر کرده است تا فروشندگان بتوانند یک GSI را بوت کنند. به طور خاص، Keymaster نباید تأیید را انجام دهد زیرا اطلاعات نسخه گزارش شده توسط GSI ممکن است با اطلاعات نسخه گزارش شده توسط بوت لودر فروشنده مطابقت نداشته باشد. برای دستگاه‌هایی که Keymaster 3 یا پایین‌تر را پیاده‌سازی می‌کنند، فروشندگان باید پیاده‌سازی Keymaster را برای رد کردن تأیید تغییر دهند (یا به Keymaster 4 ارتقا دهند). برای جزئیات بیشتر در مورد Keymaster، به Hardware-backed Keystore مراجعه کنید.

دانلود GSIها

شما می‌توانید GSIهای از پیش ساخته شده را از وب‌سایت ادغام مداوم (CI) AOSP به آدرس ci.android.com دانلود کنید. اگر نوع GSI برای پلتفرم سخت‌افزاری شما برای دانلود در دسترس نیست، برای جزئیات بیشتر در مورد ساخت GSI برای اهداف خاص، به بخش زیر مراجعه کنید.

ساخت GSIها

از اندروید ۹ به بعد، هر نسخه اندروید یک شاخه GSI به نام DESSERT -gsi در AOSP دارد (برای مثال، android12-gsi شاخه GSI در اندروید ۱۲ است). شاخه‌های GSI شامل محتوای اندروید به همراه تمام وصله‌های امنیتی و وصله‌های GSI اعمال شده هستند.

برای ساخت یک GSI، با دانلود از یک شاخه GSI و انتخاب یک هدف ساخت GSI، درخت منبع اندروید را تنظیم کنید. از جداول هدف ساخت زیر برای تعیین نسخه صحیح GSI برای دستگاه خود استفاده کنید. پس از اتمام ساخت، GSI همان تصویر سیستم (یعنی system.img ) است و در پوشه خروجی out/target/product/ generic_arm64 ظاهر می‌شود.

برای مثال، برای ساخت هدف GSI به نام gsi_arm64-userdebug در شاخه GSI android12-gsi ، دستورات زیر را اجرا کنید.

$ repo init -u https://android.googlesource.com/platform/manifest -b android12-gsi
$ repo sync -cq
$ source build/envsetup.sh
$ lunch gsi_arm64-userdebug
$ make -j4

اهداف ساخت GSI اندروید

اهداف ساخت GSI زیر برای دستگاه‌هایی است که با اندروید ۹ یا بالاتر عرضه می‌شوند.

نام GSI	قوس CPU	میزان تلخی رابط اتصال دهنده	سیستم به عنوان ریشه	هدف ساخت
`gsi_arm`	بازو	۳۲	ی	`gsi_arm-user` `gsi_arm-userdebug`
`gsi_arm64`	آرم۶۴	۶۴	ی	`gsi_arm64-user` `gsi_arm64-userdebug`
`gsi_x86`	ایکس۸۶	۳۲	ی	`gsi_x86-user` `gsi_x86-userdebug`
`gsi_x86_64`	x86-64	۶۴	ی	`gsi_x86_64-user` `gsi_x86_64-userdebug`

الزامات مربوط به فلش کردن GSIها

دستگاه‌های اندروید می‌توانند طراحی‌های متفاوتی داشته باشند، بنابراین هیچ دستور یا دستورالعمل عمومی برای فلش کردن یک GSI که برای همه دستگاه‌ها قابل اجرا باشد، وجود ندارد. برای دستورالعمل‌های صریح فلش کردن، با سازنده دستگاه اندروید مشورت کنید. از مراحل زیر به عنوان یک راهنمای کلی استفاده کنید:

مطمئن شوید که دستگاه موارد زیر را دارد:
- تربلیزه شده
- روشی برای باز کردن قفل دستگاه‌ها (تا بتوان آنها را با استفاده از fastboot فلش کرد)
- یک حالت قفل نشده برای قابل فلش شدن از طریق fastboot (برای اطمینان از اینکه آخرین نسخه fastboot را دارید، آن را از طریق سورس درختی اندروید بسازید.)
پارتیشن سیستم فعلی را پاک کنید، سپس GSI را به پارتیشن سیستم فلش کنید.
داده‌های کاربر را پاک کنید و داده‌ها را از سایر پارتیشن‌های لازم (مثلاً داده‌های کاربر و پارتیشن‌های سیستم) پاک کنید.
دستگاه را دوباره راه اندازی کنید.

برای مثال، برای فلش کردن یک GSI به هر دستگاه پیکسل:

به حالت fastboot بوت بروید و بوت لودر را آنلاک کنید .
دستگاه‌هایی که از fastbootd پشتیبانی می‌کنند، باید از طریق دستور زیر در fastbootd بوت شوند:
```
$ fastboot reboot fastboot
```
GSI را پاک کنید و آن را به پارتیشن سیستم فلش کنید:
```
$ fastboot erase system
$ fastboot flash system system.img
```
اگر دستگاه شما از چارچوب مجازی اندروید پشتیبانی می‌کند، میان‌افزار ماشین مجازی محافظت‌شده را فلش کنید:
```
$ fastboot flash pvmfw pvmfw.img
```
داده‌های کاربر را پاک کنید و داده‌ها را از سایر پارتیشن‌های لازم (به عنوان مثال، داده‌های کاربر و پارتیشن‌های سیستم) پاک کنید:
```
$ fastboot -w
```
دوباره به بوت لودر راه اندازی مجدد کنید:
```
$ fastboot reboot-bootloader
```
هنگام فلش کردن vbmeta ارائه شده، تأیید بوت تأیید شده را غیرفعال کنید:
```
$ fastboot --disable-verification flash vbmeta vbmeta.img
```

Reboot:
```
$ fastboot reboot
```

در دستگاه‌های اندروید ۱۰ یا جدیدتر که پارتیشن‌های سیستمی کوچک‌تری دارند، ممکن است هنگام فلش کردن GSI پیام خطای زیر ظاهر شود:

    Resizing 'system_a'    FAILED (remote: 'Not enough space to resize partition')
    fastboot: error: Command failed

از دستور زیر برای حذف پارتیشن محصول و آزاد کردن فضا برای پارتیشن سیستم استفاده کنید. این کار فضای اضافی برای فلش کردن GSI فراهم می‌کند:

$ fastboot delete-logical-partition product_a

پسوند _a باید با شناسه اسلات پارتیشن سیستم مطابقت داشته باشد، مانند system_a در این مثال.

به GSI ها کمک کنید

اندروید از مشارکت شما در توسعه GSI استقبال می‌کند. می‌توانید از طریق موارد زیر در بهبود GSI مشارکت کرده و به آن کمک کنید:

ایجاد یک پچ GSI. DESSERT -gsi یک شاخه توسعه نیست و فقط موارد برگزیده از آخرین شاخه انتشار AOSP ( android16-qpr1-release ) را می‌پذیرد، بنابراین برای ارسال یک پچ GSI، باید:
1. وصله را به شاخه‌ی AOSP android16-qpr1-release ارسال کنید.
2. پچ را با دستور DESSERT -gsi انتخاب کنید.
3. برای بررسی Cherrypick، یک اشکال (باگ) ثبت کنید.
گزارش اشکالات GSI یا ارائه پیشنهادات دیگر. دستورالعمل‌های موجود در بخش «گزارش اشکالات» را مرور کنید، سپس اشکالات GSI را مرور یا بایگانی کنید.

نکات

هنگام بوت شدن با GSI، حالت نوار ناوبری توسط vendor overriding پیکربندی می‌شود. می‌توانید با اجرای دستور adb زیر در زمان اجرا، حالت نوار ناوبری را تغییر دهید.

adb exec-out cmd overlay enable-exclusive com.android.internal.systemui.navbar.mode

که در آن mode می‌تواند threebutton ، twobutton ، gestural و غیره باشد.