Motivo avvio canonico

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

Motivi dell'avvio

Un bootloader utilizza risorse hardware e di memoria disponibili in modo univoco per determinare perché un dispositivo è stato riavviato, quindi comunica questa determinazione aggiungendo androidboot.bootreason=<reason> alla riga di comando del kernel Android per il lancio. init traduce quindi questa riga di comando per propagarsi alla proprietà Android bootloader_boot_reason_prop (ro.boot.bootreason). Per i dispositivi che si avviano con Android 12 o versioni successive e utilizzando il kernel versione 5.10 o successive, androidboot.bootreason=<reason> viene aggiunto a bootconfig al posto della riga di comando del kernel.

Specifiche del motivo dell'avvio

Le versioni precedenti di Android specificavano un formato basato sull'avvio che non utilizzava spazi, era tutto minuscolo, includeva pochi requisiti (ad esempio per la generazione di report kernel_panic, watchdog, cold/warm/hard) e che consentiva altri motivi unici. Questa specifica a basso contenuto ha provocato la proliferazione di centinaia di stringhe di motivi di avvio personalizzate (e a volte prive di significato), che a sua volta ha determinato una situazione ingestibile. A partire dall'attuale release di Android, il grande slancio dovuto alla presenza di contenuti quasi non analizzabili o privi di significato presentati dal bootloader ha creato problemi di conformità per bootloader_boot_reason_prop.

Con la release Android 9, il team di Android riconosce che la versione precedente di bootloader_boot_reason_prop ha avuto un notevole slancio e non può essere riscritte in fase di runtime. Eventuali miglioramenti alla specifica del motivo dell'avvio devono quindi derivare dalle interazioni con gli sviluppatori del bootloader e dalle modifiche al sistema esistente. A questo scopo, il team di Android è:

• Coinvolgimento degli sviluppatori di bootloader per incoraggiarli a:
  • Fornisci motivi canonici, analizzabili e riconoscibili per bootloader_boot_reason_prop.
  • Partecipa all'elenco kBootReasonMap di system/core/bootstat/bootstat.cpp.
• Aggiunta di un'origine controllata e riscrivibile in runtime di system_boot_reason_prop (sys.boot.reason). Un insieme limitato di app di sistema (ad esempio bootstat e init) può riscrivere questa proprietà, ma a tutte le app possono essere concessi diritti di sicurezza per leggerla.
• Informare gli utenti sul motivo dell'avvio di attendere fino a quando i dati utente sono stati montati prima di considerare attendibili i contenuti nella proprietà Motivo di avvio del sistema system_boot_reason_prop.

Perché così tardi? Anche se bootloader_boot_reason_prop è disponibile nelle fasi iniziali dell'avvio, viene bloccato dal criterio 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 accedere a queste informazioni. Un'API raffinata, analizzabile e canonica per motivi 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 del montaggio dei dati utente, system_boot_reason_prop conterrà il valore di bootloader_boot_reason_prop.
• Dopo che i dati utente sono stati montati, system_boot_reason_prop può 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 dell'avvio possa essere acquisito ufficialmente, passando da una precisione immediata all'avvio (con bootloader_boot_reason_prop) a una disponibilità solo dopo il montaggio dei dati utente (con system_boot_reason_prop).

La logica di bootstat dipende da un valore bootloader_boot_reason_prop più informativo e conforme. Quando la proprietà utilizza un formato prevedibile, migliora l'accuratezza di tutti gli scenari di riavvio e chiusura controllati, il che a sua volta perfeziona e amplia l'accuratezza e il significato di system_boot_reason_prop.

Formato motivo avvio canonico

Il formato canonico del motivo dell'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 sottolineato)
• Tutti i caratteri stampabili
• reason, subreason e una o più istanze detail separate da virgole.
  • Un valore reason obbligatorio che rappresenta il motivo della massima priorità per cui il dispositivo ha dovuto riavviarsi o arrestarsi.
  • Un elemento subreason facoltativo che rappresenta un breve riepilogo del motivo per cui il dispositivo è stato riavviato o è stato arrestato (oppure chi lo ha riavviato o arrestato).
  • Uno o più valori facoltativi di detail. Un detail può puntare a un sottosistema per aiutare a determinare quale sistema specifico ha generato subreason. Puoi specificare più valori detail, che in genere devono seguire una gerarchia di importanza. Tuttavia, è anche accettabile segnalare più valori detail di uguale importanza.

Un valore vuoto per bootloader_boot_reason_prop è considerato illegale, poiché ciò consente ad altri agenti di inserire un motivo di avvio a posteriori.

Requisiti per i motivi

Il valore specificato per reason (primo intervallo, prima del termine o della virgola) deve essere il seguente insieme suddiviso in motivi kernel, forte e smussato:

• set di kernel:
  • "watchdog"
  • "kernel_panic"
• set efficace:
  • "recovery"
  • "bootloader"
• serie smussata:
  • "cold". Indica in genere un ripristino completo di tutti i dispositivi, inclusa la memoria.
  • "hard". Indica in genere che lo stato dell'hardware è stato reimpostato e che ramoops deve conservare i contenuti persistenti.
  • "warm". Indica in genere che la memoria e i dispositivi conservano uno stato e l'archivio di backup ramoops (vedi il driver pstore nel kernel) include contenuti permanenti.
  • "shutdown"
  • "reboot". In genere significa che lo stato ramoops è sconosciuto e lo stato dell'hardware è sconosciuto. Questo valore è un catchall perché i valori cold, hard e warm forniscono indizi sulla profondità del reset per il dispositivo.

I bootloader devono fornire un set di kernel o un set blunt reason e consigliamo vivamente di fornire un valore subreason se può essere determinato. Ad esempio, una pressione prolungata del tasto di accensione che potrebbe avere o meno la copia di backup di ramoops avrà il motivo dell'avvio "reboot,longkey".

Nessun reason del primo intervallo può far parte di subreason o detail. Tuttavia, poiché i motivi dell'impostazione del kernel non possono essere generati dallo spazio utente, "watchdog" può essere riutilizzato dopo un motivo per l'impostazione non smorzata, insieme a un dettaglio dell'origine (ad esempio "reboot,watchdog,service_manager_unresponsive" o "reboot,software,watchdog").

I motivi dell'avvio non devono richiedere conoscenze interne di esperti per decifrare e/o devono essere leggibili da una persona con un report intuitivo. Esempi: "shutdown,vbxd" (pessimo), "shutdown,uv" (migliore), "shutdown,undervoltage" (preferito).

Combinazioni motivo-sottomotivo

Android riserva un insieme di reason-subreason combinazioni che non devono essere sovraccaricate durante il normale utilizzo, ma che possono essere utilizzate caso per caso se la combinazione rispecchia 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 del log delle modifiche Git associata nel repository di origine Android.

Segnala motivi di avvio

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

Ti consigliamo vivamente di utilizzare voci conformi esistenti in system/core/bootstat/bootstat.cpp e di applicare restrizioni all'esercizio prima di utilizzare una stringa non conforme. Come regola generale, si tratta di:

• Puoi segnalare "kernel_panic" dal bootloader, in quanto bootstat potrebbe essere in grado di controllare ramoops per kernel_panic signatures per perfezionare i motivi secondari nella versione canonica system_boot_reason_prop.
• Non è possibile 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 aggiungilo all'elenco in kBootReasonMap.
• Valuta cosa significa "bark" per chi non ha familiarità con questa tecnologia e determina se è disponibile un subreason più significativo.

Verifica la conformità del motivo dell'avvio

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

Di conseguenza, la conformità dei bootloader richiede che gli sviluppatori dei bootloader rispettino volontariamente le regole e le linee guida descritte in precedenza. Invitiamo tali sviluppatori a contribuire ad AOSP (in particolare a system/core/bootstat/bootstat.cpp) e a sfruttare questa opportunità come forum per discussioni sui problemi che causano l'avvio.