Android 9 includes the following changes to the bootloader boot reason specification.
A bootloader uses uniquely-available hardware and memory resources to
determine why a device rebooted, then communicates that determination by
androidboot.bootreason=<reason> to the Android
kernel command line for its launch.
init then translates this
command line to propagate to the Android property
For devices launching with Android 12 or later,
using kernel version 5.10 or greater,
is added to bootconfig instead of the kernel command line.
Boot reason specifications
Previous releases of Android specified a boot reason format that used no
spaces, was all lowercase, included few requirements (such as for reporting
hard), and which made
allowances for other unique reasons. This loose specification resulted in the
proliferation of hundreds of custom (and sometimes meaningless) boot reason
strings, which in turn led to an unmanageable situation. As of the current
Android release, the sheer momentum of near unparseable or meaningless content
filed by the bootloader has created compliance issues for
With the Android 9 release, the Android team
recognizes that the legacy
substantial momentum and cannot be re-written at runtime. Any improvements to
the boot reason specification must therefore come from interactions with
bootloader developers and tweaks to the existing system. To that end the
Android team is:
- Engaging with bootloader developers to encourage them to:
- Provide canonical, parseable, and recognizable reasons to
- Participate in the
- Provide canonical, parseable, and recognizable reasons to
- Adding a controlled and runtime-rewritable source of the
sys.boot.reason). A limited set of system applications (such as
init) can rewrite this property, but all applications can be granted sepolicy rights to read it.
- Informing users of the boot reason to wait until after userdata is mounted
before trusting the content in the system boot reason property
Why so late? While
bootloader_boot_reason_prop is available early
on in boot, it is blocked by the Android security policy on an as-need basis
because it represents inaccurate, unparseable, and noncanonical information.
In most situations, only developers with deep knowledge of the boot system
should need to access this information. A refined, parseable, and canonical
API for boot reason via
system_boot_reason_prop can be reliably
and accurately picked up only after userdata has mounted.
- Before userdata has mounted,
system_boot_reason_propwill contain the value from
- After userdata has mounted,
system_boot_reason_propmay be updated to be compliant or to report more accurate information.
For this reason, Android 9 extends the period of
time before the boot reason can be officially acquired, changing it from being
immediately accurate in boot (with
to being available only after userdata has mounted (with
Bootstat logic depends on a more informative and compliant
bootloader_boot_reason_prop. When that property uses a
predictable format, it improves the accuracy of all controlled reboot and
shutdown scenarios, which in turn refines and expands the accuracy and meaning
Canonical boot reason format
The canonical boot reason format for
in Android 9 uses the following syntax:
- Lower case
- No blanks (use underline)
- All printable characters
subreason, and one or more
- A required
reasonthat represents the highest priority reason why the device had to reboot or shutdown.
- An optional
subreasonthat represents a short summary of why the device had to reboot or shutdown (or who rebooted or shutdown the device).
- One or more optional
detailmay point to a subsystem to aid in determining which specific system resulted in the
subreason. You can specify multiple
detailvalues, which should generally follow a hierarchy of importance. However, it is also acceptable to report multiple
detailvalues of equal importance.
- A required
An empty value for
bootloader_boot_reason_prop is considered
illegal (as this allows other agents to inject a boot reason after the fact).
The value given for
reason (first span, prior to termination or
comma) must be of the following set divided into kernel, strong, and blunt
- kernel set:
- strong set:
- blunt set:
"cold". Generally indicates a full reset of all devices, including memory.
"hard". Generally indicates the hardware has its state reset and
ramoopsshould retain persistent content.
"warm". Generally indicates the memory and the devices retain some state, and the
pstoredriver in kernel) backing store contains persistent content.
"reboot". Generally means the
ramoopsstate is unknown and the hardware state is unknown. This value is a catchall as the
warmvalues provide clues as to the depth of the reset for the device.
Bootloaders must provide a kernel set or a blunt set
are strongly encouraged to provide a
subreason if it can be
determined. For example, a power key long press that may or may not have
ramoops backup would have the boot reason
reason can be part of any
detail. However, because kernel set reasons cannot be produced by
"watchdog" may be reused after a blunt set reason,
along with a detail of the source (e.g.
Boot reasons should not require expert internal knowledge to decipher and/or
should be human readable with an intuitive report. Examples:
Android reserves a set of
combinations that should not be overloaded in normal usage but can be used on
a case-by-case basis if the combination accurately reflects the associated
condition. Examples of reserved combinations include:
For more details, refer to
system/core/bootstat/bootstat.cpp and the associated git
changelog history in the Android source repository.
Reporting boot reasons
All boot reasons, either from the bootloader or recorded in the canonical boot
reason, must be recorded in the
kBootReasonMap section of
kBootReasonMap list is a mix of compliant and legacy
non-compliant reasons. Bootloader developers should register only new
compliant reasons here (and should not register non-compliant reasons unless
the product has already shipped and cannot be changed).
We strongly recommend using existing, compliant entries in
system/core/bootstat/bootstat.cpp and exercising restraint before
using a non-compliant string. As a guideline, it is:
- OK to report
"kernel_panic"from the bootloader, as
bootstatmay be able to inspect
kernel_panic signaturesto refine the subreasons into the canonical
- Not OK to report a non-compliant string in
"panic")from the bootloader, as this will ultimately break the ability to refine the
For example, if
a bootloader developer should:
- Change to
"watchdog,bark"and add to the list in
- Consider what
"bark"means for those unfamiliar with the technology and determine if a more meaningful
Verifying boot reason compliance
At this time, Android does not provide an active CTS test that can accurately trigger or inspect all possible boot reasons a bootloader could provide; partners can still attempt to run a passive test to determine compatibility.
As a result, bootloader compliance requires bootloader developers to
voluntarily adhere to the spirit of the rules and guidelines described above.
We urge such developers to contribute to AOSP (specifically to
system/core/bootstat/bootstat.cpp) and use this opportunity as a
forum for discussions about boot reason issues.