Motivo di avvio canonico

Android 9 include le seguenti modifiche alla specifica del motivo di avvio del bootloader.

Motivi di avvio

Un bootloader utilizza risorse hardware e di memoria disponibili in modo univoco per determinare il motivo per cui un dispositivo è stato riavviato, quindi comunica questa determinazione aggiungendo androidboot.bootreason=<reason> alla riga di comando del kernel Android per il suo avvio. init traduce quindi questa riga di comando per propagarla alla proprietà Android bootloader_boot_reason_prop (ro.boot.bootreason). Per i dispositivi lanciati con Android 12 o versioni successive, che utilizzano la versione kernel 5.10 o successive, androidboot.bootreason=<reason> viene aggiunto a bootconfig anziché alla riga di comando del kernel.

Specifiche del motivo di avvio

Le versioni precedenti di Android specificavano un formato del motivo di avvio che non utilizzava spazi, era tutto in minuscolo, includeva pochi requisiti (ad esempio per la segnalazione kernel_panic, watchdog, cold/warm/hard) e che consentiva altri motivi univoci. Questa specifica libera ha portato alla proliferazione di centinaia di stringhe di motivi di avvio personalizzate (e a volte senza significato), che a loro volta hanno portato a una situazione ingestibile. A partire dalla versione attuale di Android, la grande quantità di contenuti quasi non analizzabili o senza significato inviati dal bootloader ha creato problemi di conformità per bootloader_boot_reason_prop.

Con la release di Android 9, il team di Android riconosce che la proprietà legacy bootloader_boot_reason_prop ha una notevole quantità di dati e non può essere riscritta in fase di runtime. Pertanto, eventuali miglioramenti alla specifica del motivo di avvio devono derivare dalle interazioni con gli sviluppatori del bootloader e dalle modifiche al sistema esistente. A questo scopo, il team di Android:

• Collabora con gli sviluppatori del bootloader per incoraggiarli a:
  • Fornire motivi canonici, analizzabili e riconoscibili a bootloader_boot_reason_prop.
  • Partecipare all'elenco system/core/bootstat/bootstat.cpp kBootReasonMap.
• Aggiungere un'origine controllata e riscrivibile in fase di runtime di system_boot_reason_prop (sys.boot.reason). Un insieme limitato di app di sistema (come bootstat e init) può riscrivere questa proprietà, ma a tutte le app possono essere concessi i diritti sepolicy per leggerla.
• Informare gli utenti del motivo di avvio di attendere fino a quando i dati utente non vengono montati prima di considerare attendibili i contenuti nella proprietà del motivo di avvio del sistema system_boot_reason_prop.

Perché così tardi? Sebbene bootloader_boot_reason_prop sia disponibile all'inizio dell'avvio, viene bloccata dalla norma di sicurezza di Android in base alle esigenze perché rappresenta informazioni imprecise, non analizzabili e non canoniche. Nella maggior parte dei casi, solo gli sviluppatori con una conoscenza approfondita del sistema di avvio dovrebbero avere bisogno di accedere a queste informazioni. Un'API raffinata, analizzabile e canonica per il motivo di avvio con system_boot_reason_prop può essere recuperata in modo affidabile e accurato solo dopo che i dati utente sono stati montati. In particolare:

• Prima che i dati utente siano stati montati, system_boot_reason_prop conterrà il valore di bootloader_boot_reason_prop.
• Dopo che i dati utente sono stati montati, system_boot_reason_prop potrebbe essere aggiornata per essere conforme o per segnalare informazioni più accurate.

Per questo motivo, Android 9 estende il periodo di tempo prima che il motivo di avvio possa essere acquisito ufficialmente, passando da una precisione immediata all'avvio (con bootloader_boot_reason_prop) a una disponibilità solo dopo che i dati utente sono stati montati (con system_boot_reason_prop).

La logica di bootstat dipende da una proprietà più informativa e conforme bootloader_boot_reason_prop. Quando quella proprietà utilizza un formato prevedibile, migliora l'accuratezza di tutti gli scenari di riavvio e spegnimento controllati, il che a sua volta perfeziona ed espande l'accuratezza e il significato di system_boot_reason_prop.

Formato canonico del motivo di avvio

Il formato canonico del motivo di avvio per bootloader_boot_reason_prop in Android 9 utilizza la seguente sintassi:

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

Regole di formattazione:

• Minuscolo
• Nessuno spazio vuoto (utilizza il trattino basso)
• Tutti i caratteri stampabili
• Istanze reason, subreason e una o più detail separate da virgole.
  • Un reason obbligatorio che rappresenta il motivo di massima priorità per cui il dispositivo ha dovuto essere riavviato o spento.
  • Un subreason facoltativo che rappresenta un breve riepilogo del motivo per cui il dispositivo ha dovuto essere riavviato o spento (o chi ha riavviato o spento il dispositivo).
  • Uno o più valori detail facoltativi. Un detail può puntare a un sottosistema per aiutare a determinare quale sistema specifico ha generato il subreason. Puoi specificare più detail valori, che in genere devono seguire una gerarchia di importanza. Tuttavia, è anche accettabile segnalare più detail valori di uguale importanza.

Un valore vuoto per bootloader_boot_reason_prop è considerato illegale (in quanto consente ad altri agenti di inserire un motivo di avvio dopo il fatto).

Requisiti del motivo

Il valore fornito per reason (prima estensione, prima della terminazione o della virgola) deve appartenere al seguente insieme suddiviso in motivi del kernel, forti e generici:

• Insieme del kernel:
  • "watchdog"
  • "kernel_panic"
• Insieme forte:
  • "recovery"
  • "bootloader"
• Insieme generico:
  • "cold". In genere indica una reimpostazione completa di tutti i dispositivi, inclusa la memoria.
  • "hard". In genere indica che lo stato dell'hardware è stato reimpostato e ramoops deve conservare i contenuti persistenti.
  • "warm". In genere indica che la memoria e i dispositivi conservano alcuni stati e l'ramoops (vedi il pstore driver nel kernel) archivio di backup contiene contenuti persistenti.
  • "shutdown"
  • "reboot". In genere significa che lo stato di ramoops è sconosciuto e lo stato dell'hardware è sconosciuto. Questo valore è un valore di tipo catch-all, in quanto i valori cold, hard e warm forniscono indizi sulla profondità della reimpostazione del dispositivo.

I bootloader devono fornire un insieme del kernel o un insieme generico reason, e sono vivamente invitati a fornire un subreason se può essere determinato. Ad esempio, una pressione prolungata del tasto di accensione che potrebbe o meno avere ramoops backup avrebbe il motivo di avvio "reboot,longkey".

Nessun reason della prima estensione può far parte di un subreason o detail. Tuttavia, poiché i motivi dell'insieme del kernel non possono essere prodotti da spazio utente, "watchdog" può essere riutilizzato dopo un motivo dell'insieme generico, insieme a un dettaglio dell'origine (ad esempio, "reboot,watchdog,service_manager_unresponsive", o "reboot,software,watchdog").

I motivi di avvio non devono richiedere conoscenze interne specialistiche per essere decifrati e/o devono essere leggibili da persone fisiche con un report intuitivo. Esempi: "shutdown,vbxd" (non valido), "shutdown,uv" (migliore), "shutdown,undervoltage" (preferito).

Combinazioni di motivi e sottomotivi

Android riserva un insieme di combinazioni reason-subreason che non devono essere sovraccaricate nell'uso normale, ma possono essere utilizzate caso per caso se la combinazione riflette accuratamente la condizione associata. Ecco alcuni esempi di combinazioni riservate:

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

Per maggiori dettagli, consulta kBootReasonMap in system/core/bootstat/bootstat.cpp e la cronologia associata delle modifiche git nel repository di origine Android.

Segnalare i motivi di avvio

Tutti i motivi di avvio, dal bootloader o registrati nel motivo di avvio canonico ragione, devono essere registrati nella sezione kBootReasonMap di system/core/bootstat/bootstat.cpp. L'elenco kBootReasonMap è un mix di motivi conformi e legacy non conformi. Gli sviluppatori del bootloader devono registrare qui solo i nuovi motivi conformi (e non devono registrare motivi non conformi a meno che il prodotto non sia già stato spedito e non possa essere modificato).

Ti consigliamo vivamente di utilizzare le voci conformi esistenti in system/core/bootstat/bootstat.cpp e di esercitare moderazione prima di utilizzare una stringa non conforme. Come linea guida, è:

• OK segnalare "kernel_panic" dal bootloader, in quanto bootstat potrebbe essere in grado di ispezionare ramoops per kernel_panic signatures per perfezionare i sottomotivi nel system_boot_reason_prop canonico.
• Non è OK segnalare una stringa non conforme in kBootReasonMap (ad esempio "panic") dal bootloader, in quanto ciò finirà per interrompere la possibilità di perfezionare il reason.

Ad esempio, se kBootReasonMap contiene "wdog_bark", uno sviluppatore del bootloader deve:

• Modificare in "watchdog,bark" e aggiungere all'elenco in kBootReasonMap.
• Valutare il significato di "bark" per chi non conosce la tecnologia e determinare se è disponibile un subreason più significativo.

Verificare la conformità del motivo di avvio

Al momento, Android non fornisce un test CTS attivo in grado di attivare o ispezionare con precisione tutti i possibili motivi di avvio che un bootloader potrebbe fornire; i partner possono comunque tentare di eseguire un test passivo per determinare la compatibilità.

Di conseguenza, la conformità del bootloader richiede che gli sviluppatori del bootloader aderiscano volontariamente allo spirito delle regole e delle linee guida descritte sopra. Invitiamo questi sviluppatori a contribuire ad AOSP (in particolare a system/core/bootstat/bootstat.cpp) e a utilizzare questa opportunità come forum per le discussioni sui problemi relativi ai motivi di avvio.