Skip to content

EXTENDROM_BOOT_DEBUG

Jump to bottom
steadfasterX edited this page Aug 21, 2024 · 15 revisions

EXTENDROM_BOOT_DEBUG

State

State Branch Supported Android version(s) Tested on
STABLE main A9, A10, A11, A12, A13, A14 A9, A10, A11, A12, A13

(*) A14 is untested but should work

Flags

Where to configure:

  • device/<vendor>/<model>/vendorsetup.sh (recommended)
  • or device/<vendor>/<model>/<any>.mk (check build process!)
required flag values meaning
yes EXTENDROM_BOOT_DEBUG can be unset or true set to true if you want to activate the boot debugger
no 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
no 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)
no 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)
no 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)
no 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)

*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. /mnt/vendor/persist or /persist
  3. /metadata

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".

why are multiple locations possible for EXTENDROM_DEBUG_PATH?

The reason behind that is that /metadata, /mnt/vendor/persist or /persist are usually quite small but your only chance to get logs when you cannot decrypt /data or want to debug the encryption on boot.

why is /cache not supported anymore?

actually it is - as long as you build with selinux=permissive. Here are the full reasons behind you might want to avoid it nevertheless:

  1. creating files in /cache will fire a neverallow as this is part of the system core files - which means /cache still works as long as you do not build with selinux=enforcing
  2. some devices have a very small /cache partition
  3. newer Android versions do not have a separate /cache partition anymore (actually /cache will symlink to /data here - which gets encrypted)
  4. 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..

... when using selinux=enforcing:

  1. are you able to access the EXTENDROM_DEBUG_PATH (e.g in recovery or in Android with root)?
    • if "no": use one of /mnt/vendor/persist, /persist or /metadata
    • if "yes": keep the default, i.e. do not set EXTENDROM_DEBUG_PATH at all

... when using selinux=permissive:

  1. are you able to access the EXTENDROM_DEBUG_PATH (e.g in recovery or in Android with root)?
    • if "yes": keep the default, i.e. do not set EXTENDROM_DEBUG_PATH at all
    • if "no": go on:
  2. do you have a separate /cache partition?
    • if "yes": use /cache
    • if "no": use one of /mnt/vendor/persist, /persist or /metadata

Besides the above if you have to choose one of use one of /mnt/vendor/persist, /persist or /metadata 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