Kanonisches Boot-Ergebnis

Android 9 enthält die folgenden Änderungen an der Boot-Grundspezifikation des Bootloaders.

Gründe für das Ausführen

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 Kernelbefehlszeile der Boot-Konfiguration hinzugefügt.

Spezifikationen für den Bootgrund

In früheren Android-Releases wurde ein Format für den Startgrund angegeben, das keine Leerzeichen enthielt, nur Kleinbuchstaben verwendete, nur wenige Anforderungen enthielt (z. B. für die Meldung von kernel_panic, watchdog, cold/warm/hard) und andere eindeutige Gründe zuließ. 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 arbeiten mit Bootloader-Entwicklern zusammen, um sie zu folgenden Maßnahmen anzuregen:
    • Geben Sie kanonische, parsbare und erkennbare Gründe für bootloader_boot_reason_prop 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 sind, 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 Bootgrund mit system_boot_reason_prop kann nur nach dem Bereitstellen von userdata zuverlässig und korrekt abgerufen werden. Im Detail:

  • Bevor userdata bereitgestellt wurde, enthält system_boot_reason_prop den Wert aus 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 die Zeitspanne verlängert, bevor der Grund für den Start 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. Dies wiederum optimiert und erweitert die Genauigkeit und Bedeutung von system_boot_reason_prop.

Kanonisches Format für den Bootgrund

Das kanonische Format für den Bootgrund für bootloader_boot_reason_prop unter Android 9 hat die 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.
    • Optionale subreason, die eine kurze Zusammenfassung enthält, warum das Gerät neu gestartet oder heruntergefahren werden musste (oder wer das Gerät neu gestartet oder heruntergefahren hat).
    • Einer 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 ungültig, da andere Kundenservicemitarbeiter so nachträglich einen Startgrund einschleusen können.

Anforderungen an den Grund

Der für reason angegebene Wert (erste Spanne vor dem Ende oder Komma) muss aus den folgenden Gründen in Kern-, starke und unmissverständliche Gründe unterteilt sein:

  • kernel set:
    • "watchdog"
    • "kernel_panic"
  • starkes Set:
    • "recovery"
    • "bootloader"
  • stumpfes Set:
    • "cold": Gibt in der Regel einen vollständigen Reset 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 Sammelwert, da die Werte cold, hard und warm Aufschluss über den Umfang des Zurücksetzens des Geräts 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 möglicherweise ein ramoops-Back-up vorhanden ist, wird als Grund für das Starten "reboot,longkey" angegeben.

Keine erste Spanne reason darf Teil eines subreason oder detail sein. Da Gründe für vom Kernel festgelegte Status 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.

Die Gründe für das Starten sollten nicht decodiert werden müssen und/oder sollten in einem intuitiven Bericht menschenlesbar sein. 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.

Gründe für den Start 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 Anhaltspunkt gilt:

  • OK, "kernel_panic" über den Bootloader melden, da bootstat ramoops für kernel_panic signatures prüfen kann, um die untergeordneten Gründe in die kanonische 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 Folgendes tun:

  • Wechseln Sie zu "watchdog,bark" und fügen Sie die Datei der Liste in kBootReasonMap hinzu.
  • Überlegen Sie, was "bark" für Nutzer 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.