Motivo avvio canonico

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

Motivi dell'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 traduce poi 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 del kernel 5.10 o successive, androidboot.bootreason=<reason> viene aggiunto a bootconfig anziché alla riga di comando del kernel.

Specifiche del motivo dell'avvio

Le release precedenti di Android specificavano un formato del motivo di avvio che non utilizzava spazi, era tutto in minuscolo, includeva pochi requisiti (ad esempio per i report kernel_panic, watchdog, cold/warm/hard) e ammetteva altri motivi unici. Questa specifica non rigida ha comportato la proliferazione di centinaia di stringhe personalizzate (e a volte prive di significato) per i motivi di avvio, il che ha a sua volta portato a una situazione non gestibile. A partire dalla release Android corrente, l'enorme quantità di contenuti quasi non decodificabili o privi di significato registrati dal bootloader ha creato problemi di conformità per bootloader_boot_reason_prop.

Con il rilascio di Android 9, il team di Android riconosce che bootloader_boot_reason_prop legacy ha un impulso sostanziale e non può essere riscritto in fase di esecuzione. Pertanto, eventuali miglioramenti alla specifica del motivo di avvio devono derivare da interazioni con gli sviluppatori del bootloader e da modifiche al sistema esistente. A questo scopo, il team di Android è:

  • Coinvolgere gli sviluppatori di bootloader per incoraggiarli a:
    • Fornisci motivi canonici, analizzabili e riconoscibili per bootloader_boot_reason_prop.
    • Partecipare 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 (ad esempio bootstat e init) può riscrivere questa proprietà, ma a tutte le app può essere concesso il diritto di lettura dei criteri di sicurezza.
  • 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 dell'avvio del sistema system_boot_reason_prop.

Perché così tardi? Sebbene bootloader_boot_reason_prop sia disponibile all'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 dovrebbero accedere a queste informazioni. Un'API per il motivo di avvio con system_boot_reason_prop raffinata, analizzabile e canonica può essere rilevata in modo affidabile e accurato solo dopo il montaggio di userdata. Nello specifico:

  • Prima del montaggio dei dati utente, system_boot_reason_prop conterrà il valore di bootloader_boot_reason_prop.
  • Dopo aver montato userdata, system_boot_reason_prop potrebbe essere aggiornato per essere conforme o per riportare informazioni più precise.

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 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 del motivo di avvio canonico

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

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

Regole di formattazione:

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

Un valore vuoto per bootloader_boot_reason_prop è considerato illegale (in quanto consente ad altri agenti di iniettare un motivo di avvio a posteriori).

Requisiti del motivo

Il valore specificato per reason (primo intervallo, prima della terminazione o della virgola) deve appartenere al seguente insieme suddiviso in motivi di base, forti e smussati:

  • kernel set:
    • "watchdog"
    • "kernel_panic"
  • strong set:
    • "recovery"
    • "bootloader"
  • serie smussata:
    • "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 dovrebbe conservare i contenuti permanenti.
    • "warm". Indica in genere che la memoria e i dispositivi conservano un certo stato e l'archivio di backup ramoops (vedi il driver pstore nel kernel) include contenuti permanenti.
    • "shutdown"
    • "reboot". In genere, indica che lo stato ramoops è sconosciuto e lo stato dell'hardware è sconosciuto. Questo valore è generico, poiché i valori cold, hard e warm forniscono indizi sulla profondità del ripristino dei dati di fabbrica del dispositivo.

I bootloader devono fornire un set di kernel o un set blunt reason e sono fortemente incoraggiati a fornire un subreason, se possibile. 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 primo span reason può far parte di subreason o detail. Tuttavia, poiché i motivi di impostazione del kernel non possono essere generati dall'esploratore dello 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 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" (cattivo), "shutdown,uv" (migliore), "shutdown,undervoltage" (preferito).

Combinazioni di motivi e sottomotivi

Android riserva un insieme di combinazioni reason-subreason che non devono essere sovraccaricate in condizioni di utilizzo normale, ma possono essere utilizzate caso per caso se la combinazione riflette con precisione 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 di git associata nel repository di origine di Android.

Segnalare i motivi dell'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 è un mix di motivi di conformità e non conformità legacy. Gli sviluppatori di bootloader devono registrare qui solo i nuovi motivi di conformità (e non devono registrare motivi di mancata conformità, 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 linea guida, è:

  • 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 OK segnalare una stringa non conforme in kBootReasonMap (ad esempio "panic") dal bootloader), poiché alla fine verrà compromessa la possibilità di perfezionare il reason.

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

  • Passa a "watchdog,bark" e aggiungi all'elenco in kBootReasonMap.
  • Valuta il significato di "bark" per chi non è familiare con la tecnologia e determina se è disponibile un "bark" più significativo.subreason

Verifica la conformità del motivo dell'avvio

Al momento, Android non fornisce un test CTS attivo che possa 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 norme 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 discutere di problemi relativi al motivo di avvio.