android-ndk-r26d-linux.zip

# Simpleperf Android Studio includes a graphical front end to Simpleperf, documented in [Inspect CPU activity with CPU Profiler](https://developer.android.com/studio/profile/cpu-profiler). Most users will prefer to use that instead of using Simpleperf directly. Simpleperf is a native CPU profiling tool for Android. It can be used to profile both Android applications and native processes running on Android. It can profile both Java and C++ code on Android. The simpleperf executable can run on Android >=L, and Python scripts can be used on Android >= N. Simpleperf is part of the Android Open Source Project. The source code is [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/). The latest document is [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/README.md). [TOC] ## Introduction An introduction slide deck is [here](./introduction.pdf). Simpleperf contains two parts: the simpleperf executable and Python scripts. The simpleperf executable works similar to linux-tools-perf, but has some specific features for the Android profiling environment: 1. It collects more info in profiling data. Since the common workflow is "record on the device, and report on the host", simpleperf not only collects samples in profiling data, but also collects needed symbols, device info and recording time. 2. It delivers new features for recording. 1) When recording dwarf based call graph, simpleperf unwinds the stack before writing a sample to file. This is to save storage space on the device. 2) Support tracing both on CPU time and off CPU time with --trace-offcpu option. 3) Support recording callgraphs of JITed and interpreted Java code on Android >= P. 3. It relates closely to the Android platform. 1) Is aware of Android environment, like using system properties to enable profiling, using run-as to profile in application's context. 2) Supports reading symbols and debug information from the .gnu_debugdata section, because system libraries are built with .gnu_debugdata section starting from Android O. 3) Supports profiling shared libraries embedded in apk files. 4) It uses the standard Android stack unwinder, so its results are consistent with all other Android tools. 4. It builds executables and shared libraries for different usages. 1) Builds static executables on the device. Since static executables don't rely on any library, simpleperf executables can be pushed on any Android device and used to record profiling data. 2) Builds executables on different hosts: Linux, Mac and Windows. These executables can be used to report on hosts. 3) Builds report shared libraries on different hosts. The report library is used by different Python scripts to parse profiling data. Detailed documentation for the simpleperf executable is [here](#executable-commands-reference). Python scripts are split into three parts according to their functions: 1. Scripts used for recording, like app_profiler.py, run_simpleperf_without_usb_connection.py. 2. Scripts used for reporting, like report.py, report_html.py, inferno. 3. Scripts used for parsing profiling data, like simpleperf_report_lib.py. The python scripts are tested on Python >= 3.9. Older versions may not be supported. Detailed documentation for the Python scripts is [here](#scripts-reference). ## Tools in simpleperf The simpleperf executables and Python scripts are located in simpleperf/ in ndk releases, and in system/extras/simpleperf/scripts/ in AOSP. Their functions are listed below. bin/: contains executables and shared libraries. bin/android/${arch}/simpleperf: static simpleperf executables used on the device. bin/${host}/${arch}/simpleperf: simpleperf executables used on the host, only supports reporting. bin/${host}/${arch}/libsimpleperf_report.${so/dylib/dll}: report shared libraries used on the host. *.py, inferno, purgatorio: Python scripts used for recording and reporting. Details are in [scripts_reference.md](scripts_reference.md). ## Android application profiling See [android_application_profiling.md](./android_application_profiling.md). ## Android platform profiling See [android_platform_profiling.md](./android_platform_profiling.md). ## Executable commands reference See [executable_commands_reference.md](./executable_commands_reference.md). ## Scripts reference See [scripts_reference.md](./scripts_reference.md). ## View the profile See [view_the_profile.md](./view_the_profile.md). ## Answers to common issues ### Support on different Android versions On Android < N, the kernel may be too old (< 3.18) to support features like recording DWARF based call graphs. On Android M - O, we can only profile C++ code and fully compiled Java code. On Android >= P, the ART interpreter supports DWARF based unwinding. So we can profile Java code. On Android >= Q, we can used simpleperf shipped on device to profile released Android apps, with `<profileable android:shell="true" />`. ### Comparing DWARF based and stack frame based call graphs Simpleperf supports two ways recording call stacks with samples. One is DWARF based call graph, the other is stack frame based call graph. Below is their comparison: Recording DWARF based call graph: 1. Needs support of debug information in binaries. 2. Behaves normally well on both ARM and ARM64, for both Java code and C++ code. 3. Can only unwind 64K stack for each sample. So it isn't always possible to unwind to the bottom. However, this is alleviated in simpleperf, as explained in the next section. 4. Takes more CPU time than stack frame based call graphs. So it has higher overhead, and can't sample at very high frequency (usually <= 4000 Hz). Recording stack frame based call graph: 1. Needs support of stack frame registers. 2. Doesn't work well on ARM. Because ARM is short of registers, and ARM and THUMB code have different stack frame registers. So the kernel can't unwind user stack containing both ARM and THUMB code. 3. Also doesn't work well on Java code. Because the ART compiler doesn't reserve stack frame registers. And it can't get frames for interpreted Java code. 4. Works well when profiling native programs on ARM64. One example is profiling surfacelinger. And usually shows complete flamegraph when it works well. 5. Takes much less CPU time than DWARF based call graphs. So the sample frequency can be 10000 Hz or higher. So if you need to profile code on ARM or profile Java code, DWARF based call graph is better. If you need to profile C++ code on ARM64, stack frame based call graphs may be better. After all, you can fisrt try DWARF based call graph, which is also the default option when `-g` is used. Because it always produces reasonable results. If it doesn't work well enough, then try stack frame based call graph instead. ### Fix broken DWARF based call graph A DWARF-based call graph is generated by unwinding thread stacks. When a sample is recorded, a kernel dumps up to 64 kilobytes of stack data. By unwinding the stack based on DWARF information, we can get a call stack. Two reasons may cause a broken call stack: 1. The kernel can only dump up to 64 kilobytes of stack data for each sample, but a thread can have much larger stack. In this case, we can't unwind to the thread start point. 2. We need binaries containing DWARF call frame information to unwind stack frames. The binary should have one of the following sections: .eh_frame, .debug_frame, .ARM.exidx or .gnu_debugdata. To mitigate these problems, For the missing stack data problem: 1. To alleviate it, simpleperf joins callchains (call stacks) after recording. If two callchains of a thread have an entry containing the same ip and sp address, then simpleperf tries to join them to make the callchains longer. So we can get more complete callchains by recording longer and joining more samples. This do