[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-08-21 (世界標準時間)。"],[],[],null,["# Canonical boot reason\n\nAndroid 9 includes the following changes to the bootloader boot reason specification.\n\nBoot reasons\n------------\n\n\nA bootloader uses uniquely-available hardware and memory resources to\ndetermine why a device rebooted, then communicates that determination by\nadding `androidboot.bootreason=\u003creason\u003e` to the Android\nkernel command line for its launch. `init` then translates this\ncommand line to propagate to the Android property\n`bootloader_boot_reason_prop` (`ro.boot.bootreason`).\nFor devices launching with Android 12 or higher,\nusing kernel version 5.10 or greater, `androidboot.bootreason=\u003creason\u003e`\nis added to bootconfig instead of the kernel command line.\n\nBoot reason specifications\n--------------------------\n\n\nPrevious releases of Android specified a boot reason format that used no\nspaces, was all lowercase, included few requirements (such as for reporting\n`kernel_panic`, `watchdog`,\n`cold`/`warm`/`hard`), and which made\nallowances for other unique reasons. This loose specification resulted in the\nproliferation of hundreds of custom (and sometimes meaningless) boot reason\nstrings, which in turn led to an unmanageable situation. As of the current\nAndroid release, the sheer momentum of near unparseable or meaningless content\nfiled by the bootloader has created compliance issues for\n`bootloader_boot_reason_prop`.\n\n\nWith the Android 9 release, the Android team\nrecognizes that the legacy `bootloader_boot_reason_prop` has\nsubstantial momentum and cannot be re-written at runtime. Any improvements to\nthe boot reason specification must therefore come from interactions with\nbootloader developers and tweaks to the existing system. To that end the\nAndroid team is:\n\n- Engaging with bootloader developers to encourage them to:\n - Provide canonical, parseable, and recognizable reasons to `bootloader_boot_reason_prop`.\n - Participate in the `system/core/bootstat/bootstat.cpp` `kBootReasonMap` list.\n- Adding a controlled and runtime-rewritable source of the `system_boot_reason_prop` (`sys.boot.reason`). A limited set of system apps (such as `bootstat` and `init`) can rewrite this property, but all apps can be granted sepolicy rights to read it.\n- Informing users of the boot reason to wait until after userdata is mounted before trusting the content in the system boot reason property `system_boot_reason_prop`.\n\n\nWhy so late? While `bootloader_boot_reason_prop` is available early\non in boot, it is blocked by the Android security policy on an as-need basis\nbecause it represents inaccurate, unparseable, and noncanonical information.\nIn most situations, only developers with deep knowledge of the boot system\nshould need to access this information. A refined, parseable, and canonical\nAPI for boot reason with `system_boot_reason_prop` can be reliably\nand accurately picked up only **after** userdata has mounted.\nSpecifically:\n\n- **Before** userdata has mounted, `system_boot_reason_prop` will contain the value from `bootloader_boot_reason_prop`.\n- **After** userdata has mounted, `system_boot_reason_prop` may be updated to be compliant or to report more accurate information.\n\n\nFor this reason, Android 9 extends the period of\ntime before the boot reason can be officially acquired, changing it from being\nimmediately accurate in boot (with `bootloader_boot_reason_prop`)\nto being available only after userdata has mounted (with\n`system_boot_reason_prop`).\n\n\nBootstat logic depends on a more informative and compliant\n`bootloader_boot_reason_prop`. When that property uses a\npredictable format, it improves the accuracy of all controlled reboot and\nshutdown scenarios, which in turn refines and expands the accuracy and meaning\nof `system_boot_reason_prop`.\n\nCanonical boot reason format\n----------------------------\n\n\nThe canonical boot reason format for `bootloader_boot_reason_prop`\nin Android 9 uses the following syntax: \n\n```text\n\u003creason\u003e,\u003csubreason\u003e,\u003cdetail\u003e…\n```\n\n\nFormatting rules:\n\n- Lower case\n- No blanks (use underline)\n- All printable characters\n- Comma-separated `reason`, `subreason`, and one or more `detail` instances.\n - A required `reason` that represents the highest priority reason why the device had to reboot or shutdown.\n - An optional `subreason` that represents a short summary of why the device had to reboot or shutdown (or who rebooted or shutdown the device).\n - One or more optional `detail` values. A `detail` may point to a subsystem to aid in determining which specific system resulted in the `subreason`. You can specify multiple `detail` values, which should generally follow a hierarchy of importance. However, it's also acceptable to report multiple `detail` values of equal importance.\n\n\nAn empty value for `bootloader_boot_reason_prop` is considered\nillegal (as this allows other agents to inject a boot reason after the fact).\n\n### Reason requirements\n\n\nThe value given for `reason` (first span, prior to termination or\ncomma) must be of the following set divided into kernel, strong, and blunt\nreasons:\n\n- kernel set:\n - \"`watchdog\"`\n - `\"kernel_panic\"`\n- strong set:\n - `\"recovery\"`\n - `\"bootloader\"`\n- blunt set:\n - `\"cold\"`. Generally indicates a full reset of all devices, including memory.\n - `\"hard\"`. Generally indicates the hardware has its state reset and `ramoops` should retain persistent content.\n - `\"warm\"`. Generally indicates the memory and the devices retain some state, and the `ramoops` (see `pstore` driver in kernel) backing store contains persistent content.\n - `\"shutdown\"`\n - `\"reboot\"`. Generally means the `ramoops` state is unknown and the hardware state is unknown. This value is a catchall as the `cold`, `hard`, and `warm` values provide clues as to the depth of the reset for the device.\n\n\nBootloaders must provide a kernel set or a blunt set `reason`, and\nare strongly encouraged to provide a `subreason` if it can be\ndetermined. For example, a power key long press that may or may not have\n`ramoops` backup would have the boot reason\n`\"reboot,longkey\"`.\n\n\nNo first-span `reason` can be part of any `subreason` or\n`detail`. However, because kernel set reasons cannot be produced by\nuser space, `\"watchdog\"` may be reused after a blunt set reason,\nalong with a detail of the source (for example,\n`\"reboot,watchdog,service_manager_unresponsive\"`, or\n`\"reboot,software,watchdog\"`).\n\n\nBoot reasons should not require expert internal knowledge to decipher and/or\nshould be human readable with an intuitive report. Examples:\n`\"shutdown,vbxd\"` (bad), `\"shutdown,uv\"` (better),\n`\"shutdown,undervoltage\"` (preferred).\n\n### Reason-subreason combinations\n\n\nAndroid reserves a set of `reason`-`subreason`\ncombinations that should not be overloaded in normal usage but can be used on\na case-by-case basis if the combination accurately reflects the associated\ncondition. Examples of reserved combinations include:\n\n- `\"reboot,userrequested\"`\n- `\"shutdown,userrequested\"`\n- `\"shutdown,thermal\"` (from `thermald`)\n- `\"shutdown,battery\"`\n- `\"shutdown,battery,thermal\"` (from `BatteryStatsService`)\n- `\"reboot,adb\"`\n- `\"reboot,shell\"`\n- `\"reboot,bootloader\"`\n- `\"reboot,recovery\"`\n\n\nFor more details, refer to `kBootReasonMap` in\n`system/core/bootstat/bootstat.cpp` and the associated git\nchangelog history in the Android source repository.\n\nReport boot reasons\n-------------------\n\n\nAll boot reasons, either from the bootloader or recorded in the canonical boot\nreason, must be recorded in the `kBootReasonMap` section of\n`system/core/bootstat/bootstat.cpp`. The\n`kBootReasonMap` list is a mix of compliant and legacy\nnoncompliant reasons. Bootloader developers should register only new\ncompliant reasons here (and shouldn't register noncompliant reasons unless\nthe product has already shipped and cannot be changed).\n| **Note:** While `system/core/bootstat/bootstat.cpp` contains a `kBootReasonMap` section that lists a considerable number of legacy reasons, the presence of these reasons does not mean the `reason` string is approved for use. A subset of the list represents compliant reasons; we expect this subset to grow as bootloader authors register and explain additional compliant reasons.\n\n\nWe strongly recommend using existing, compliant entries in\n`system/core/bootstat/bootstat.cpp` and exercising restraint before\nusing a noncompliant string. As a guideline, it is:\n\n- **OK** to report `\"kernel_panic\"` from the bootloader, as `bootstat` may be able to inspect `ramoops` for `kernel_panic signatures` to refine the subreasons into the canonical `system_boot_reason_prop`.\n- **Not OK** to report a noncompliant string in `kBootReasonMap` (such as `\"panic\")` from the bootloader, as this will ultimately break the ability to refine the `reason`.\n\n\nFor example, if `kBootReasonMap` contains `\"wdog_bark\"`,\na bootloader developer should:\n\n- Change to `\"watchdog,bark\"` and add to the list in `kBootReasonMap`.\n- Consider what `\"bark\"` means for those unfamiliar with the technology and determine if a more meaningful `subreason` is available.\n\nVerify boot reason compliance\n-----------------------------\n\n\nAt this time, Android does not provide an active CTS test that can accurately\ntrigger or inspect all possible boot reasons a bootloader could provide;\npartners can still attempt to run a passive test to determine compatibility.\n\n\nAs a result, bootloader compliance requires bootloader developers to\nvoluntarily adhere to the spirit of the rules and guidelines described above.\nWe urge such developers to contribute to AOSP (specifically to\n`system/core/bootstat/bootstat.cpp`) and use this opportunity as a\nforum for discussions about boot reason issues."]]
