Implementing Scoped Vendor Logging

Android 11 adds a new HAL, IDumpstateDevice (version 1.1). This HAL exposes new methods to more tightly scope vendor logs that are included in standard bug reports, as well as to allow user builds to turn vendor logging on and off (the default for user builds is off). This gives OEMs more control over what gets included in particular types of bug reports.

This feature impacts OEMs if they choose to implement this optional HAL. SoCs might be impacted, depending on what the OEM chooses to expose with this HAL. There’s no expected impact to carriers.

What you include in bug reports depends on which information you find relevant for debugging, but generally more verbose is better.

Examples and source

There's a default implementation of the (deprecated) 1.0 version of IDumpstateDevice that shows an example of using the dumpstate util library: frameworks/native/cmds/dumpstate/DumpstateUtil.h. There's also a Cuttlefish implementation of the 1.1 HAL: device/google/cuttlefish/guest/monitoring/dumpstate_ext/*.

The source code is located here:

Implementation

To implement this HAL, implement the android.hardware.dumpstate@1.1::IDumpstateDevice HAL interface. There are many possible DumpstateMode values, but not all are likely to be supported by a single device (for example, WEAR for non-Wear OS devices).

Implementing the dumpstate HAL is optional. All new devices launching with Android 11 MUST implement IDumpstateDevice 1.1 if they implement the Dumpstate HAL. Devices that have already implemented IDumpstateDevice 1.0 prior to Android 11 should be relatively easy to upgrade to 1.1, and doing so is strongly recommended, as it greatly reduces the amount of extraneous private information included in bug reports.

This feature depends on the core dumpstate changes also included with Android 11, located under frameworks/native/cmds/dumpstate.

Implementing this HAL will likely require some SEPolicy changes to certain system properties, files, etc. to get things fully working, and will require coordination with vendors to dump all relevant information into bug reports.

Customization

The device user can toggle vendor logging on or off using developer settings. When it's turned off, dumpstateBoard_1_1 may still output minimal essential information as determined by the OEM. Turning vendor logging off makes IDumpstateDevice::dumpstateBoard add only essential information to a bug report, while turning it on includes whatever information the OEM chooses.

You can modify dumpstate.cpp (which calls the IDumpstateDevice HAL methods), for example, to increase the timeout given for dumpstateBoard to complete. However, the core logic of dumpstate.cpp should remain unchanged.

Timeouts can be any value, but they shouldn't dramatically increase the time that a bug report takes to complete. In particular, DumpstateMode::CONNECTIVITY is highly time sensitive and needs to run as fast as possible to collect all relevant modem/Wi-Fi/networking logs.

Validation

There's a VTS test for the IDumpstateDevice implementation, and there are functional unit tests for general BugreportManager functionality.

The recommended manual test case is frameworks/base/core/tests/bugreports/src/android/server/bugreports/BugreportManagerTest.java.