Alasan Boot Canonical

Android 9 menyertakan perubahan berikut pada spesifikasi alasan boot bootloader.

Alasan boot

Bootloader menggunakan sumber daya perangkat keras dan memori yang tersedia secara unik untuk menentukan mengapa perangkat di-boot ulang, kemudian mengomunikasikan penentuan tersebut dengan menambahkan androidboot.bootreason=<reason> ke baris perintah kernel Android untuk peluncurannya. init kemudian menerjemahkan baris perintah ini untuk disebarkan ke properti Android bootloader_boot_reason_prop ( ro.boot.bootreason ). Untuk perangkat yang diluncurkan dengan Android 12 atau lebih baru, menggunakan kernel versi 5.10 atau lebih tinggi, androidboot.bootreason=<reason> ditambahkan ke bootconfig alih-alih baris perintah kernel.

Spesifikasi alasan boot

Rilis Android sebelumnya menetapkan format alasan booting yang tidak menggunakan spasi, semuanya huruf kecil, menyertakan beberapa persyaratan (seperti untuk pelaporan kernel_panic , watchdog , cold / warm / hard ), dan yang membuat kelonggaran untuk alasan unik lainnya. Spesifikasi longgar ini menghasilkan proliferasi ratusan string alasan boot khusus (dan terkadang tidak berarti), yang pada gilirannya menyebabkan situasi yang tidak dapat dikelola. Pada rilis Android saat ini, momentum dari konten yang hampir tidak dapat diuraikan atau tidak berarti yang diajukan oleh bootloader telah menciptakan masalah kepatuhan untuk bootloader_boot_reason_prop .

Dengan rilis Android 9, tim Android menyadari bahwa bootloader_boot_reason_prop lama memiliki momentum yang substansial dan tidak dapat ditulis ulang saat runtime. Setiap perbaikan pada spesifikasi alasan boot karena itu harus berasal dari interaksi dengan pengembang bootloader dan tweak ke sistem yang ada. Untuk itu tim Android adalah:

• Terlibat dengan pengembang bootloader untuk mendorong mereka untuk:
  • Berikan alasan kanonik, dapat diuraikan, dan dapat dikenali untuk bootloader_boot_reason_prop .
  • Berpartisipasi dalam daftar kBootReasonMap system/core/bootstat/bootstat.cpp kBootReasonMap
• Menambahkan sumber system_boot_reason_prop yang dikontrol dan dapat ditulis ulang runtime ( sys.boot.reason ). Kumpulan aplikasi sistem yang terbatas (seperti bootstat dan init ) dapat menulis ulang properti ini, tetapi semua aplikasi dapat diberikan hak kebijakan untuk membacanya.
• Memberi tahu pengguna tentang alasan boot untuk menunggu hingga data pengguna dipasang sebelum mempercayai konten di properti alasan boot sistem system_boot_reason_prop .

Mengapa begitu terlambat? Meskipun bootloader_boot_reason_prop tersedia sejak awal saat boot, ini diblokir oleh kebijakan keamanan Android berdasarkan kebutuhan karena mewakili informasi yang tidak akurat, tidak dapat diuraikan, dan nonkanonik. Dalam kebanyakan situasi, hanya pengembang dengan pengetahuan mendalam tentang sistem boot yang perlu mengakses informasi ini. API yang disempurnakan, dapat diuraikan, dan kanonik untuk alasan boot melalui system_boot_reason_prop dapat diambil dengan andal dan akurat hanya setelah data pengguna dipasang. Secara khusus:

• Sebelum userdata dipasang, system_boot_reason_prop akan berisi nilai dari bootloader_boot_reason_prop .
• Setelah data pengguna dipasang, system_boot_reason_prop dapat diperbarui agar sesuai atau untuk melaporkan informasi yang lebih akurat.

Karena alasan ini, Android 9 memperpanjang periode waktu sebelum alasan booting dapat diperoleh secara resmi, mengubahnya dari yang langsung akurat saat boot (dengan bootloader_boot_reason_prop ) menjadi hanya tersedia setelah data pengguna dipasang (dengan system_boot_reason_prop ).

Logika bootstat bergantung pada bootloader_boot_reason_prop yang lebih informatif dan sesuai. Ketika properti tersebut menggunakan format yang dapat diprediksi, properti tersebut meningkatkan akurasi semua skenario reboot dan shutdown yang terkontrol, yang pada gilirannya menyempurnakan dan memperluas akurasi dan makna system_boot_reason_prop .

Format alasan boot kanonik

Format alasan boot kanonik untuk bootloader_boot_reason_prop di Android 9 menggunakan sintaks berikut:

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

Aturan pemformatan:

• Huruf kecil
• Tidak ada yang kosong (gunakan garis bawah)
• Semua karakter yang dapat dicetak
• reason dipisahkan koma , subreason , dan satu atau lebih detail (s).
  • reason wajib yang mewakili alasan prioritas tertinggi mengapa perangkat harus di-boot ulang atau dimatikan.
  • subreason opsional yang mewakili ringkasan singkat tentang mengapa perangkat harus melakukan boot ulang atau shutdown (atau siapa yang melakukan boot ulang atau shutdown pada perangkat).
  • Satu atau beberapa nilai detail opsional. Sebuah detail mungkin menunjuk ke sebuah subsistem untuk membantu dalam menentukan sistem spesifik mana yang menghasilkan subreason -alasan tersebut. Anda dapat menentukan beberapa nilai detail , yang umumnya harus mengikuti hierarki kepentingan. Namun, juga dapat diterima untuk melaporkan beberapa nilai detail yang sama pentingnya.

Nilai kosong untuk bootloader_boot_reason_prop dianggap ilegal (karena ini memungkinkan agen lain memasukkan alasan boot setelah fakta).

Persyaratan alasan

Nilai yang diberikan untuk reason (rentang pertama, sebelum penghentian atau koma) harus dari himpunan berikut dibagi menjadi alasan kernel, kuat, dan tumpul:

• kumpulan inti:
  • " watchdog"
  • "kernel_panic"
• set yang kuat:
  • "recovery"
  • "bootloader"
• set tumpul:
  • "cold" . Umumnya menunjukkan reset penuh semua perangkat, termasuk memori.
  • "hard" . Secara umum menunjukkan bahwa perangkat keras telah disetel ulang dan ramoops harus mempertahankan konten yang persisten.
  • "warm" . Umumnya menunjukkan memori dan perangkat mempertahankan beberapa status, dan ramoops (lihat driver pstore di kernel) berisi konten persisten.
  • "shutdown"
  • "reboot" . Umumnya berarti status ramoops tidak diketahui dan status perangkat keras tidak diketahui. Nilai ini mencakup semua karena nilai cold , hard , dan warm memberikan petunjuk tentang kedalaman penyetelan ulang untuk perangkat.

Bootloader harus memberikan set kernel atau reason set tumpul, dan sangat dianjurkan untuk memberikan subreason jika dapat ditentukan. Misalnya, penekanan lama tombol daya yang mungkin atau mungkin tidak memiliki cadangan ramoops akan memiliki alasan boot "reboot,longkey" .

Tidak ada reason rentang pertama yang dapat menjadi bagian dari subreason atau detail apa pun . Namun, karena alasan set kernel tidak dapat dihasilkan oleh ruang pengguna, "watchdog" dapat digunakan kembali setelah alasan set yang tumpul, bersama dengan detail sumber (misalnya "reboot,watchdog,service_manager_unresponsive" , atau "reboot,software,watchdog" ).

Alasan boot seharusnya tidak memerlukan pengetahuan internal ahli untuk menguraikan dan/atau harus dapat dibaca manusia dengan laporan intuitif. Contoh: "shutdown,vbxd" (buruk), "shutdown,uv" (lebih baik), "shutdown,undervoltage" (lebih disukai).

Kombinasi Alasan-Subalasan

Android mencadangkan serangkaian reason - kombinasi subreason -alasan yang tidak boleh kelebihan beban dalam penggunaan normal tetapi dapat digunakan berdasarkan kasus per kasus jika kombinasi tersebut secara akurat mencerminkan kondisi terkait. Contoh kombinasi yang dipesan meliputi:

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

Untuk detail selengkapnya, lihat kBootReasonMap di system/core/bootstat/bootstat.cpp dan riwayat git changelog terkait di repositori sumber Android.

Melaporkan alasan boot

Semua alasan boot, baik dari bootloader atau dicatat dalam alasan boot kanonik, harus dicatat di bagian kBootReasonMap dari system/core/bootstat/bootstat.cpp . Daftar kBootReasonMap adalah campuran dari alasan kepatuhan dan warisan yang tidak patuh. Pengembang bootloader hanya boleh mendaftarkan alasan kepatuhan baru di sini (dan tidak boleh mendaftarkan alasan ketidakpatuhan kecuali produk telah dikirim dan tidak dapat diubah).

Kami sangat menyarankan untuk menggunakan entri yang ada dan sesuai di system/core/bootstat/bootstat.cpp dan melakukan pengendalian sebelum menggunakan string yang tidak sesuai. Sebagai pedoman adalah:

• OK untuk melaporkan "kernel_panic" dari bootloader, karena bootstat mungkin dapat memeriksa ramoops untuk kernel_panic signatures guna menyaring subalasan ke dalam canonical system_boot_reason_prop .
• Tidak boleh melaporkan string yang tidak sesuai di kBootReasonMap (seperti "panic") dari bootloader, karena ini pada akhirnya akan merusak kemampuan untuk menyaring reason .

Misalnya, jika kBootReasonMap berisi "wdog_bark" , pengembang bootloader harus:

• Ubah ke "watchdog,bark" dan tambahkan ke daftar di kBootReasonMap .
• Pertimbangkan apa arti "bark" bagi mereka yang tidak terbiasa dengan teknologi dan tentukan apakah ada subreason yang lebih bermakna.

Memverifikasi kepatuhan alasan boot

Saat ini, Android tidak menyediakan pengujian CTS aktif yang dapat secara akurat memicu atau memeriksa semua kemungkinan alasan boot yang dapat diberikan oleh bootloader; mitra masih dapat mencoba menjalankan tes pasif untuk menentukan kompatibilitas.

Akibatnya, kepatuhan bootloader mengharuskan pengembang bootloader untuk secara sukarela mematuhi semangat aturan dan pedoman yang dijelaskan di atas. Kami mendesak pengembang tersebut untuk berkontribusi pada AOSP (khususnya ke system/core/bootstat/bootstat.cpp ) dan menggunakan kesempatan ini sebagai forum diskusi tentang masalah alasan booting.