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_magisk-ng 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 (will be doubled) 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 (will be doubled) 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 (will be doubled) 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 (will be doubled) 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[.1] -> unfiltered logcat for ALL buffers
  2. EXTENDROM_DEBUG_PATH/boot_debug/crash.txt[.1] -> filtered logcat just with crash traces (if any)
  3. EXTENDROM_DEBUG_PATH/boot_debug/kernel.txt[.1] -> filtered logcat just with kernel messages*
  4. EXTENDROM_DEBUG_PATH/boot_debug/selinux.txt[.1] -> filtered logcat just with selinux denials

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

boot debug log rotation

so whatever we choose as EXTENDROM_DEBUG_PATH we want to ensure it does not fill up the whole partition, right?! Especially when EXTENDROM_DEBUG_PATH is set to another partition then the default.

That's why all logs have a default size - which gets doubled due to log rotation. The logcat command does not allow to set a rotation of 0 so we might end up with 2 files for each of the supported logs. After the given default size the process will rotate the log and add a suffix of .1 to each log which exceeds its limit.

You can easily adjust the max size for each log by setting the related flag(s) (see table above).

Supported locations for EXTENDROM_DEBUG_PATH

Due to the nature of selinux it is not possible to just choose a random path. Of course it would be also great to just have 1 path which fits for all devices.. well this is not the case so extendrom comes with 3 possible options to set EXTENDROM_DEBUG_PATH:

  1. /data/vendor_de (default!)
  2. /cache
  3. /mnt/vendor/persist or /persist

So WHEN do you might want to change the default path?

Tbh there is only 1 reason: encryption. If your device is encrypted and you want to debug the boot process it will not be possible to access the boot logs later - if your recovery is not able to decrypt the /data partition (regardless of FBE or FDE btw).

*FBE = "File Based Encryption". FDE = "Full Disk Encryption".

So why are /cache AND /persist both available here?

There are multiple reasons for that:

  • some devices have a small /cache partition
  • newer Android versions do not have a separate /cache partition anymore (actually /cache will symlink to /data here - which gets encrypted)
  • /mnt/vendor/persist or /persist are usually quite small but your only chance to get logs when you cannot decrypt /data
  • during e.g. the (force) encryption process /cache gets cleared so you will loose the most important and related logs

Do I need to change EXTENDROM_DEBUG_PATH or not?

So what you choose here depends on 3 simple questions:

  1. do you want to debug encryption?
    • if "yes": use /mnt/vendor/persist or /persist
    • if "no": keep the default, do not set EXTENDROM_DEBUG_PATH
  2. do you have a separate /cache partition? -> use /cache
  3. is /cache very small (like 10 MB free) -> use /mnt/vendor/persist or /persist

Besides the above if you have to choose one of /cache, /mnt/vendor/persist or /persist then you MIGHT want to adjust the logfile size(s) -> see the related flags in the table above.

Infos for (extendrom) developers only

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