اختبار VTS باستخدام رمز RAMD لتصحيح الأخطاء

منذ Android 10، تم تغيير نوع صورة النظام العامة (GSI) المستخدَمة لإجراء اختبارات الامتثال لـ CTS على GSI/VTS من userdebug إلى user build لكي يتم توقيع الإصدار. يشكّل ذلك مشكلة لاختبار VTS لأنّه يتطلّب استخدام adb root لتشغيله، ولكن adb root غير متاح على جهاز المستخدم.

تم تقديم ملف ramdisk لتصحيح الأخطاء (أو صورة التمهيد لتصحيح الأخطاء) لتفعيل adb root على جهاز تم إنشاؤه من قِبل المستخدم وتم فتح قفله في برنامج الإقلاع. ويؤدي ذلك إلى تبسيط عملية الاختبار باستخدام ملف الإصدار الخاص بالمستخدم GSI system.img نفسه لاختبار CTS على GSI و اختبار VTS على GSI. لإعداد STS، يبقى استخدام system.img آخر من المصنّعين الأصليّين للأجهزة (OEM) باستخدام userdebug مطلوبًا.

يعرض الجدول التالي التغييرات في نوع الصورة والإصدار لاختبار الامتثال في Android 10.

مجموعة الاختبار	الاختبار باستخدام	إنشاء	تصحيح أخطاء RAMD	adb root؟	تغيير في تنويعة التصميم من الإصدار 9 من Android إلى الإصدار 10
مجموعة أدوات اختبار التوافق (CTS)	نظام المصنّع الأصلي للجهاز	المستخدم	N	N	لم يتغيّر موقفي
CTS-on-GSI	GSI	المستخدم	N	N	userdebug -> user GSI الإصدار موقَّع
STS	نظام المصنّع الأصلي للجهاز	تصحيح أخطاء المستخدم	N	Y	الميزات الجديدة في تطبيق Q
VTS	نظام تحديد المواقع العالمي (GSI)	المستخدم	Y	Y	userdebug -> GSI للمستخدم الإصدار موقَّع

ملاحظة: يتم تحديد التغييرات في ملف ramdisk الخاص بميزة تصحيح الأخطاء في AOSP باستخدام العلامة hashtag debug_ramdisk.

نظرة عامة

يتم إنشاء ملفات الصور الإضافية هذه ضمن مجلد الإنشاء (${ANDROID_PRODUCT_OUT}):

• boot-debug.img
• vendor_boot-debug.img

عند فلاش boot-debug.img على قسم boot في الجهاز، يتم تحميل ملف sepolicy الخاص بالنظام في إصدار userdebug وملف سمات إضافي، وهو adb_debug.prop. يتيح ذلك استخدام adb root مع إصدار المستخدم system.img (إما GSI أو المصنّع الأصلي للجهاز).

بالنسبة إلى صورة الإصدار العام للنواة (GKI) باستخدام الأجهزة التي تحتوي على قسم vendor_boot، يجب عدم فلاش القسم boot-debug.img، لأنّه يجب فلاش قسم boot باستخدام صورة GKI معتمَدة. بدلاً من ذلك، يجب برمجة vendor_boot-debug.img على قسم vendor_boot لتسهيل تصحيح أخطاء ملف ramdisk.

المتطلبات الأساسية لاستخدام ذاكرة وصول عشوائي (RAM) لتصحيح الأخطاء

يقدّم المصنّع الأصلي للجهاز ملف ramdisk لتصحيح الأخطاء، وهو يُجري اختبارات الامتثال. يجب ألا يكون ملف الإصدار موقَّعًا، ولا يمكن استخدامه إلا إذا كان الجهاز غير مقفل.

لن يتم إنشاء ملف ramdisk لتصحيح الأخطاء أو استخدامه لترقية الأجهزة التي تتضمّن ما يلي:

• BOARD_BUILD_SYSTEM_ROOT_IMAGE صحيح
• skip_initramfs في سطر أوامر kernel

ملاحظة: يجب أن تستخدم جميع الأجهزة الجديدة التي تم إطلاقها مع الإصدار 10 من نظام التشغيل Android والإصدارات الأحدث ملف initramfs لتفعيل الأقسام الديناميكية.

الإصدار العام من نظام التشغيل Android 12

ما مِن تعليمات إضافية مطلوبة لاستخدام ملف ramdisk لتصحيح الأخطاء مع ملف Android 12 GSI.

اعتبارًا من 29 أيلول (سبتمبر) 2021، لم تعُد أقراص RAMdisk لفحص الأخطاء بحاجة إلى التحديث باستخدام أداة repack_bootimg. إنّ الإصدار Android 12 GSI بعد SGR1.210929.001 (7777720) سيدمج ملف userdebug_plat_sepolicy.cil المحدّث في system.img الخاص به، ويتجاهل userdebug_plat_sepolicy.cil من قرص تصحيح الأخطاء. يُرجى الاطّلاع على اللوائح التنظيمية للاطّلاع على التفاصيل.

الإصدار العام من Android 11

عند استخدام boot-debug.img أو vendor_boot-debug.img، يتم تحميل ملف system sepolicy من ملف userdebug_plat_sepolicy.cil في ملف debugging ramdisk الخاص بـ boot-debug.img أو vendor_boot-debug.img. لتشغيل صور GSI ، يُرجى دائمًا دمج التغييرات الأخيرة في سياسة الأمان من الفرع android11-gsi لإعادة إنشاء boot-debug.img أو vendor_boot-debug.img.

بدلاً من ذلك، يمكن استخدام أداة repack_bootimg لإعادة إنشاء boot-debug.img أو vendor_boot-debug.img باستخدام سياسة أمان GSI المعدَّلة.

إعادة تجميع ذاكرة وصول عشوائي (RAM) لنظام التشغيل في وضع تصحيح الأخطاء

ملاحظة: يمكنك التوقف عن القراءة الآن في حال استخدام جهاز GSI يعمل بنظام التشغيل Android 12 بالإصدار >= SGR1.210929.001. تحتوي الأقسام التالية على خطوات repack_bootimg، وهي مطلوبة فقط عند استخدام صورة Android 11 الأساسية.

بدلاً من دمج تغييرات سياسة الأمان لإعادة إنشاء boot-debug.img، يمكن للشركاء استخدام repack_bootimg لتعديل ملف سياسة الأمان في GSI إلى boot-debug.img (أو vendor_boot-debug.img إذا كان الجهاز يستخدم GKI).

في ما يلي الخطوات التي يجب اتّباعها:

1. نزِّل otatools.zip من https://ci.android.com. ننصح بالتنزيل من عناصر إنشاء aosp_arm64-userdebug على aosp-main.

2. إعداد بيئة التنفيذ لـ repack_bootimg:

   unzip otatools.zip -d otatools
   export PATH="${PWD}/otatools/bin:${PATH}"
   repack_bootimg --help

3. يمكنك تنزيل userdebug_plat_sepolicy.cil أو boot-with-debug-ramdisk-${KERNEL_VERSION}.img من إصدار GSI الذي تستخدمه. على سبيل المثال، إذا كنت تستخدم ملف GSI لنظام التشغيل arm64 من RJR1.211020.001 (7840830)، يمكنك تنزيله من https://ci.android.com/builds/submitted/7840830/aosp_arm64-user/latest.

   ملاحظة مهمة: لا يُعدّ ${KERNEL_VERSION} ذا صلة هنا. يمكنك استخدام أيّ من boot-with-debug-ramdisk-${KERNEL_VERSION}.img.
   ملاحظة: اعتبارًا من 27‏/09‏/2021، تم إعادة تسمية boot-debug-${KERNEL_VERSION}.img في إصدار GSI إلى boot-with-debug-ramdisk-${KERNEL_VERSION}.img.

4. تحديث الجهاز boot-debug.img أو vendor_boot-debug.img من خلال userdebug_plat_sepolicy.cil:

   repack_bootimg --local --dst_bootimg boot-debug.img \
       --ramdisk_add userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil \
       --ramdisk_add userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil
   # If using GKI
   repack_bootimg --local --dst_bootimg vendor_boot-debug.img \
       --ramdisk_add userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil \
       --ramdisk_add userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil

   مع boot-with-debug-ramdisk-${KERNEL_VERSION}.img:

   repack_bootimg --src_bootimg boot-with-debug-ramdisk-5.4.img \
       --dst_bootimg boot-debug.img \
       --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil \
       --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil
   # If using GKI
   repack_bootimg --src_bootimg boot-with-debug-ramdisk-5.4.img \
       --dst_bootimg vendor_boot-debug.img \
       --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil \
       --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil

   يمكن تعديل مَعلمات --ramdisk_add وفقًا لإعدادات الجهاز. راجِع القسم التالي للحصول على شرح تفصيلي.

   ملاحظة: يُرجى الاطّلاع على repack_bootimg --help للاطّلاع على الاستخدامات والأمثلة التفصيلية.

مسار سياسة sepolicy تصحيح أخطاء المستخدم

ينسخ الإجراء repack_bootimg أعلاه الملف userdebug_plat_sepolicy.cil من مساحة التخزين المؤقت لنظام التشغيل --src_bootimg إلى مساحة التخزين المؤقت لنظام التشغيل --dst_bootimg. ومع ذلك، قد يختلف المسار داخل ذاكرة الوصول العشوائي لتصحيح الأخطاء في إصدارات Android المختلفة. في Android 10 وAndroid 11، يكون المسار first_stage_ramdisk/userdebug_plat_sepolicy.cil للأجهزة التي تحتوي على androidboot.force_normal_boot=1 في سطر أوامر kernel. بخلاف ذلك، يكون المسار هو userdebug_plat_sepolicy.cil.

نفِّذ الأمر التالي للتحقّق مما إذا كان هناك androidboot.force_normal_boot في سطر أوامر kernel:

adb root
adb shell cat /proc/cmdline | grep force_normal_boot

بدءًا من Android 12، يكون المسار ضمن ملف debugging ramdisk هو userdebug_plat_sepolicy.cil دائمًا، بغض النظر عن توفّر androidboot.force_normal_boot=1 في سطر أوامر kernel. يعرض الجدول التالي المسارات ضمن ذاكرة وصول عشوائي (RAM) لتصحيح الأخطاء في إصدارات Android المختلفة.

صورة تصحيح الأخطاء	Android 10	Android 11	Android 12
GKI Boot-with-debug-ramdisk-${KERNEL_VERSION}.img	لا ينطبق	first_stage_ramdisk/userdebug_plat_sepolicy.cil	userdebug_plat_sepolicy.cil
ملف boot-debug.img الخاص بالجهاز	يعتمد على force_normal_boot	يعتمد على force_normal_boot	userdebug_plat_sepolicy.cil
ملف vendor_boot-debug.img الخاص بالجهاز	لا ينطبق	يعتمد على force_normal_boot	userdebug_plat_sepolicy.cil

يمكنك تحديد --ramdisk_add لنسخ الملفات من مسارات مختلفة وإليها باستخدام قائمة بأزواج src_path:dst_path. على سبيل المثال، ينسخ الأمر التاليملف first_stage_ramdisk/userdebug_plat_sepolicy.cil من boot-with-debug-ramdisk-5.4.img على جهاز Android 11 إلىfirst_stage_ramdisk/userdebug_plat_sepolicy.cil ضمن vendor_boot-debug.img على جهاز Android 11.

repack_bootimg \
    --src_bootimg boot-with-debug-ramdisk-5.4.img \
    --dst_bootimg vendor_boot-debug.img \
    --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:first_stage_ramdisk/userdebug_plat_sepolicy.cil

إذا لم يكن هناك androidboot.force_normal_boot=1 في سطر أوامر kernel، فيجب ضبط الأمر على النحو التالي لتغيير مسار الوجهة إلى userdebug_plat_sepolicy.cil.

repack_bootimg \
    --src_bootimg boot-with-debug-ramdisk-5.4.img \
    --dst_bootimg vendor_boot-debug.img \
    --ramdisk_add first_stage_ramdisk/userdebug_plat_sepolicy.cil:userdebug_plat_sepolicy.cil

إضافة تذييل AVB

إذا تم ضبط الصورة التي تم تمريرها إلى --dst_bootimg على أنّها ملف مُجمَّع في AVB ، يجب إضافة تذييل AVB بعد تنفيذ الأمر repack_bootimg.

على سبيل المثال، قبل تشغيل repack_bootimg، نفِّذ الأمر التالي للتحقّق مما إذا كان vendor_boot-debug.img يتضمّن تذييل AVB متسلسلًا.

avbtool info_image --image vendor_boot-debug.img

إذا كان يحتوي في الأصل على تذييل AVB متسلسل، يجب إضافة تذييل AVB بعد تنفيذ الأمر repack_bootimg. يعمل استخدام أي مفتاح اختبار لتوقيع ملف ‎vendor_boot-debug.img لأنّه لا يمكن استخدام ملف ramdisk الخاص بتصحيح الأخطاء إلا عند فتح قفل الجهاز، ما يسمح بتحميل صور موقَّعة باستخدام مفتاح غير مخصّص للإصدار على قسم ‎boot أو vendor_boot.

avbtool add_hash_footer --partition_name vendor_boot \
    --partition_size 100663296 \
    --algorithm SHA256_RSA4096 \
    --key otatools/external/avb/test/data/testkey_rsa4096.pem \
    --image vendor_boot-debug.img

ملاحظة مهمة: يجب تعديل الرقم الذي تم تمريره إلى --partition_size استنادًا إلى حجم القسم الخاص بالجهاز، مثل حجم قسم vendor_boot في الجهاز.