• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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(HIDL HAL)
52`adb root && adb shell lshal debug android.hardware.contexthub@1.0::IContexthub/default`
53
54(AIDL HAL)
55`adb root && adb shell dumpsys android.hardware.contexthub.IContextHub/default`
56
57`DebugDumpManager` is the framework module responsible for collecting debug
58dumps from the CHRE framework and nanoapps. Refer to the associated
59documentation in the source code for details on this process.
60
61## CHRE_ASSERT and CHRE_ASSERT_LOG
62
63`CHRE_ASSERT()` and `CHRE_ASSERT_LOG()` can be used to help catch
64programmatic errors during development. However, since their use may have
65memory impact, they can be disabled by setting `CHRE_ASSERTIONS_ENABLED` to
66false in the Makefile. In general, assertions should be used sparingly - they
67are best applied to situations that would lead to potentially unrecoverable
68logical errors that are not handled by the code. For comparison, asserting that
69a pointer is not null is generally an anti-pattern (though the current CHRE
70codebase is not free of this), as dereferencing null would produce a crash
71anyways which should have equivalent debuggability as an assertion, among other
72reasons.
73