Raison de démarrage canonique

Android 9 inclut les modifications suivantes apportées à la spécification de la raison de démarrage du bootloader.

Motifs de démarrage

Un bootloader utilise des ressources matérielles et de mémoire disponibles uniquement pour déterminer pourquoi un appareil a redémarré, puis communique cette détermination en ajoutant androidboot.bootreason=<reason> à la ligne de commande du kernel Android pour son lancement. init traduit ensuite cette ligne de commande pour la propager à la propriété Android bootloader_boot_reason_prop (ro.boot.bootreason). Pour les appareils lancés avec Android 12 ou version ultérieure, utilisant la version 5.10 du kernel ou une version ultérieure, androidboot.bootreason=<reason> est ajouté à bootconfig au lieu de la ligne de commande du kernel.

Spécifications du motif de démarrage

Les versions précédentes d'Android spécifiaient un format de raison de démarrage qui n'utilisait pas d'espaces, était en minuscules, incluait peu d'exigences (par exemple, pour signaler kernel_panic, watchdog, cold/warm/hard) et qui prévoyait d'autres raisons uniques. Cette spécification peu stricte a entraîné la prolifération de centaines de chaînes de raison de démarrage personnalisées (et parfois dénuées de sens), ce qui a à son tour entraîné une situation incontrôlable. Depuis la version actuelle d'Android, la simple dynamique du contenu presque illisible ou sans signification enregistré par le bootloader a créé des problèmes de conformité pour bootloader_boot_reason_prop.

Avec la version Android 9, l'équipe Android reconnaît que l'ancienne bootloader_boot_reason_prop a un élan important et ne peut pas être réécrite au moment de l'exécution. Toute amélioration de la spécification de la raison de démarrage doit donc provenir d'interactions avec les développeurs du bootloader et d'ajustements du système existant. À cette fin, l'équipe Android:

  • Interagir avec les développeurs de bootloader pour les encourager à :
    • Fournissez des raisons canoniques, analysables et reconnaissables à bootloader_boot_reason_prop.
    • Participer à la liste system/core/bootstat/bootstat.cpp kBootReasonMap.
  • Ajout d'une source contrôlée et réécrite au moment de l'exécution de system_boot_reason_prop (sys.boot.reason). Un ensemble limité d'applications système (telles que bootstat et init) peut réécrire cette propriété, mais toutes les applications peuvent se voir accorder des droits sepolicy pour la lire.
  • Informez les utilisateurs de la raison de démarrage pour qu'ils attendent que userdata soit installé avant de faire confiance au contenu de la propriété system_boot_reason_prop de la raison de démarrage du système.

Pourquoi si tard ? Bien que bootloader_boot_reason_prop soit disponible dès le démarrage, il est bloqué par la stratégie de sécurité Android en fonction des besoins, car il représente des informations inexactes, non analysables et non canoniques. Dans la plupart des cas, seuls les développeurs ayant une connaissance approfondie du système de démarrage doivent avoir accès à ces informations. Une API raffinée, analysable et canonique pour la raison de démarrage avec system_boot_reason_prop ne peut être détectée de manière fiable et précise que après le montage de userdata. Plus spécifiquement :

  • Avant le montage de userdata, system_boot_reason_prop contient la valeur de bootloader_boot_reason_prop.
  • Une fois userdata installé, system_boot_reason_prop peut être mis à jour pour être conforme ou pour fournir des informations plus précises.

Pour cette raison, Android 9 prolonge la période avant que la raison de démarrage puisse être officiellement acquise, passant d'une précision immédiate au démarrage (avec bootloader_boot_reason_prop) à une disponibilité uniquement après le montage de userdata (avec system_boot_reason_prop).

La logique Bootstat dépend d'un bootloader_boot_reason_prop plus informatif et conforme. Lorsque cette propriété utilise un format prévisible, elle améliore la précision de tous les scénarios de redémarrage et d'arrêt contrôlés, ce qui affine et étend la précision et la signification de system_boot_reason_prop.

Format du motif de démarrage canonique

Le format canonique de la raison de démarrage pour bootloader_boot_reason_prop dans Android 9 utilise la syntaxe suivante: 

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

Règles de mise en forme:

  • Tout en minuscules
  • Pas de valeurs vides (utiliser le soulignement)
  • Tous les caractères imprimables
  • reason, subreason et une ou plusieurs instances detail séparés par une virgule.
    • reason obligatoire qui représente la raison de priorité la plus élevée pour laquelle l'appareil a dû redémarrer ou s'arrêter.
    • subreason facultatif qui représente un bref résumé des raisons pour lesquelles l'appareil a dû redémarrer ou s'arrêter (ou qui l'a fait).
    • Une ou plusieurs valeurs detail facultatives. Un detail peut pointer vers un sous-système pour aider à déterminer quel système spécifique a généré le subreason. Vous pouvez spécifier plusieurs valeurs detail, qui doivent généralement suivre une hiérarchie d'importance. Toutefois, il est également acceptable de signaler plusieurs valeurs detail d'égale importance.

Une valeur vide pour bootloader_boot_reason_prop est considérée comme illégale (car elle permet à d'autres agents d'injecter une raison de démarrage après coup).

Exigences concernant le motif

La valeur donnée pour reason (première étendue, avant la fin ou la virgule) doit appartenir à l'ensemble suivant, divisé en raisons de noyau, fortes et directes:

  • kernel set:
    • "watchdog"
    • "kernel_panic"
  • Ensemble fort :
    • "recovery"
    • "bootloader"
  • ensemble de pointes émoussées :
    • "cold" : indique généralement une réinitialisation complète de tous les appareils, y compris de la mémoire.
    • "hard". Indique généralement que l'état du matériel a été réinitialisé et que ramoops doit conserver le contenu persistant.
    • "warm". Indique généralement que la mémoire et les appareils conservent un état, et que le stockage en arrière-plan ramoops (voir le pilote pstore dans le noyau) contient du contenu persistant.
    • "shutdown"
    • "reboot". En général, cela signifie que l'état ramoops est inconnu et que l'état matériel est inconnu. Cette valeur est une valeur générique, car les valeurs cold, hard et warm fournissent des indices sur la profondeur de la réinitialisation de l'appareil.

Les bootloaders doivent fournir un ensemble de kernel ou un ensemble reason brut, et sont vivement encouragés à fournir un subreason si cela peut être déterminé. Par exemple, un appui prolongé sur le bouton Marche/Arrêt qui peut ou non avoir une sauvegarde ramoops aura le motif de démarrage "reboot,longkey".

Aucun reason de première étendue ne peut faire partie d'un subreason ou d'un detail. Toutefois, comme les raisons de configuration du noyau ne peuvent pas être générées par l'espace utilisateur, "watchdog" peut être réutilisé après une raison de configuration directe, avec des détails sur la source (par exemple, "reboot,watchdog,service_manager_unresponsive" ou "reboot,software,watchdog").

Les raisons de démarrage ne doivent pas nécessiter de connaissances internes expertes pour être déchiffrées et/ou doivent être lisibles par l'humain avec un rapport intuitif. Exemples : "shutdown,vbxd" (mauvais), "shutdown,uv" (meilleur), "shutdown,undervoltage" (recommandé).

Combinaisons de motifs et de sous-motifs

Android réserve un ensemble de combinaisons reason-subreason qui ne doivent pas être surchargées en utilisation normale, mais qui peuvent être utilisées au cas par cas si la combinaison reflète précisément la condition associée. Voici quelques exemples de combinaisons réservées:

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

Pour en savoir plus, consultez kBootReasonMap dans system/core/bootstat/bootstat.cpp et l'historique des modifications git associé dans le dépôt source Android.

Signaler les raisons de démarrage

Toutes les raisons de démarrage, qu'elles proviennent du bootloader ou qu'elles soient enregistrées dans la raison de démarrage canonique, doivent être enregistrées dans la section kBootReasonMap de system/core/bootstat/bootstat.cpp. La liste kBootReasonMap combine des raisons de conformité et d'ancienne non-conformité. Les développeurs de bootloaders ne doivent enregistrer ici que de nouvelles raisons de conformité (et ne doivent pas enregistrer de raisons de non-conformité, sauf si le produit a déjà été expédié et ne peut pas être modifié).

Nous vous recommandons vivement d'utiliser des entrées existantes conformes dans system/core/bootstat/bootstat.cpp et de faire preuve de retenue avant d'utiliser une chaîne non conforme. Voici quelques recommandations:

  • OK pour signaler "kernel_panic" à partir du bootloader, car bootstat peut être en mesure d'inspecter ramoops pour kernel_panic signatures afin d'affiner les sous-raisons dans le system_boot_reason_prop canonique.
  • Non autorisé de signaler une chaîne non conforme dans kBootReasonMap (par exemple, "panic") à partir du bootloader, car cela empêchera finalement d'affiner reason.

Par exemple, si kBootReasonMap contient "wdog_bark", un développeur de bootloader doit:

  • Passez à "watchdog,bark" et ajoutez-le à la liste dans kBootReasonMap.
  • Réfléchissez à ce que "bark" signifie pour les personnes qui ne connaissent pas la technologie et déterminez si un subreason plus pertinent est disponible.

Vérifier la conformité du motif de démarrage

Pour le moment, Android ne fournit pas de test CTS actif pouvant déclencher ou inspecter avec précision toutes les raisons de démarrage possibles qu'un bootloader pourrait fournir. Les partenaires peuvent toujours essayer d'exécuter un test passif pour déterminer la compatibilité.

Par conséquent, la conformité du bootloader exige que les développeurs de bootloader respectent volontairement l'esprit des règles et consignes décrites ci-dessus. Nous invitons ces développeurs à contribuer à AOSP (et plus particulièrement à system/core/bootstat/bootstat.cpp) et à utiliser cette opportunité comme forum de discussion sur les problèmes de raison de démarrage.