73 lines
3.4 KiB
Markdown
73 lines
3.4 KiB
Markdown
|
# Debugging the CHRE Framework
|
|||
|
|
|
|||
|
|
[TOC]
|
|||
|
|
|
|||
|
|
This section lists the methods that can be used to aid in CHRE framework
|
|||
|
|
debugging.
|
|||
|
|
|
|||
|
|
## Logging
|
|||
|
|
|
|||
|
|
The CHRE framework invokes the `LOGx()` macros defined in
|
|||
|
|
`platform/include/chre/platform/log.h` to log information into the system,
|
|||
|
|
for printf-style debugging. This capability is also exposed to nanoapps via
|
|||
|
|
`chreLog()`. Although it may not be strictly required, it is strongly
|
|||
|
|
recommended that the platform implementation directs these log messages to
|
|||
|
|
Android’s logcat system under the “CHRE” tag, where they will be automatically
|
|||
|
|
collected in bug reports. These logs must not wake the applications processor
|
|||
|
|
(AP), so they should be buffered on a best-effort basis and flushed to the AP
|
|||
|
|
opportunistically when it wakes up.
|
|||
|
|
|
|||
|
|
### Log levels
|
|||
|
|
|
|||
|
|
CHRE framework currently supports four levels, namely Error `LOGE()`, Warning
|
|||
|
|
` LOGW()`, Info `LOGI()` and Debug `LOGD()`. These correspond to the
|
|||
|
|
equivalent [logcat
|
|||
|
|
levels](https://source.android.com/setup/contribute/code-style#log-sparingly).
|
|||
|
|
Choosing an appropriate level for logs, and logging only the necessary
|
|||
|
|
information to identify and debug failures can help avoid issues with “log
|
|||
|
|
spam”, such as log output that is difficult to read, or uninteresting “spammy”
|
|||
|
|
logs causing useful log messages to be pushed out of limited buffering space.
|
|||
|
|
|
|||
|
|
### Log level filtering
|
|||
|
|
|
|||
|
|
The CHRE framework currently only supports compile-time log level filtering.
|
|||
|
|
While it’s recommended to leave it at the default setting, the
|
|||
|
|
`CHRE_MINIMUM_LOG_LEVEL` build flag can be defined to one of the values set
|
|||
|
|
in `util/include/chre/util/log_common.h` to control which log levels are
|
|||
|
|
included in the binary.
|
|||
|
|
|
|||
|
|
## Debug Dumps
|
|||
|
|
|
|||
|
|
A debug dump is human-readable text produced on-demand for debugging purposes.
|
|||
|
|
While `LOGx()` is useful for logging events as they happen, the debug dump is
|
|||
|
|
a complementary function typically used to output a snapshot of the framework's
|
|||
|
|
state, history, vital statistics, etc. The debug dump is especially useful for
|
|||
|
|
information that would be too spammy to log on every change, but is useful to
|
|||
|
|
diagnose potential issues. The CHRE framework produces a debug dump when
|
|||
|
|
requested via the Context Hub HAL’s built-in `debug()` method, which is
|
|||
|
|
automatically collected as part of the bug report process, and can be manually
|
|||
|
|
triggered via ADB using the following command:
|
|||
|
|
|
|||
|
|
(HIDL HAL)
|
|||
|
|
`adb root && adb shell lshal debug android.hardware.contexthub@1.0::IContexthub/default`
|
|||
|
|
|
|||
|
|
(AIDL HAL)
|
|||
|
|
`adb root && adb shell dumpsys android.hardware.contexthub.IContextHub/default`
|
|||
|
|
|
|||
|
|
`DebugDumpManager` is the framework module responsible for collecting debug
|
|||
|
|
dumps from the CHRE framework and nanoapps. Refer to the associated
|
|||
|
|
documentation in the source code for details on this process.
|
|||
|
|
|
|||
|
|
## CHRE_ASSERT and CHRE_ASSERT_LOG
|
|||
|
|
|
|||
|
|
`CHRE_ASSERT()` and `CHRE_ASSERT_LOG()` can be used to help catch
|
|||
|
|
programmatic errors during development. However, since their use may have
|
|||
|
|
memory impact, they can be disabled by setting `CHRE_ASSERTIONS_ENABLED` to
|
|||
|
|
false in the Makefile. In general, assertions should be used sparingly - they
|
|||
|
|
are best applied to situations that would lead to potentially unrecoverable
|
|||
|
|
logical errors that are not handled by the code. For comparison, asserting that
|
|||
|
|
a pointer is not null is generally an anti-pattern (though the current CHRE
|
|||
|
|
codebase is not free of this), as dereferencing null would produce a crash
|
|||
|
|
anyways which should have equivalent debuggability as an assertion, among other
|
|||
|
|
reasons.
|