Raison de démarrage canonique

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

Motifs de démarrage

Un bootloader utilise des ressources matérielles et de mémoire uniques pour déterminer la raison du redémarrage d'un appareil, puis communique cette détermination en ajoutant androidboot.bootreason=<reason> à la ligne de commande du noyau 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 ou ultérieure du noyau, androidboot.bootreason=<reason> est ajouté à bootconfig au lieu de la ligne de commande du noyau.

Spécifications du motif de démarrage

Les versions précédentes d'Android spécifiaient un format de motif de démarrage sans espaces, en minuscules, avec peu d'exigences (par exemple, pour les rapports kernel_panic, watchdog, cold/warm/hard) et qui prévoyait d'autres motifs uniques. Cette spécification vague 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 conduit à une situation ingérable. Dans la version actuelle d'Android, l'énorme quantité de contenu presque impossible à analyser ou dénué de sens envoyé par le bootloader a créé des problèmes de conformité pour bootloader_boot_reason_prop.

Avec la sortie d'Android 9, l'équipe Android reconnaît que l'ancien bootloader_boot_reason_prop a une dynamique importante et ne peut pas être réécrit au moment de l'exécution. Toute amélioration apportée à la spécification de la raison du redémarrage doit donc provenir d'interactions avec les développeurs du bootloader et de modifications apportées au système existant. Pour ce faire, l'équipe Android :

• Nous collaborons avec les développeurs de bootloader pour les encourager à :
  • Fournis des raisons canoniques, analysables et reconnaissables pour bootloader_boot_reason_prop.
  • Participez à la liste system/core/bootstat/bootstat.cpp kBootReasonMap.
• Ajout d'une source contrôlée et réinscriptible 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 tous les applications peuvent se voir accorder des droits sepolicy pour la lire.
• Informer les utilisateurs de la raison du démarrage pour attendre que les données utilisateur soient montées avant de faire confiance au contenu de la propriété de raison du démarrage du système system_boot_reason_prop.

Pourquoi si tard ? Bien que bootloader_boot_reason_prop soit disponible dès le début du démarrage, il est bloqué par la règle de sécurité Android selon les 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 devraient avoir besoin d'accéder à ces informations. Une API affinée, analysable et canonique pour la raison du démarrage avec system_boot_reason_prop ne peut être récupérée de manière fiable et précise qu'après le montage des données utilisateur. Plus spécifiquement :

• Avant le montage des données utilisateur, system_boot_reason_prop contiendra la valeur de bootloader_boot_reason_prop.
• Une fois les données utilisateur montées, peut être mis à jour pour être conforme ou pour fournir des informations plus précises.system_boot_reason_prop

Pour cette raison, Android 9 étend la période avant que le motif de démarrage puisse être officiellement acquis, en le faisant passer d'une précision immédiate au démarrage (avec bootloader_boot_reason_prop) à une disponibilité uniquement après le montage des données utilisateur (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 élargit la précision et la signification de system_boot_reason_prop.

Format canonique du motif de démarrage

Le format canonique de la raison du 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
• Aucun espace vide (utiliser un tiret bas)
• Tous les caractères imprimables
• Instances reason et subreason séparées par une virgule, et une ou plusieurs instances detail.
  • reason obligatoire qui représente la raison de priorité la plus élevée pour laquelle l'appareil a dû redémarrer ou s'éteindre.
  • subreason facultatif qui représente un bref résumé de la raison pour laquelle l'appareil a dû redémarrer ou s'éteindre (ou de la personne qui a redémarré ou éteint l'appareil).
  • 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 entraîné 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 incorrecte (car cela permet à d'autres agents d'injecter une raison de démarrage après coup).

Exigences concernant le motif

La valeur indiquée pour reason (première étendue, avant la fin ou la virgule) doit appartenir à l'ensemble suivant, divisé en raisons principales, fortes et générales :

• kernel set:
  • "watchdog"
  • "kernel_panic"
• Ensemble fort :
  • "recovery"
  • "bootloader"
• blunt set:
  • "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 certain état, et que le magasin de sauvegarde ramoops (voir le pilote pstore dans le noyau) contient du contenu persistant.
  • "shutdown"
  • "reboot". Cela signifie généralement que l'état ramoops est inconnu et que l'état du matériel est inconnu. Cette valeur est un terme 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 noyaux ou un ensemble blunt reason, et sont fortement encouragés à fournir un subreason s'il peut être déterminé. Par exemple, une pression prolongée sur la touche Marche/Arrêt, qui peut ou non avoir une sauvegarde ramoops, aura le motif de démarrage "reboot,longkey".

Aucun reason de première portée ne peut faire partie d'un subreason ou d'un detail. Toutefois, étant donné que les raisons de l'ensemble du noyau ne peuvent pas être produites par l'espace utilisateur, "watchdog" peut être réutilisé après une raison d'ensemble brutale, avec un détail de la source (par exemple, "reboot,watchdog,service_manager_unresponsive" ou "reboot,software,watchdog").

Les raisons de redémarrage ne doivent pas nécessiter de connaissances internes spécialisées pour être déchiffrées et/ou doivent être lisibles par un humain avec un rapport intuitif. Exemples : "shutdown,vbxd" (mauvais), "shutdown,uv" (mieux), "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 du journal des modifications git associé dans le dépôt source Android.

Signaler les raisons du démarrage

Tous les motifs de démarrage, qu'ils proviennent du bootloader ou qu'ils soient enregistrés dans le motif de démarrage canonique, doivent être enregistrés dans la section kBootReasonMap de system/core/bootstat/bootstat.cpp. La liste kBootReasonMap comprend à la fois des motifs conformes et des motifs non conformes anciens. Les développeurs de bootloader ne doivent enregistrer que les nouvelles raisons conformes ici (et ne doivent pas enregistrer les raisons non conformes, 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 et conformes dans system/core/bootstat/bootstat.cpp, et de faire preuve de retenue avant d'utiliser une chaîne non conforme. Voici quelques exemples :

• 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-motifs dans le system_boot_reason_prop canonique.
• Pas OK pour signaler une chaîne non conforme dans kBootReasonMap (par exemple, "panic") du bootloader, car cela empêchera en fin de compte d'affiner le 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 signifie "bark" 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 redémarrage

Pour le moment, Android ne fournit pas de test CTS actif permettant de déclencher ou d'inspecter avec précision toutes les raisons de démarrage possibles qu'un bootloader pourrait fournir. Les partenaires peuvent toujours tenter 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 (plus précisément à system/core/bootstat/bootstat.cpp) et à utiliser cette opportunité comme forum de discussion sur les problèmes liés aux raisons de redémarrage.