Grund für kanonischen Start

Unter Android 9 wurden die folgenden Änderungen an der Spezifikation des Bootloader-Bootgrunds vorgenommen.

Startgründe

Ein Bootloader ermittelt anhand der einmalig verfügbaren Hardware- und Speicherressourcen, warum ein Gerät neu gestartet wurde, und sendet diese Entscheidung dann, indem er zum Start androidboot.bootreason=<reason> zur Android-Kernel-Befehlszeile hinzufügt. init übersetzt diese Befehlszeile dann so, dass sie an das Android-Attribut bootloader_boot_reason_prop (ro.boot.bootreason) weitergegeben wird. Bei Geräten, die mit Android 12 oder höher auf den Markt gebracht werden und Kernel-Version 5.10 oder höher verwenden, wird „bootconfig“ anstelle der Kernel-Befehlszeile androidboot.bootreason=<reason> hinzugefügt.

Spezifikationen für Bootgründe

In früheren Releases von Android wurde ein Format für den Startgrund angegeben, bei dem keine Leerzeichen verwendet wurden, alles aus Kleinbuchstaben stammte und wenige Anforderungen erfüllte (z. B. für die Berichterstellung kernel_panic, watchdog, cold/warm/hard) und andere besondere Gründe berücksichtigten. Diese lockere Spezifikation führte zur Verbreitung von Hunderten von benutzerdefinierten (und manchmal bedeutungslosen) Strings für Startgründe, was wiederum zu einer unüberschaubaren Situation führte. Mit der aktuellen Android-Version hat die schiere Dynamik der vom Bootloader erfassten nahezu nicht parsbaren oder bedeutungslosen Inhalte zu Complianceproblemen bei bootloader_boot_reason_prop geführt.

Mit dem Release von Android 9 erkennt das Android-Team, dass die Legacy-bootloader_boot_reason_prop eine erhebliche Dynamik aufweist und während der Laufzeit nicht neu geschrieben werden kann. Alle Verbesserungen der Spezifikation des Bootgrunds müssen daher aus Interaktionen mit Bootloader-Entwicklern und Änderungen am vorhandenen System stammen. Zu diesem Zweck setzt sich das Android-Team für Folgendes ein:

  • Interaktionen mit Bootloader-Entwicklern, um sie zu Folgendem zu ermutigen:
    • Gib für bootloader_boot_reason_prop kanonische, geparste und erkennbare Gründe an.
    • Nehmen Sie an der kBootReasonMap-Liste von system/core/bootstat/bootstat.cpp teil.
  • Hinzufügen einer kontrollierten und zur Laufzeit überschreibbaren Quelle von system_boot_reason_prop (sys.boot.reason). Eine begrenzte Anzahl von System-Apps (z. B. bootstat und init) kann dieses Attribut neu schreiben, aber alle Apps können sepolicy-Rechte zum Lesen erhalten.
  • Nutzer werden über den Startgrund informiert, dass sie nach dem Bereitstellen der Nutzerdaten warten müssen, bevor sie dem Inhalt im Attribut system_boot_reason_prop des Systemstartgrunds als vertrauenswürdig einstufen.

Warum so spät? bootloader_boot_reason_prop ist zwar frühzeitig beim Booten verfügbar, wird aber nach Bedarf durch die Android-Sicherheitsrichtlinie blockiert, da es ungenaue, nicht geparste und nicht kanonische Informationen darstellt. In den meisten Fällen sollten nur Entwickler mit umfassenden Kenntnissen des Bootsystems auf diese Informationen zugreifen müssen. Eine optimierte, parsbare und kanonische API für den Start mit system_boot_reason_prop kann erst nach der Bereitstellung der Nutzerdaten zuverlässig und genau erfasst werden. Im Detail:

  • Bevor Nutzerdaten bereitgestellt wurden, enthält system_boot_reason_prop den Wert von bootloader_boot_reason_prop.
  • Nachdem die Nutzerdaten bereitgestellt wurden, wird system_boot_reason_prop möglicherweise aktualisiert, damit es konform ist oder genauere Informationen zur Verfügung stehen.

Aus diesem Grund verlängert Android 9 den Zeitraum, bevor der Startgrund offiziell ermittelt werden kann, und ist nicht mehr sofort im Bootmodus (mit bootloader_boot_reason_prop) verfügbar, sondern erst verfügbar, nachdem die Nutzerdaten bereitgestellt wurden (mit system_boot_reason_prop).

Die Bootstat-Logik hängt von einer informativeren und konformeren bootloader_boot_reason_prop ab. Wenn dieses Attribut ein vorhersehbares Format verwendet, verbessert es die Genauigkeit aller kontrollierten Neustarts und Szenarien, was wiederum die Genauigkeit und Bedeutung von system_boot_reason_prop verfeinert und erweitert.

Format des kanonischen Startgrunds

Das Format für den kanonischen Startgrund für bootloader_boot_reason_prop in Android 9 verwendet die folgende Syntax: 

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

Formatierungsregeln:

  • Kleinschreibung
  • Keine Leerzeichen (unterstrichen)
  • Alle druckbaren Zeichen
  • Kommagetrennte reason- und subreason-Instanzen sowie eine oder mehrere detail-Instanzen.
    • Ein erforderlicher reason, der den Grund mit der höchsten Priorität darstellt, warum das Gerät neu gestartet oder heruntergefahren werden musste.
    • Ein optionaler subreason, der eine kurze Zusammenfassung der Gründe darstellt, aus denen das Gerät neu gestartet oder heruntergefahren werden musste (oder wer es neu gestartet oder heruntergefahren hat).
    • Ein oder mehrere optionale detail-Werte. Ein detail kann auf ein Subsystem verweisen, um festzustellen, welches spezifische System zur subreason geführt hat. Sie können mehrere detail-Werte angeben, die im Allgemeinen einer wichtigen Hierarchie folgen. Es ist jedoch auch zulässig, mehrere detail-Werte von gleicher Bedeutung zu melden.

Ein leerer Wert für bootloader_boot_reason_prop gilt als illegal, da dadurch andere Agenten nachträglich einen Startgrund einfügen können.

Anforderungen an den Grund

Der für reason angegebene Wert (erster Span vor der Beendigung oder ein Komma) muss der folgenden Gruppe entsprechen, unterteilt in Kernel-, strong- und blunt-Gründe:

  • Kernel-Satz:
    • "watchdog"
    • "kernel_panic"
  • Starker Satz:
    • "recovery"
    • "bootloader"
  • stumpfes Set:
    • "cold": Zeigt in der Regel an, dass alle Geräte vollständig zurückgesetzt werden, einschließlich des Arbeitsspeichers.
    • "hard". Gibt im Allgemeinen an, dass der Status der Hardware zurückgesetzt wurde und ramoops persistente Inhalte beibehalten soll.
    • "warm". Gibt im Allgemeinen an, dass der Arbeitsspeicher und die Geräte einen Status beibehalten und der Sicherungsspeicher ramoops (siehe Treiber pstore im Kernel) nichtflüchtigen Inhalt enthält.
    • "shutdown"
    • "reboot": Bedeutet im Allgemeinen, dass der Status ramoops unbekannt und Hardwarestatus unbekannt ist. Dieser Wert ist ein universeller Wert, da die Werte cold, hard und warm Hinweise auf die Tiefe der Zurücksetzung für das Gerät geben.

Bootloader müssen einen Kernel- oder Blunt-Set reason bereitstellen. Es wird dringend empfohlen, einen subreason anzugeben, falls dieser ermittelt werden kann. Beispiel: Wenn für langes Drücken der Ein/Aus-Taste die Sicherung ramoops verwendet wird oder nicht, wird der Startgrund "reboot,longkey" angegeben.

reason des ersten Spans darf in keinem subreason- oder detail-Element enthalten sein. Da Kernel-Set-Gründe jedoch nicht vom Nutzerbereich erzeugt werden können, kann "watchdog" nach einem Blunt-Set-Grund zusammen mit einem Detail der Quelle (z. B. "reboot,watchdog,service_manager_unresponsive" oder "reboot,software,watchdog") wiederverwendet werden.

Bootgründe sollten kein internes Expertenwissen erfordern und/oder für Menschen lesbar sein und einen intuitiven Bericht erstellen. Beispiele: "shutdown,vbxd" (schlecht), "shutdown,uv" (besser), "shutdown,undervoltage" (bevorzugt).

Kombinationen aus Grund und Untergrund

Android reserviert eine Reihe von reason-subreason-Kombinationen, die bei normaler Nutzung nicht überlastet werden sollten, aber von Fall zu Fall verwendet werden können, sofern die Kombination die zugehörige Bedingung genau erfüllt. Beispiele für reservierte Kombinationen:

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

Weitere Informationen finden Sie unter kBootReasonMap in system/core/bootstat/bootstat.cpp und im zugehörigen Git-Änderungsverlauf im Android-Quell-Repository.

Startgründe melden

Alle Bootgründe, entweder über den Bootloader oder im kanonischen Bootgrund, müssen im Abschnitt kBootReasonMap von system/core/bootstat/bootstat.cpp angegeben werden. Die kBootReasonMap-Liste ist eine Mischung aus Gründen, die den Richtlinien entsprechen und denen nicht konformer Legacy-Versionen entsprechen. Bootloader-Entwickler sollten hier nur neue konforme Gründe angeben. Nicht konforme Gründe sollten nur angegeben werden, wenn das Produkt bereits versendet wurde und nicht mehr geändert werden kann.

Es wird dringend empfohlen, in system/core/bootstat/bootstat.cpp vorhandene, konforme Einträge zu verwenden und vor der Verwendung eines nicht konformen Strings Zurückhaltung zu praktizieren. Als Richtlinie gilt:

  • OK, um "kernel_panic" aus dem Bootloader zu melden, da bootstat möglicherweise ramoops auf kernel_panic signatures prüfen kann, um die Untergründe auf die kanonische system_boot_reason_prop einzugrenzen.
  • Es ist nicht zulässig, einen nicht konformen String in kBootReasonMap zu melden (z. B. "panic") aus dem Bootloader, da dies letztendlich die Möglichkeit der Verfeinerung von reason beeinträchtigt.

Wenn kBootReasonMap beispielsweise "wdog_bark" enthält, sollte ein Bootloader-Entwickler:

  • Ändern Sie die Einstellung in "watchdog,bark" und fügen Sie sie der Liste in kBootReasonMap hinzu.
  • Überlegen Sie, was "bark" für diejenigen bedeutet, die nicht mit der Technologie vertraut sind, und prüfen Sie, ob eine aussagekräftigere subreason verfügbar ist.

Compliance des Bootgrunds prüfen

Derzeit bietet Android keinen aktiven CTS-Test, der alle möglichen Startgründe, die ein Bootloader angeben könnte, genau auslösen oder prüfen kann. Partner können aber trotzdem versuchen, einen passiven Test zur Ermittlung der Kompatibilität durchzuführen.

Deshalb müssen Bootloader-Entwickler sich freiwillig an die oben beschriebenen Regeln und Richtlinien halten. Wir fordern diese Entwickler dazu auf, zum AOSP (insbesondere für system/core/bootstat/bootstat.cpp) beizutragen und diese Gelegenheit als Forum für Diskussionen über Probleme beim Booten zu nutzen.