Skip to content

EXTENDROM_BOOT_DEBUG

Jump to bottom
steadfasterX edited this page Jun 9, 2023 · 15 revisions

EXTENDROM_BOOT_DEBUG

Current state: beta (only available in testing branch)
Supported[1] Android versions: A9, A10, A11, A12, A13

[1] might work on lower and/or higher Android versions, too but that is untested

flag values meaning where to configure
required EXTENDROM_BOOT_DEBUG can be unset or true set to true if you want to activate the boot debugger vendorsetup.sh or <device>.mk
optional EXTENDROM_DEBUG_PATH set this only when you need to override the default* the base path where logs get saved to
note: this path will always get the suffix boot_debug/ so just specify the main path		 vendorsetup.sh or <device>.mk
optional EXTENDROM_DEBUG_PATH_SIZE_FULL set this only when you need to override the default size in kilobytes for the unfiltered log vendorsetup.sh or <device>.mk
optional EXTENDROM_DEBUG_PATH_SIZE_CRASH set this only when you need to override the default size in kilobytes for the crash log vendorsetup.sh or <device>.mk
optional EXTENDROM_DEBUG_PATH_SIZE_KERNEL set this only when you need to override the default size in kilobytes for the kernel log vendorsetup.sh or <device>.mk
optional EXTENDROM_DEBUG_PATH_SIZE_SELINUX set this only when you need to override the default size in kilobytes for the selinux log vendorsetup.sh or <device>.mk

*Default path for EXTENDROM_DEBUG_PATH: /data/vendor_de
(keep in mind that the full path will be auto-expanded to: /data/vendor_de/boot_debug/)

Enables a logcat debugger running as early as possible to catch boot errors, early sepolicy denials and any other issues which might occur during boot.

Keep in mind that on non-eng builds (and sometimes even on insecure adb / -eng ones) you will be too late usually when you do adb logcat while booting. The logcat buffer gets overwritten too quickly - especially on recurring crashes during boot etc.

The most awesome thing is: it fully supports encrypted devices and selinux=enforcing out of the box without any changes.

Setup

Just set export EXTENDROM_BOOT_DEBUG=true and you are good to go.
Actually nothing else is needed - usually ;) ... but if you want/need to you can adjust the defaults.

Accessing the boot debug logs

EXTENDROM_DEBUG_PATH cannot be accessed by a regular user so you need either root or a (custom) recovery allowing to pull the logs.

You will find the following logs in EXTENDROM_DEBUG_PATH:

  1. EXTENDROM_DEBUG_PATH/boot_debug/full.txt -> unfiltered logcat for ALL buffers
  2. EXTENDROM_DEBUG_PATH/boot_debug/crash.txt -> filtered logcat just with crash traces (if any)
  3. EXTENDROM_DEBUG_PATH/boot_debug/kernel.txt -> filtered logcat just with kernel messages*
  4. EXTENDROM_DEBUG_PATH/boot_debug/selinux.txt -> filtered logcat just with selinux denials

(*)note: kernel logs will appear on userdebug and/or eng builds only!

Deprecated stuff

The reasons why /cache/debug is not the default (anymore) are:

  • some devices have a very small cache partition which either causes unexpected crashes or simply don't get relevant logs
  • during e.g. the (force) encryption process the cache get even cleared so it is not very useful at all (while sometimes better then nothing ofc)

*FBE = "File Based Encryption". FDE = "Full Disk Encryption". If your device uses the (now deprecated) FDE method the EXTENDROM_DEBUG_PATH should go to e.g. /cache/debug as due to the nature of FDE there is no exclusion of paths possible. Read Note3 above though.

Changing EXTENDROM_DEBUG_PATH

If you are NOT using encryption (FBE*) and you don't enforce selinux you can basically choose any path you wish for EXTENDROM_DEBUG_PATH. When you are trying to debug (FBE*) encrypted devices though you might have to choose a proper path so you can access it later when boot fails.

EXTENDROM_BOOT_DEBUG comes with all required sepolicies so supports selinux=enforcing builds. Speaking of that if you change EXTENDROM_DEBUG_PATH to anything other then the default (see above) you likely have to fight with selinux. So change this variable only if you run selinux in permissive mode or if you know how to write own selinux policies.

The following is just for those wanting to change EXTENDROM_DEBUG_PATH and having FBE enabled.

Depending on which Android version you build on there are several options to set EXTENDROM_DEBUG_PATH on FBE encrypted devices:

Android 9 and lower hard coded encryption exceptions here:

Android 10 hard coded encryption exceptions here:

Android 11 and later:

  • here things become easy finally. The debug path can be handled directly within init and the mkdir command (encryption=None) that means you can basically use any path which is writable at boot time.
  • While you are free to choose any it is recommended setting export EXTENDROM_DEBUG_PATH=/data/vendor_de/debug even for A11 and later. This way you don't have to care about selinux.
  • Note: For Android 11 and later extendrom will automatically ensure that whatever path you use as EXTENDROM_DEBUG_PATH it will NOT get encrypted - so you can access it via recovery.
Clone this wiki locally