Alasan booting kanonis

Android 9 menyertakan perubahan berikut pada spesifikasi alasan booting bootloader.

Alasan booting

Bootloader menggunakan hardware dan resource memori yang tersedia secara unik untuk menentukan alasan perangkat melakukan reboot, lalu mengomunikasikan penentuan tersebut dengan menambahkan androidboot.bootreason=<reason> ke command line kernel Android untuk peluncurannya. init kemudian menerjemahkan command line ini untuk disebarkan ke properti Android bootloader_boot_reason_prop (ro.boot.bootreason). Untuk perangkat yang diluncurkan dengan Android 12 atau yang lebih tinggi, menggunakan kernel versi 5.10 atau yang lebih baru, androidboot.bootreason=<reason> ditambahkan ke bootconfig, bukan command line kernel.

Spesifikasi alasan booting

Rilis Android sebelumnya menentukan format alasan booting yang tidak menggunakan spasi, semuanya huruf kecil, mencakup beberapa persyaratan (seperti untuk pelaporan kernel_panic, watchdog, cold/warm/hard), dan yang memberikan kelonggaran untuk alasan unik lainnya. Spesifikasi yang tidak ketat ini menyebabkan munculnya ratusan string alasan booting kustom (dan terkadang tidak bermakna), yang pada gilirannya menyebabkan situasi yang tidak dapat dikelola. Mulai rilis Android saat ini, momentum besar konten yang hampir tidak dapat diuraikan atau tidak bermakna yang dicatat oleh bootloader telah menimbulkan masalah kepatuhan untuk bootloader_boot_reason_prop.

Dengan rilis Android 9, tim Android menyadari bahwa bootloader_boot_reason_prop lama memiliki momentum yang besar dan tidak dapat ditulis ulang saat runtime. Oleh karena itu, setiap peningkatan pada spesifikasi alasan booting harus berasal dari interaksi dengan developer bootloader dan penyesuaian pada sistem yang ada. Untuk itu, tim Android:

  • Berinteraksi dengan developer bootloader untuk mendorong mereka:
    • Berikan alasan kanonis, yang dapat diuraikan, dan dapat dikenali untuk bootloader_boot_reason_prop.
    • Berpartisipasi dalam daftar system/core/bootstat/bootstat.cpp kBootReasonMap.
  • Menambahkan sumber yang dapat ditulis ulang saat runtime dan dikontrol untuk system_boot_reason_prop (sys.boot.reason). Sejumlah aplikasi sistem terbatas (seperti bootstat dan init) dapat menulis ulang properti ini, tetapi semua aplikasi dapat diberi hak sepolicy untuk membacanya.
  • Memberi tahu pengguna tentang alasan booting untuk menunggu hingga userdata dipasang sebelum memercayai konten dalam properti alasan booting sistem system_boot_reason_prop.

Mengapa terlambat? Meskipun bootloader_boot_reason_prop tersedia lebih awal saat booting, bootloader_boot_reason_prop diblokir oleh kebijakan keamanan Android sesuai kebutuhan karena menampilkan informasi yang tidak akurat, tidak dapat diuraikan, dan non-kanonis. Dalam sebagian besar situasi, hanya developer dengan pengetahuan mendalam tentang sistem booting yang perlu mengakses informasi ini. API yang disempurnakan, dapat diuraikan, dan kanonis untuk alasan booting dengan system_boot_reason_prop dapat diambil secara andal dan akurat hanya setelah data pengguna terpasang. Khususnya:

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

Oleh karena itu, Android 9 memperpanjang jangka waktu sebelum alasan booting dapat diperoleh secara resmi, mengubahnya dari yang langsung akurat saat booting (dengan bootloader_boot_reason_prop) menjadi hanya tersedia setelah userdata terpasang (dengan system_boot_reason_prop).

Logika Bootstat bergantung pada bootloader_boot_reason_prop yang lebih informatif dan sesuai. Jika properti tersebut menggunakan format yang dapat diprediksi, akurasi semua skenario reboot dan penonaktifan yang dikontrol akan meningkat, yang pada gilirannya akan meningkatkan dan memperluas akurasi serta makna system_boot_reason_prop.

Format alasan booting kanonis

Format alasan booting kanonis untuk bootloader_boot_reason_prop di Android 9 menggunakan sintaksis berikut: 

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

Aturan pemformatan:

  • Huruf kecil
  • Tidak ada spasi (gunakan garis bawah)
  • Semua karakter yang dapat dicetak
  • reason, subreason, dan satu atau lebih instance detail yang dipisahkan koma.
    • reason yang diperlukan yang menunjukkan prioritas tertinggi alasan perangkat harus di-reboot atau dimatikan.
    • subreason opsional yang merepresentasikan ringkasan singkat tentang alasan perangkat harus di-reboot atau dimatikan (atau siapa yang me-reboot atau mematikan perangkat).
    • Satu atau beberapa nilai detail opsional. detail dapat mengarah ke subsistem untuk membantu menentukan sistem spesifik mana yang menghasilkan subreason. Anda dapat menentukan beberapa nilai detail, yang umumnya harus mengikuti hierarki kepentingan. Namun, Anda juga dapat melaporkan beberapa nilai detail yang sama pentingnya.

Nilai kosong untuk bootloader_boot_reason_prop dianggap ilegal (karena memungkinkan agen lain menyisipkan alasan booting setelahnya).

Persyaratan alasan

Nilai yang diberikan untuk reason (rentang pertama, sebelum penghentian atau koma) harus berupa set berikut yang dibagi menjadi alasan kernel, kuat, dan tidak jelas:

  • kernel set:
    • "watchdog"
    • "kernel_panic"
  • strong set:
    • "recovery"
    • "bootloader"
  • kumpulan tumpul:
    • "cold". Umumnya menunjukkan reset penuh semua perangkat, termasuk memori.
    • "hard". Umumnya menunjukkan bahwa hardware telah direset statusnya dan ramoops harus mempertahankan konten persisten.
    • "warm". Umumnya menunjukkan bahwa memori dan perangkat mempertahankan beberapa status, dan penyimpanan pendukung ramoops (lihat driver pstore di kernel) berisi konten persisten.
    • "shutdown"
    • "reboot". Umumnya berarti status ramoops tidak diketahui dan status hardware tidak diketahui. Nilai ini adalah nilai umum karena nilai cold, hard, dan warm memberikan petunjuk tentang kedalaman reset untuk perangkat.

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

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

Alasan booting tidak boleh memerlukan pengetahuan internal ahli untuk diuraikan dan/atau harus dapat dibaca oleh manusia dengan laporan yang intuitif. Contoh: "shutdown,vbxd" (buruk), "shutdown,uv" (lebih baik), "shutdown,undervoltage" (lebih disarankan).

Kombinasi alasan-subalasan

Android mencadangkan serangkaian kombinasi reason-subreason 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 dicadangkan 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 mengetahui detail selengkapnya, lihat kBootReasonMap di system/core/bootstat/bootstat.cpp dan histori log perubahan git terkait di repositori sumber Android.

Melaporkan alasan booting

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

Sebaiknya gunakan entri yang ada dan sesuai di system/core/bootstat/bootstat.cpp dan tunjukkan kehati-hatian sebelum menggunakan string yang tidak sesuai. Sebagai panduan, berikut adalah:

  • OK untuk melaporkan "kernel_panic" dari bootloader, karena bootstat mungkin dapat memeriksa ramoops untuk kernel_panic signatures guna menyempurnakan sub-alasan menjadi system_boot_reason_prop kanonis.
  • Tidak Boleh melaporkan string yang tidak mematuhi kebijakan di kBootReasonMap (seperti "panic") dari bootloader, karena pada akhirnya akan merusak kemampuan untuk menyempurnakan reason.

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

  • Ubah ke "watchdog,bark" dan tambahkan ke daftar di kBootReasonMap.
  • Pertimbangkan arti "bark" bagi orang yang belum memahami teknologi tersebut dan tentukan apakah subreason yang lebih bermakna tersedia.

Memverifikasi kepatuhan alasan booting

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

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