سبب التمهيد الأساسي

يتضمّن Android 9 التغييرات التالية على مواصفات سبب تشغيل برنامج الإقلاع.

أسباب التشغيل

يستخدم برنامج الإقلاع موارد الأجهزة والذاكرة المتاحة بشكل فريد لتحديد سبب إعادة تشغيل الجهاز، ثم يبلِّغ عن هذا التحديد من خلال إضافة androidboot.bootreason=<reason> إلى سطر أوامر kernel في Android عند تشغيله. init بعد ذلك، يترجم سطر الأوامر هذا لنشره في خاصية Android‏ bootloader_boot_reason_prop (ro.boot.bootreason). بالنسبة إلى الأجهزة التي يتم تشغيلها باستخدام Android 12 أو إصدار أحدث، باستخدام إصدار النواة 5.10 أو إصدار أحدث، تتم إضافة androidboot.bootreason=<reason> إلى bootconfig بدلاً من سطر أوامر kernel.

مواصفات سبب التشغيل

حدّدت الإصدارات السابقة من Android تنسيقًا لسبب التشغيل لا يستخدم أي مسافات، ويكون بأحرف صغيرة بالكامل، ويتضمّن عددًا قليلاً من المتطلبات (مثل الإبلاغ عن kernel_panic وwatchdog و cold/warm/hard)، ويسمح بأسباب فريدة أخرى. أدّت هذه المواصفات غير الدقيقة إلى انتشار مئات من سلاسل أسباب التشغيل المخصّصة (وأحيانًا غير المنطقية)، ما أدّى بدوره إلى حالة غير قابلة للإدارة. اعتبارًا من إصدار Android الحالي ، أدّى الزخم الهائل للمحتوى الذي لا يمكن تحليله أو غير المنطقي الذي يقدّمه برنامج الإقلاع إلى حدوث مشاكل في الامتثال لـ bootloader_boot_reason_prop.

مع إصدار Android 9، يدرك فريق Android أنّ السمة القديمة bootloader_boot_reason_prop لها زخم كبير ولا يمكن إعادة كتابتها في وقت التشغيل. لذلك، يجب أن تأتي أي تحسينات على مواصفات سبب التشغيل من التفاعلات مع مطوّري برنامج الإقلاع والتعديلات على النظام الحالي. لتحقيق ذلك، يقوم فريق Android بما يلي:

• التواصل مع مطوّري برنامج الإقلاع لتشجيعهم على:
  • تقديم أسباب أساسية قابلة للتحليل والتمييز إلى bootloader_boot_reason_prop.
  • المشاركة في قائمة system/core/bootstat/bootstat.cpp kBootReasonMap
• إضافة مصدر خاضع للتحكّم وقابل لإعادة الكتابة في وقت التشغيل لـ system_boot_reason_prop (sys.boot.reason). يمكن لمجموعة محدودة من تطبيقات النظام (مثل bootstat و init) إعادة كتابة هذه الخاصية، ولكن يمكن منح جميع التطبيقات حقوق sepolicy لقراءتها.
• إبلاغ المستخدمين بسبب التشغيل بالانتظار إلى ما بعد تحميل بيانات المستخدم قبل الوثوق بالمحتوى في خاصية سبب تشغيل النظام system_boot_reason_prop.

لماذا هذا التأخير؟ على الرغم من أنّ bootloader_boot_reason_prop متاحة في وقت مبكر من عملية التشغيل، فإنّ سياسة أمان Android تحظرها حسب الحاجة لأنّها تمثّل معلومات غير دقيقة وغير قابلة للتحليل وغير أساسية. في معظم الحالات، يجب أن يتمكّن المطوّرون الذين لديهم معرفة عميقة بنظام التشغيل فقط من الوصول إلى هذه المعلومات. لا يمكن الحصول على واجهة برمجة تطبيقات محسّنة وقابلة للتحليل وأساسية لسبب التشغيل باستخدام system_boot_reason_prop بشكل موثوق ودقيق إلا بعد تحميل بيانات المستخدم. على وجه التحديد:

• قبل تحميل بيانات المستخدم، system_boot_reason_prop ستتضمّن القيمة من bootloader_boot_reason_prop.
• بعد تحميل بيانات المستخدم، قد يتم تعديل system_boot_reason_prop لتكون متوافقة أو لتقديم معلومات أكثر دقة.

لهذا السبب، يمدّد Android 9 الفترة الزمنية قبل أن يتم الحصول رسميًا على سبب التشغيل، ويغيّرها من أن تكون دقيقة على الفور عند التشغيل (باستخدام bootloader_boot_reason_prop) إلى أن تكون متاحة فقط بعد تحميل بيانات المستخدم (باستخدام system_boot_reason_prop).

تعتمد منطق `Bootstat` على أكثر إفادة وتوافقًا bootloader_boot_reason_prop. عندما تستخدم هذه الخاصية تنسيقًا يمكن توقّعه، فإنّها تحسّن دقة جميع سيناريوهات إعادة التشغيل والإيقاف الخاضعة للتحكّم، ما يؤدي بدوره إلى تحسين وتوسيع دقة ومعنى system_boot_reason_prop.

تنسيق سبب التشغيل الأساسي

يستخدم تنسيق سبب التشغيل الأساسي لـ bootloader_boot_reason_prop في Android 9 البنية التالية:

<reason>,<subreason>,<detail>…

قواعد التنسيق:

• الأحرف الصغيرة
• بدون مسافات (استخدِم التسطير)
• جميع الأحرف القابلة للطباعة
• reason وsubreason وواحدة أو أكثر من حالات detail مفصولة بفواصل
  • reason مطلوبة تمثّل السبب الأعلى أولوية لإعادة تشغيل الجهاز أو إيقافه
  • subreason اختيارية تمثّل ملخصًا قصيرًا لـ سبب إعادة تشغيل الجهاز أو إيقافه (أو من أعاد تشغيل الجهاز أو أوقفه)
  • واحدة أو أكثر من قيم detail الاختيارية قد تشير detail إلى نظام فرعي للمساعدة في تحديد النظام المحدد الذي أدّى إلى subreason. يمكنك تحديد قيم متعددة، والتي يجب أن تتبع بشكل عام تسلسلاً هرميًا للأهمية.detail ومع ذلك، من المقبول أيضًا الإبلاغ عن قيم متعددة detail بنفس الأهمية.

تُعد القيمة الفارغة لـ bootloader_boot_reason_prop غير قانونية (لأنّها تسمح لوكلاء آخرين بإدخال سبب التشغيل بعد ذلك).

متطلبات السبب

يجب أن تكون القيمة المقدّمة لـ reason (المدى الأول، قبل الإنهاء أو الفاصلة) من المجموعة التالية المقسّمة إلى أسباب kernel والأسباب القوية والأسباب المباشرة:

• مجموعة kernel:
  • "watchdog"
  • "kernel_panic"
• المجموعة القوية:
  • "recovery"
  • "bootloader"
• المجموعة المباشرة:
  • "cold". يشير هذا الخيار بشكل عام إلى إعادة ضبط كاملة لجميع الأجهزة، بما في ذلك الذاكرة.
  • "hard". يشير هذا الخيار بشكل عام إلى إعادة ضبط حالة الأجهزة ويجب أن تحتفظ ramoops بالمحتوى الثابت.
  • "warm". يشير هذا الخيار بشكل عام إلى أنّ الذاكرة والأجهزة تحتفظ ببعض الحالة، وأنّ ramoops (راجِع pstore برنامج التشغيل في kernel) تحتوي على محتوى ثابت.
  • "shutdown"
  • "reboot". يعني هذا الخيار بشكل عام أنّ حالة ramoops غير معروفة وحالة الأجهزة غير معروفة. هذه القيمة هي قيمة شاملة لأنّ القيم cold وhard وwarm تقدّم مؤشرات على مدى إعادة ضبط الجهاز.

يجب أن تقدّم برامج الإقلاع مجموعة kernel أو مجموعة مباشرة reason، و ننصح بشدة بتقديم subreason إذا كان من الممكن تحديدها. على سبيل المثال، سيتم تحديد سبب التشغيل "reboot,longkey" للضغط مع الاستمرار على مفتاح التشغيل الذي قد يكون لديه أو ليس لديه ramoops نسخة احتياطية.

لا يمكن أن يكون reason في المدى الأول جزءًا من أي subreason أو detail. ومع ذلك، بما أنّه لا يمكن لمساحة المستخدم إنشاء أسباب مجموعة kernel، يمكن إعادة استخدام "watchdog" بعد سبب مجموعة مباشرة، بالإضافة إلى تفاصيل المصدر (على سبيل المثال، "reboot,watchdog,service_manager_unresponsive" أو "reboot,software,watchdog").

يجب ألا تتطلّب أسباب التشغيل معرفة داخلية متخصّصة لفك رموزها و/أو يجب أن تكون قابلة للقراءة من قِبل المستخدمين مع تقرير سهل الفهم. أمثلة: "shutdown,vbxd" (سيئ)، "shutdown,uv" (أفضل)، "shutdown,undervoltage" (مفضّل).

مجموعات السبب والسبب الفرعي

تحتفظ Android بمجموعة من مجموعات reason-subreason التي يجب عدم استخدامها بشكل مفرط في الاستخدام العادي، ولكن يمكن استخدامها على أساس كل حالة على حدة إذا كانت المجموعة تعكس بدقة الحالة المرتبطة. تشمل أمثلة المجموعات المحفوظة ما يلي:

• "reboot,userrequested"
• "shutdown,userrequested"
• "shutdown,thermal" (من thermald)
• "shutdown,battery"
• "shutdown,battery,thermal" (من BatteryStatsService)
• "reboot,adb"
• "reboot,shell"
• "reboot,bootloader"
• "reboot,recovery"

لمزيد من التفاصيل، يُرجى الرجوع إلى kBootReasonMap في system/core/bootstat/bootstat.cpp وسجلّ تغييرات git المرتبط في مستودع مصدر Android.

الإبلاغ عن أسباب التشغيل

يجب تسجيل جميع أسباب التشغيل، سواء من برنامج الإقلاع أو المسجّلة في سبب التشغيل الأساسي، في قسم kBootReasonMap من system/core/bootstat/bootstat.cpp. تتضمّن قائمة kBootReasonMap مزيجًا من الأسباب المتوافقة والأسباب القديمة غير المتوافقة. يجب أن يسجّل مطوّرو برنامج الإقلاع الأسباب الجديدة المتوافقة فقط هنا (ويجب ألا يسجّلوا الأسباب غير المتوافقة ما لم يتم شحن المنتج بالفعل ولا يمكن تغييره).

ننصح بشدة باستخدام الإدخالات الحالية المتوافقة في system/core/bootstat/bootstat.cpp والتحكّم في استخدام سلسلة غير متوافقة. كإرشادات، يُرجى مراعاة ما يلي:

• مقبول الإبلاغ عن "kernel_panic" من برنامج الإقلاع، لأنّ bootstat قد تتمكّن من فحص ramoops بحثًا عن kernel_panic signatures لتحسين الأسباب الفرعية في system_boot_reason_prop الأساسية.
• غير مقبول الإبلاغ عن سلسلة غير متوافقة في kBootReasonMap (مثل "panic") من برنامج الإقلاع، لأنّ ذلك سيؤدي في النهاية إلى إيقاف إمكانية تحسين reason.

على سبيل المثال، إذا كانت kBootReasonMap تحتوي على "wdog_bark"، يجب أن يقوم مطوّر برنامج الإقلاع بما يلي:

• تغييرها إلى "watchdog,bark" وإضافتها إلى القائمة في kBootReasonMap
• تحديد معنى "bark" للمستخدمين غير الملمّين بالـ تكنولوجيا وتحديد ما إذا كان هناك subreason أكثر منطقية

التحقّق من امتثال سبب التشغيل

في الوقت الحالي، لا يقدّم Android اختبار CTS نشطًا يمكنه تشغيل جميع أسباب التشغيل المحتملة التي يمكن أن يقدّمها برنامج الإقلاع أو فحصها بدقة ، ولكن لا يزال بإمكان الشركاء محاولة إجراء اختبار غير نشط لتحديد التوافق.

نتيجةً لذلك، يتطلّب امتثال برنامج الإقلاع من مطوّري برنامج الإقلاع الالتزام طوعًا بروح القواعد والإرشادات الموضّحة أعلاه. نحثّ هؤلاء المطوّرين على المساهمة في AOSP (وتحديدًا في system/core/bootstat/bootstat.cpp) واستخدام هذه الفرصة كمنتدى للمناقشات حول مشاكل سبب التشغيل.