Alasan booting kanonis

Android 9 menyertakan perubahan berikut pada spesifikasi alasan booting bootloader.

Alasan booting

{i>Bootloader<i} menggunakan sumber daya dan hardware yang tersedia secara unik untuk menentukan mengapa perangkat di-{i>reboot<i}, lalu mengomunikasikan determinasi itu dengan menambahkan androidboot.bootreason=<reason> ke Android baris perintah {i>kernel<i} untuk peluncurannya. init lalu menerjemahkannya command line untuk melakukan penerapan ke properti Android bootloader_boot_reason_prop (ro.boot.bootreason). Untuk perangkat yang diluncurkan dengan Android 12 atau yang lebih baru, menggunakan kernel versi 5.10 atau yang lebih baru, androidboot.bootreason=<reason> ditambahkan ke {i>bootconfig<i} alih-alih baris perintah {i>kernel<i}.

Spesifikasi alasan booting

Rilis Android sebelumnya menentukan format alasan booting yang tidak menggunakan spasi, huruf kecil semua, hanya menyertakan sedikit persyaratan (seperti untuk pelaporan kernel_panic, watchdog, cold/warm/hard), dan yang menghasilkan tunjangan karena alasan unik lainnya. Spesifikasi yang longgar ini mengakibatkan proliferasi ratusan alasan booting kustom (dan terkadang tidak bermakna) {i>string<i}, yang pada akhirnya menyebabkan situasi yang tidak dapat dikelola. Sejak saat ini Rilis Android, momentum semata-mata dari konten yang hampir tidak dapat diurai atau tidak bermakna yang diajukan oleh {i>bootloader<i} telah menimbulkan masalah kepatuhan bootloader_boot_reason_prop.

Dengan rilis Android 9, tim Android mengetahui bahwa bootloader_boot_reason_prop lama memiliki momentum besar dan tidak dapat ditulis ulang saat runtime. Setiap peningkatan pada spesifikasi alasan {i>booting<i} harus berasal dari interaksi dengan pengembang {i>bootloader<i} dan melakukan perubahan pada sistem yang ada. Untuk melakukannya, Tim Android:

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

Kenapa terlambat? Meskipun bootloader_boot_reason_prop tersedia lebih awal di komputer, browser akan diblokir oleh kebijakan keamanan Android sesuai kebutuhan. karena menyajikan informasi yang tidak akurat, tidak dapat diurai, dan tidak kanonis. Dalam kebanyakan situasi, hanya developer yang memiliki pengetahuan mendalam tentang sistem {i>booting<i} perlu mengakses informasi ini. Ulasan yang disempurnakan, dapat diuraikan, dan kanonis API untuk alasan booting dengan system_boot_reason_prop dapat andal dan diambil secara akurat hanya setelah data pengguna dipasang. Khususnya:

  • Sebelum data pengguna dipasang, system_boot_reason_prop akan berisi nilai dari bootloader_boot_reason_prop.
  • Setelah data pengguna dipasang, system_boot_reason_prop dapat diupdate agar mematuhi kebijakan atau melaporkan informasi yang lebih akurat.

Karena alasan ini, Android 9 memperpanjang periode waktu sebelum alasan {i>booting<i} dapat diperoleh secara resmi, mengubahnya dari akurat saat booting (dengan bootloader_boot_reason_prop) menjadi hanya tersedia setelah data pengguna terpasang (dengan system_boot_reason_prop).

Logika Bootstat bergantung pada arsitektur bootloader_boot_reason_prop. Saat properti tersebut menggunakan format yang dapat diprediksi, meningkatkan akurasi semua proses mulai ulang yang terkontrol dan skenario penonaktifan, yang pada gilirannya akan meningkatkan akurasi dan makna dari system_boot_reason_prop.

Format alasan booting kanonis

Format alasan booting kanonis 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, subreason, dan satu atau yang dipisahkan koma instance detail lainnya.
    • reason wajib yang mewakili prioritas tertinggi alasan mengapa perangkat harus dimulai ulang atau dimatikan.
    • subreason opsional yang mewakili ringkasan singkat dari mengapa perangkat harus dimulai ulang atau dimatikan (atau siapa yang memulai ulang atau mematikan perangkat).
    • Satu atau beberapa nilai detail opsional. detail dapat menunjuk ke suatu subsistem untuk membantu menentukan sistem spesifik mana menghasilkan subreason. Anda dapat menentukan beberapa Nilai detail, yang umumnya harus mengikuti hierarki tingkat kepentingan. Namun, Anda juga dapat melaporkan beberapa detail nilai yang sama pentingnya.

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

Persyaratan alasan

Nilai yang diberikan untuk reason (span pertama, sebelum penghentian atau koma) harus dari kumpulan berikut yang dibagi menjadi kernel, strong, dan blunt alasan:

  • {i>kernel set<i}:
    • "watchdog"
    • "kernel_panic"
  • set kuat:
    • "recovery"
    • "bootloader"
  • tumpul set:
    • "cold". Umumnya menunjukkan pengresetan penuh untuk semua perangkat, termasuk memori.
    • "hard". Umumnya menunjukkan bahwa hardware memiliki status direset dan ramoops akan mempertahankan konten persisten.
    • "warm". Secara umum menunjukkan memori dan perangkat mempertahankan beberapa status, dan ramoops (lihat pstore {i>driver<i} di {i>kernel<i}) penyimpanan pendukung berisi konten yang persisten.
    • "shutdown"
    • "reboot". Umumnya berarti status ramoops tidak diketahui dan status perangkat keras tidak diketahui. Nilai ini adalah {i> catchall<i} karena Nilai cold, hard, dan warm memberikan petunjuk mengenai kedalaman {i>reset<i} untuk perangkat tersebut.

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

Tidak ada reason rentang pertama yang dapat menjadi bagian dari subreason atau detail. Akan tetapi, karena alasan set {i>kernel<i} tidak dapat dihasilkan oleh ruang pengguna, "watchdog" dapat digunakan kembali setelah alasan blunt set, bersama dengan detail sumbernya (misalnya, "reboot,watchdog,service_manager_unresponsive", atau "reboot,software,watchdog").

Alasan booting tidak boleh memerlukan pengetahuan internal pakar 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 reason-subreason kombinasi yang seharusnya tidak kelebihan beban dalam penggunaan normal tetapi dapat digunakan pada secara kasus per kasus jika kombinasi tersebut secara akurat mencerminkan . 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 detail selengkapnya, lihat kBootReasonMap di system/core/bootstat/bootstat.cpp dan git yang terkait di repositori sumber Android.

Melaporkan alasan booting

Semua alasan booting, baik dari bootloader maupun dicatat di booting kanonis harus dicatat di bagian kBootReasonMap dalam system/core/bootstat/bootstat.cpp. Tujuan Daftar kBootReasonMap merupakan gabungan antara konten yang mematuhi kebijakan dan yang lama alasan yang tidak mematuhi kebijakan. Pengembang {i>bootloader<i} sebaiknya hanya mendaftarkan alasan kepatuhan di sini (dan tidak boleh mencantumkan alasan yang tidak mematuhi kebijakan kecuali produk telah dikirim dan tidak dapat diubah).

Kami sangat menyarankan untuk menggunakan entri yang ada dan sesuai dalam system/core/bootstat/bootstat.cpp dan melakukan pembatasan sebelum menggunakan string yang tidak mematuhi kebijakan. Sebagai pedoman, panduan ini adalah:

  • Oke untuk melaporkan "kernel_panic" dari bootloader, karena bootstat mungkin dapat memeriksa ramoops untuk kernel_panic signatures guna menyaring subalasan ke dalam system_boot_reason_prop kanonis.
  • Tidak diizinkan untuk melaporkan string yang tidak mematuhi kebijakan di kBootReasonMap (seperti "panic") dari {i>bootloader<i}, karena hal ini pada akhirnya akan merusak kemampuan untuk reason.

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

  • Ubah ke "watchdog,bark" dan tambahkan ke daftar di kBootReasonMap.
  • Pertimbangkan arti "bark" bagi mereka yang tidak terbiasa dengan teknologi dan menentukan apakah subreason yang tersedia.

Memverifikasi kepatuhan alasan booting

Saat ini, Android tidak menyediakan pengujian CTS aktif yang dapat secara akurat memicu atau memeriksa semua kemungkinan alasan {i>booting<i} yang dapat disediakan oleh {i>bootloader<i}; partner tetap dapat mencoba menjalankan pengujian pasif untuk menentukan kompatibilitas.

Akibatnya, kepatuhan {i>bootloader<i} mengharuskan pengembang {i>bootloader<i} untuk secara sukarela mematuhi prinsip dari aturan dan pedoman yang dijelaskan di atas. Kami mendorong developer tersebut untuk berkontribusi pada AOSP (khususnya untuk system/core/bootstat/bootstat.cpp) dan gunakan peluang ini sebagai untuk diskusi tentang masalah alasan booting.