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 del riavvio di un dispositivo, quindi comunica questa determinazione aggiungendo androidboot.bootreason=<reason> alla riga di comando del kernel Android per il suo avvio. init, che poi traduce questa riga di comando da propagare alla proprietà Android bootloader_boot_reason_prop (ro.boot.bootreason). Per i dispositivi lanciati con Android 12 o versioni successive, che utilizzano la versione del 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 per il motivo di avvio che non utilizzava spazi, era tutto in minuscolo, includeva pochi requisiti (ad esempio per la generazione di report kernel_panic, watchdog, cold/warm/hard) e che prevedeva concessioni per altri motivi unici. Questa specifica vaga ha portato alla proliferazione di centinaia di stringhe di motivi di avvio personalizzate (e a volte prive di significato), il che ha portato a una situazione ingestibile. A partire dall'attuale versione di Android, l'enorme quantità di contenuti quasi illeggibili o privi di significato inseriti dal bootloader ha creato problemi di conformità per bootloader_boot_reason_prop.

Con il rilascio di Android 9, il team Android riconosce che l'bootloader_boot_reason_prop legacy ha un notevole slancio e non può essere riscritto 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 Android sta:

• Collaborare con gli sviluppatori di bootloader per incoraggiarli a:
  • Fornisci motivi canonici, analizzabili e riconoscibili per bootloader_boot_reason_prop.
  • Partecipa all'elenco system/core/bootstat/bootstat.cpp kBootReasonMap.
• Aggiunta di 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 diritti sepolicy per leggerla.
• Informare gli utenti del motivo di avvio di attendere fino al montaggio dei dati utente prima di considerare attendibile il contenuto della 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 bloccato dai criteri di sicurezza di Android in base alle necessità 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 devono accedere a queste informazioni. Un'API raffinata, analizzabile e canonica per il motivo di avvio con system_boot_reason_prop può essere rilevata in modo affidabile e accurato solo dopo il montaggio dei dati utente. Nello specifico:

• Prima che i dati utente vengano montati, system_boot_reason_prop conterrà il valore di bootloader_boot_reason_prop.
• Dopo il montaggio dei dati utente, system_boot_reason_prop potrebbe essere aggiornato 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, modificandolo da immediatamente accurato all'avvio (con bootloader_boot_reason_prop) a disponibile solo dopo il montaggio dei dati utente (con system_boot_reason_prop).

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

Formato del motivo di avvio canonico

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 (usa il trattino basso)
• Tutti i caratteri stampabili
• reason, subreason e una o più istanze di detail separate da virgole.
  • Un reason obbligatorio che rappresenta il motivo con la priorità più alta per cui il dispositivo ha dovuto riavviarsi o spegnersi.
  • Un subreason facoltativo che rappresenta un breve riepilogo del motivo per cui il dispositivo ha dovuto riavviarsi o spegnersi (o di chi ha riavviato o spento il dispositivo).
  • Uno o più valori detail facoltativi. Un detail può puntare a un sottosistema per facilitare la determinazione del sistema specifico che ha generato l'subreason. Puoi specificare più valori detail, che in genere devono seguire una gerarchia di importanza. Tuttavia, è accettabile anche segnalare più valori di detail di uguale importanza.

Un valore vuoto per bootloader_boot_reason_prop è considerato non valido (in quanto consente ad altri agenti di inserire un motivo di avvio in un secondo momento).

Requisiti per il motivo

Il valore fornito per reason (il primo intervallo, prima della risoluzione o della virgola) deve appartenere al seguente insieme suddiviso in motivi principali, forti e blandi:

• kernel set:
  • "watchdog"
  • "kernel_panic"
• strong set:
  • "recovery"
  • "bootloader"
• blunt set:
  • "cold". In genere indica un ripristino completo di tutti i dispositivi, inclusa la memoria.
  • "hard". In genere indica che lo stato dell'hardware è stato reimpostato e ramoops deve conservare i contenuti permanenti.
  • "warm". In genere indica che la memoria e i dispositivi mantengono uno stato e che l'archivio di backup ramoops (vedi driver pstore nel kernel) contiene contenuti permanenti.
  • "shutdown"
  • "reboot". In genere significa che lo stato di ramoops è sconosciuto e lo stato dell'hardware è sconosciuto. Questo valore è un jolly, in quanto i valori cold, hard e warm forniscono indizi sulla profondità del ripristino per il dispositivo.

I bootloader devono fornire un set di kernel o un set blunt reason ed è fortemente consigliato fornire un subreason se è possibile determinarlo. 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 di primo livello può far parte di un subreason o di un detail. Tuttavia, poiché i motivi del kernel non possono essere prodotti dallo spazio utente, "watchdog" può essere riutilizzato dopo un motivo di impostazione 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" (scarsa), "shutdown,uv" (migliore), "shutdown,undervoltage" (preferita).

Combinazioni di motivo e sotto-motivo

Android riserva un insieme di combinazioni reason-subreason che non devono essere sovraccaricate durante il normale utilizzo, 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 dei log delle modifiche di Git associati nel repository di origine Android.

Segnalare i motivi di avvio

Tutti i motivi di avvio, dal bootloader o registrati nel motivo di avvio canonico, devono essere registrati nella sezione kBootReasonMap di system/core/bootstat/bootstat.cpp. L'elenco kBootReasonMap è un mix di motivi conformi e non conformi legacy. Gli sviluppatori di 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 voci esistenti e conformi in system/core/bootstat/bootstat.cpp e di esercitare moderazione prima di utilizzare una stringa non conforme. Come linea guida, è:

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

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

• Passa a "watchdog,bark" e aggiungi all'elenco in kBootReasonMap.
• Valuta cosa significa "bark" per chi non ha familiarità con la tecnologia e determina se è disponibile un subreason più significativo.

Verifica 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 agli sviluppatori di bootloader di rispettare volontariamente lo 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 al motivo di avvio.