Grund für kanonischen Start

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

Startgründe

Ein Bootloader verwendet eindeutig verfügbare Hardware- und Speicherressourcen, um zu ermitteln, warum ein Gerät neu gestartet wurde, und teilt diese Entscheidung mit, indem er androidboot.bootreason=<reason> zur Android-Kernel-Befehlszeile für den Start hinzufügt. init übersetzt diese Befehlszeile dann, um sie an die Android-Eigenschaft bootloader_boot_reason_prop (ro.boot.bootreason) weiterzuleiten. Bei Geräten, die mit Android 12 oder höher und der Kernelversion 5.10 oder höher gestartet werden, wird androidboot.bootreason=<reason> anstelle der Kernel-Befehlszeile der Boot-Konfiguration hinzugefügt.

Spezifikationen für Bootgründe

In früheren Releases von Android wurde ein Format für Bootgründe angegeben, bei dem keine Leerzeichen verwendet wurden und alle Kleinbuchstaben enthielten. Außerdem gab es wenige Anforderungen (z. B. für die Berichterstellung kernel_panic, watchdog, cold/warm/hard) und es wurden andere besondere Gründe berücksichtigt. Diese lockere Spezifikation führte zur Verbreitung von Hunderten von benutzerdefinierten (und manchmal sinnlosen) Boot-Grundzeichenfolgen, was wiederum zu einer unübersichtlichen Situation führte. Bei der aktuellen Android-Version hat die schiere Menge an nahezu nicht parsbaren oder bedeutungslosen Inhalten, die vom Bootloader eingereicht wurden, zu Compliance-Problemen für bootloader_boot_reason_prop geführt.

Mit der Veröffentlichung von Android 9 erkennt das Android-Team, dass die alte bootloader_boot_reason_prop einen erheblichen Schwung hat und nicht zur Laufzeit neu geschrieben werden kann. Verbesserungen an der Bootgrundspezifikation müssen daher durch Interaktionen mit Bootloader-Entwicklern und Anpassungen am vorhandenen System erfolgen. Das Android-Team setzt sich dafür ein,

  • Wir setzen uns mit Bootloader-Entwicklern in Verbindung, um sie zu folgenden Maßnahmen anzuregen:
    • Gib für bootloader_boot_reason_prop kanonische, analysierbare und erkennbare Gründe an.
    • Sie sind in der Liste system/core/bootstat/bootstat.cpp kBootReasonMap enthalten.
  • Hinzufügen einer kontrollierten und zur Laufzeit überschreibbaren Quelle für system_boot_reason_prop (sys.boot.reason). Diese Eigenschaft kann von einer begrenzten Anzahl von System-Apps (z. B. bootstat und init) überschrieben werden, aber allen Apps können Sepolicy-Rechte zum Lesen zugewiesen werden.
  • Nutzer werden über den Grund für das Starten informiert, dass sie warten müssen, bis die Nutzerdaten bereitgestellt wurden, bevor sie den Inhalt der Eigenschaft „Systemstartgrund“ system_boot_reason_prop vertrauen können.

Warum so spät? bootloader_boot_reason_prop ist zwar schon früh nach dem Start verfügbar, wird aber bei Bedarf von der Android-Sicherheitsrichtlinie blockiert, da es fehlerhafte, nicht parsbare und nicht kanonische Informationen enthält. In den meisten Fällen sollten nur Entwickler mit fundierten Kenntnissen des Boot-Systems 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 werden, enthält system_boot_reason_prop den Wert von bootloader_boot_reason_prop.
  • Nach dem Bereitstellen von userdata kann system_boot_reason_prop aktualisiert werden, um die Compliance-Anforderungen zu erfüllen oder genauere Informationen zu erfassen.

Aus diesem Grund wird in Android 9 der Zeitraum verlängert, bevor der Startgrund offiziell abgerufen werden kann. Er ist nicht mehr sofort beim Start korrekt (mit bootloader_boot_reason_prop), sondern erst verfügbar, nachdem das Nutzerdatenverzeichnis bereitgestellt wurde (mit system_boot_reason_prop).

Die Bootstat-Logik hängt von einer informativeren und konformen bootloader_boot_reason_prop ab. Wenn für diese Eigenschaft ein vorhersehbares Format verwendet wird, wird die Genauigkeit aller kontrollierten Neustart- und Herunterfahrszenarien verbessert. Dadurch werden die Genauigkeit und Bedeutung von system_boot_reason_prop verfeinert und erweitert.

Format des kanonischen Startgrunds

Das kanonische Format für den Startgrund von bootloader_boot_reason_prop unter Android 9 hat folgende Syntax: 

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

Formatierungsregeln:

  • Kleinschreibung
  • Keine Lücken (unterstreichen Sie die Felder)
  • Alle druckbaren Zeichen
  • Durch Kommas getrennte reason-, subreason- und eine oder mehrere detail-Instanzen.
    • Ein erforderlicher reason, der den Grund mit der höchsten Priorität angibt, 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 Untersystem verweisen, um zu ermitteln, welches System zu dem subreason geführt hat. Sie können mehrere detail-Werte angeben, die im Allgemeinen einer Wichtigkeitshierarchie folgen sollten. Es ist jedoch auch zulässig, mehrere detail-Werte mit gleicher Wichtigkeit anzugeben.

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 (erste Spanne vor Beendigung oder Komma) muss aus den folgenden Gründen in Kern-, starke und unmissverständliche Gründe unterteilt sein:

  • kernel set:
    • "watchdog"
    • "kernel_panic"
  • Starker Satz:
    • "recovery"
    • "bootloader"
  • stumpfes Set:
    • "cold": Gibt in der Regel einen vollständigen Neustart aller Geräte an, einschließlich des Arbeitsspeichers.
    • "hard": Gibt in der Regel an, dass der Zustand der Hardware zurückgesetzt wurde und ramoops dauerhafte Inhalte beibehalten sollte.
    • "warm": Gibt in der Regel an, dass der Arbeitsspeicher und die Geräte einen bestimmten Status beibehalten und der ramoops-Speicher (siehe pstore-Treiber im Kernel) nichtflüchtige Inhalte enthält.
    • "shutdown"
    • "reboot". Bedeutet in der Regel, dass der ramoops-Status und der Hardwarestatus unbekannt sind. 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 ein Kernel-Set oder ein Blunt-Set reason angeben. Es wird dringend empfohlen, eine subreason anzugeben, sofern diese ermittelt werden kann. Wenn Sie beispielsweise die Ein‑/Aus-Taste lange gedrückt haben und dabei möglicherweise ein ramoops-Back-up durchgeführt wurde, lautet der Startgrund "reboot,longkey".

Keine erste Spanne reason darf Teil eines subreason oder detail sein. Da Gründe für vom Kernel festgelegte Zeitüberschreitungen jedoch nicht vom Nutzerbereich stammen können, kann "watchdog" nach einem solchen Grund zusammen mit einem Detail zur 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 untergeordnetem Grund

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, wenn die Kombination die zugehörige Bedingung genau widerspiegelt. Beispiele für reservierte Kombinationen:

  • "reboot,userrequested"
  • "shutdown,userrequested"
  • "shutdown,thermal" (von thermald)
  • "shutdown,battery"
  • "shutdown,battery,thermal" (von 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 Boot-Gründe, die entweder vom Bootloader stammen oder im kanonischen Boot-Grund aufgezeichnet wurden, müssen im Abschnitt kBootReasonMap von system/core/bootstat/bootstat.cpp aufgezeichnet werden. Die Liste kBootReasonMap enthält sowohl konforme als auch nicht konforme Gründe. Bootloader-Entwickler sollten hier nur neue konforme Gründe registrieren. Nicht konforme Gründe sollten nur registriert werden, wenn das Produkt bereits ausgeliefert wurde und nicht mehr geändert werden kann.

Wir empfehlen dringend, vorhandene, konforme Einträge in system/core/bootstat/bootstat.cpp zu verwenden und mit der Verwendung eines nicht konformen Strings zurückhaltend zu sein. Als Richtlinie gilt:

  • OK, "kernel_panic" über den Bootloader melden, da bootstat ramoops auf kernel_panic signatures prüfen kann, um die untergeordneten Gründe in der kanonischen system_boot_reason_prop zu verfeinern.
  • Nicht zulässig: Melden Sie keinen nicht konformen String in kBootReasonMap, z. B. "panic") aus dem Bootloader, da dies die Möglichkeit zur Optimierung 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 Personen bedeutet, die mit der Technologie nicht vertraut sind, und prüfen Sie, ob eine aussagekräftigere subreason verfügbar ist.

Einhaltung des Bootgrunds prüfen

Derzeit bietet Android keinen aktiven CTS-Test, mit dem alle möglichen Boot-Gründe eines Bootloaders korrekt ausgelöst oder geprüft werden können. Partner können jedoch versuchen, einen passiven Test auszuführen, um die Kompatibilität zu bestimmen.

Daher müssen Bootloader-Entwickler freiwillig den oben beschriebenen Regeln und Richtlinien entsprechen, um die Anforderungen an die Bootloader-Compliance zu erfüllen. Wir empfehlen diesen Entwicklern, zum AOSP beizutragen (insbesondere zu system/core/bootstat/bootstat.cpp) und diese Gelegenheit als Forum für Diskussionen zu Problemen mit dem Bootgrund zu nutzen.