Use DebugFS in Android 12

Devices that launch with Android 12 using kernel versions higher than v5.4 are required to ship with the GKI kernel. So that partners can access DebugFS in userdebug builds while they develop on the GKI kernel, the kernel config CONFIG_DEBUG_FS is enabled in the GKI defconfig. Never mount DebugFS in user builds for devices launching on Android 12.

Userdebug builds have better test coverage than user builds and get heavily tested throughout the development cycle. The following plan minimizes the difference between the two build types with respect to DebugFS access, and provides these benefits:

  • Prevents userdebug builds from accidentally depending on DebugFS for new functionality
  • Ensures that any existing functionality that's broken by the lack of DebugFS is known early in the development cycle

Debugfs accesses in userdebug builds are categorized as follows:

  1. DebugFS file initializations during device boot, such as a write access to a file in DebugFS to turn on debug data collection.
  2. Bugreport generation: The dumpstate HAL reads DebugFS files when DumpstateBoard() is invoked by dumpstate. This information becomes part of the bug report.
  3. Device-specific testing and validation.

The following table describes how each of these three categories is supported in Android 12. Note that the following only applies to userdebug builds since DebugFS can't be mounted in user builds.

Use case Android 12 userdebug build
One-time DebugFS files initialization, during startup. This access happens only once during boot time. Dumpstate HAL performs this during HAL initialization. To enable the same, init mounts DebugFS in userdebug builds before the HAL initializes. Init calls umount() on DebugFS when the device has completed booting.
Bugreport generation: The dumpstate HAL reads DebugFS files, which become part of the bug report. Done by dumpstate HAL within DumpstateBoard() when invoked by dumpstate (DumpstateDevice.cpp). The dumpstate tool (part of the Android framework) ensures that DebugFS mounts during the invocation.
Device-specific testing and validation Adb root and shell. Mount DebugFS from the adb shell with root access1.

1To mount DebugFS from adb shell with root access, use this command:

adb shell mount -t debugfs debugfs /sys/kernel/debug.

Required partner actions

Partners must enact the following based on these changes in Android 12 devices:

  • Make all boot time initializations of DebugFS nodes happen during the dumpstate HAL initialization. For an example of how to do this, see DNM: Example for boot time initialization of DebugFS files.
  • Don't allow DebugFS access during runtime. The following exceptions apply:
    • Bugreport generation (comes from the dumpstate HAL)
    • Testing and validation (accessible by adb root and shell - ensure that DebugFS is mounted first)

Developers can set the debug persistent property persist.dbg.keep_debugfs_mounted to keep DebugFs mounted across reboots on userdebug and eng builds.

GTS compliance tests ensure that the DebugFS filesystem isn't mounted in user builds. Sepolicy neverallow statements ensure that in devices launching on Android 12 or higher, unauthorized processes aren't provided access to DebugFs.