1# Debugging the CHRE Framework 2 3[TOC] 4 5This section lists the methods that can be used to aid in CHRE framework 6debugging. 7 8## Logging 9 10The CHRE framework invokes the `LOGx()` macros defined in 11`platform/include/chre/platform/log.h` to log information into the system, 12for printf-style debugging. This capability is also exposed to nanoapps via 13`chreLog()`. Although it may not be strictly required, it is strongly 14recommended that the platform implementation directs these log messages to 15Android’s logcat system under the “CHRE” tag, where they will be automatically 16collected in bug reports. These logs must not wake the applications processor 17(AP), so they should be buffered on a best-effort basis and flushed to the AP 18opportunistically when it wakes up. 19 20### Log levels 21 22CHRE framework currently supports four levels, namely Error `LOGE()`, Warning 23` LOGW()`, Info `LOGI()` and Debug `LOGD()`. These correspond to the 24equivalent [logcat 25levels](https://source.android.com/setup/contribute/code-style#log-sparingly). 26Choosing an appropriate level for logs, and logging only the necessary 27information to identify and debug failures can help avoid issues with “log 28spam”, such as log output that is difficult to read, or uninteresting “spammy” 29logs causing useful log messages to be pushed out of limited buffering space. 30 31### Log level filtering 32 33The CHRE framework currently only supports compile-time log level filtering. 34While it’s recommended to leave it at the default setting, the 35`CHRE_MINIMUM_LOG_LEVEL` build flag can be defined to one of the values set 36in `util/include/chre/util/log_common.h` to control which log levels are 37included in the binary. 38 39## Debug Dumps 40 41A debug dump is human-readable text produced on-demand for debugging purposes. 42While `LOGx()` is useful for logging events as they happen, the debug dump is 43a complementary function typically used to output a snapshot of the framework's 44state, history, vital statistics, etc. The debug dump is especially useful for 45information that would be too spammy to log on every change, but is useful to 46diagnose potential issues. The CHRE framework produces a debug dump when 47requested via the Context Hub HAL’s built-in `debug()` method, which is 48automatically collected as part of the bug report process, and can be manually 49triggered via ADB using the following command: 50 51`adb root && adb shell lshal debug android.hardware.contexthub@1.0::IContexthub/default` 52 53`DebugDumpManager` is the framework module responsible for collecting debug 54dumps from the CHRE framework and nanoapps. Refer to the associated 55documentation in the source code for details on this process. 56 57## CHRE_ASSERT and CHRE_ASSERT_LOG 58 59`CHRE_ASSERT()` and `CHRE_ASSERT_LOG()` can be used to help catch 60programmatic errors during development. However, since their use may have 61memory impact, they can be disabled by setting `CHRE_ASSERTIONS_ENABLED` to 62false in the Makefile. In general, assertions should be used sparingly - they 63are best applied to situations that would lead to potentially unrecoverable 64logical errors that are not handled by the code. For comparison, asserting that 65a pointer is not null is generally an anti-pattern (though the current CHRE 66codebase is not free of this), as dereferencing null would produce a crash 67anyways which should have equivalent debuggability as an assertion, among other 68reasons. 69