diff options
Diffstat (limited to 'simpleperf/doc')
| -rw-r--r-- | simpleperf/doc/README.md | 19 | ||||
| -rw-r--r-- | simpleperf/doc/android_application_profiling.md | 12 | ||||
| -rw-r--r-- | simpleperf/doc/android_platform_profiling.md | 49 | ||||
| -rw-r--r-- | simpleperf/doc/executable_commands_reference.md | 3 | ||||
| -rw-r--r-- | simpleperf/doc/jit_symbols.md | 59 | ||||
| -rw-r--r-- | simpleperf/doc/scripts_reference.md | 5 |
6 files changed, 5 insertions, 142 deletions
diff --git a/simpleperf/doc/README.md b/simpleperf/doc/README.md index 2f3b0854..f0cddd2a 100644 --- a/simpleperf/doc/README.md +++ b/simpleperf/doc/README.md @@ -20,9 +20,8 @@ The latest document is [here](https://android.googlesource.com/platform/system/e - [Executable commands reference](#executable-commands-reference) - [Scripts reference](#scripts-reference) - [Answers to common issues](#answers-to-common-issues) - - [Why we suggest profiling on Android >= N devices?](#why-we-suggest-profiling-on-android--n-devices) + - [Why we suggest profiling on Android >= N devices?](#why-we-suggest-profiling-on-android-gt-n-devices) - [Suggestions about recording call graphs](#suggestions-about-recording-call-graphs) - - [Why we can't always get complete DWARF-based call graphs](#why-we-cant-always-get-complete-dwarf-based-call-graphs) - [How to solve missing symbols in report?](#how-to-solve-missing-symbols-in-report) - [Fix broken callchain stopped at C functions](#fix-broken-callchain-stopped-at-c-functions) - [Show annotated source code and disassembly](#show-annotated-source-code-and-disassembly) @@ -89,7 +88,7 @@ bin/${host}/${arch}/simpleperf: simpleperf executables used on the host, only su 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). +*.py, inferno: Python scripts used for recording and reporting. ## Android application profiling @@ -160,18 +159,6 @@ graphs. It can be supported in two ways: 1. Use unstripped native binaries when building the apk, as [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/demo/SimpleperfExampleWithNative/app/profiling.gradle). 2. Download unstripped native libraries on device, as [here](#fix-broken-callchain-stopped-at-c-functions). -### Why we can't always get complete DWARF-based call graphs? - -DWARF-based call graphs are generated by unwinding thread stacks. When a sample is generated, up to -64KB stack data is dumped by the kernel. By unwinding the stack based on dwarf information, we get -a callchain. But the thread stack can be much longer than 64KB. In that case, we can't unwind to -the thread start point. - -To alleviate the problem, simpleperf joins callchains after recording them. 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. In that case, the longer we run, the more samples we get. This makes it -more likely to get complete callchains, but it's still not guaranteed to get complete call graphs. - ### How to solve missing symbols in report? The simpleperf record command collects symbols on device in perf.data. But if the native libraries @@ -246,7 +233,7 @@ Patches can be uploaded to android-review.googlesource.com as [here](https://sou or sent to email addresses listed [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/OWNERS). If you want to compile simpleperf C++ source code, follow below steps: -1. Download AOSP main branch as [here](https://source.android.com/setup/build/requirements). +1. Download AOSP master branch as [here](https://source.android.com/setup/build/requirements). 2. Build simpleperf. ```sh $ . build/envsetup.sh diff --git a/simpleperf/doc/android_application_profiling.md b/simpleperf/doc/android_application_profiling.md index f0e06c08..259c121e 100644 --- a/simpleperf/doc/android_application_profiling.md +++ b/simpleperf/doc/android_application_profiling.md @@ -18,7 +18,6 @@ Profiling an Android application involves three steps: - [Record and report call graph](#record-and-report-call-graph) - [Report in html interface](#report-in-html-interface) - [Show flamegraph](#show-flamegraph) - - [Report in Android Studio](#report-in-android-studio) - [Record both on CPU time and off CPU time](#record-both-on-cpu-time-and-off-cpu-time) - [Profile from launch](#profile-from-launch) - [Control recording in application code](#control-recording-in-application-code) @@ -244,17 +243,6 @@ $ FlameGraph/stackcollapse-perf.pl out.perf >out.folded $ FlameGraph/flamegraph.pl out.folded >a.svg ``` -## Report in Android Studio - -simpleperf report-sample command can convert perf.data into protobuf format accepted by -Android Studio cpu profiler. The conversion can be done either on device or on host. If you have -more symbol info on host, then prefer do it on host with --symdir option. - -```sh -$ simpleperf report-sample --protobuf --show-callchain -i perf.data -o perf.trace -# Then open perf.trace in Android Studio to show it. -``` - ## Record both on CPU time and off CPU time We can [record both on CPU time and off CPU time](executable_commands_reference.md#record-both-on-cpu-time-and-off-cpu-time). diff --git a/simpleperf/doc/android_platform_profiling.md b/simpleperf/doc/android_platform_profiling.md index 21cf0f42..afa1927b 100644 --- a/simpleperf/doc/android_platform_profiling.md +++ b/simpleperf/doc/android_platform_profiling.md @@ -1,19 +1,10 @@ # Android platform profiling -## Table of Contents -- [Android platform profiling](#android-platform-profiling) - - [Table of Contents](#table-of-contents) - - [General Tips](#general-tips) - - [Start simpleperf from system_server process](#start-simpleperf-from-system_server-process) - - [Hardware PMU counter limit](#hardware-pmu-counter-limit) - -## General Tips - Here are some tips for Android platform developers, who build and flash system images on rooted devices: 1. After running `adb root`, simpleperf can be used to profile any process or system wide. -2. It is recommended to use the latest simpleperf available in AOSP main, if you are not working -on the current main branch. Scripts are in `system/extras/simpleperf/scripts`, binaries are in +2. It is recommended to use the latest simpleperf available in AOSP master, if you are not working +on the current master branch. Scripts are in `system/extras/simpleperf/scripts`, binaries are in `system/extras/simpleperf/scripts/bin/android`. 3. It is recommended to use `app_profiler.py` for recording, and `report_html.py` for reporting. Below is an example. @@ -43,39 +34,3 @@ $ python binary_cache_builder.py -lib $ANDROID_PRODUCT_OUT/symbols $ python report_html.py --add_source_code --source_dirs $ANDROID_BUILD_TOP --add_disassembly \ --binary_filter surfaceflinger.so ``` - -## Start simpleperf from system_server process - -Sometimes we want to profile a process/system-wide when a special situation happens. In this case, -we can add code starting simpleperf at the point where the situation is detected. - -1. Disable selinux by `adb shell setenforce 0`. Because selinux only allows simpleperf running - in shell or debuggable/profileable apps. - -2. Add below code at the point where the special situation is detected. - -```java -try { - // for capability check - Os.prctl(OsConstants.PR_CAP_AMBIENT, OsConstants.PR_CAP_AMBIENT_RAISE, - OsConstants.CAP_SYS_PTRACE, 0, 0); - // Write to /data instead of /data/local/tmp. Because /data can be written by system user. - Runtime.getRuntime().exec("/system/bin/simpleperf record -g -p " + String.valueOf(Process.myPid()) - + " -o /data/perf.data --duration 30 --log-to-android-buffer --log verbose"); -} catch (Exception e) { - Slog.e(TAG, "error while running simpleperf"); - e.printStackTrace(); -} -``` - -## Hardware PMU counter limit - -When monitoring instruction and cache related perf events (in hw/cache/raw/pmu category of list cmd), -these events are mapped to PMU counters on each cpu core. But each core only has a limited number -of PMU counters. If number of events > number of PMU counters, then the counters are multiplexed -among events, which probably isn't what we want. - -On Pixel devices, the number of PMU counters on each core is usually 7, of which 4 of them are used -by the kernel to monitor memory latency. So only 3 counters are available. It's fine to monitor up -to 3 PMU events at the same time. To monitor more than 3 events, the `--use-devfreq-counters` option -can be used to borrow from the counters used by the kernel. diff --git a/simpleperf/doc/executable_commands_reference.md b/simpleperf/doc/executable_commands_reference.md index 6e696d43..5d51a158 100644 --- a/simpleperf/doc/executable_commands_reference.md +++ b/simpleperf/doc/executable_commands_reference.md @@ -486,9 +486,6 @@ trace-offcpu is implemented using sched:sched_switch tracepoint event, which may on old kernels. But it is guaranteed to be supported on devices >= Android O MR1. We can check whether trace-offcpu is supported as below. -trace-offcpu only works with recording one of events: cpu-cycles, cpu-clock, task-clock. Using it -with other events or multiple events doesn't make much sense and makes the report confusing. - ```sh $ simpleperf list --show-features dwarf-based-call-graph diff --git a/simpleperf/doc/jit_symbols.md b/simpleperf/doc/jit_symbols.md deleted file mode 100644 index 8d0a2a93..00000000 --- a/simpleperf/doc/jit_symbols.md +++ /dev/null @@ -1,59 +0,0 @@ -# JIT symbols - -## Table of contents -- [Java JIT symbols](#java-jit-symbols) -- [Generic JIT symbols](#generic-jit-symbols) - - [Symbol map file location for application](#symbol-map-file-location-for-application) - - [Symbol map file location for standalone program](#symbol-map-file-location-for-standalone-program) - - [Symbol map file format](#symbol-map-file-format) - - [Known issues](#known-issues) - -## Java JIT symbols - -On Android >= P, simpleperf supports profiling Java code, no matter whether it is executed by -the interpreter, or JITed, or compiled into native instructions. So you don't need to do anything. - -For details on Android O and N, see -[android_application_profiling.md](./android_application_profiling.md#prepare-an-android-application). - -## Generic JIT symbols - -Simpleperf supports picking up symbols from per-pid symbol map files, somewhat similar to what -Linux kernel perftool does. Application should create those files at specific locations. - -### Symbol map file location for application - -Application should create symbol map files in its data directory. - -For example, process `123` of application `foo.bar.baz` should create -`/data/data/foo.bar.baz/perf-123.map`. - -### Symbol map file location for standalone program - -Standalone programs should create symbol map files in `/data/local/tmp`. - -For example, standalone program process `123` should create `/data/local/tmp/perf-123.map`. - -### Symbol map file format - -Symbol map file is a text file. - -Every line describes a new symbol. Line format is: -``` -<symbol-absolute-address> <symbol-size> <symbol-name> -``` - -For example: -``` -0x10000000 0x16 jit_symbol_one -0x20000000 0x332 jit_symbol_two -0x20002004 0x8 jit_symbol_three -``` - -### Known issues - -Current implementation gets confused if memory pages where JIT symbols reside are reused by mapping -a file either before or after. - -For example, if memory pages were first used by `dlopen("libfoo.so")`, then freed by `dlclose`, -then allocated for JIT symbols - simpleperf will report symbols from `libfoo.so` instead. diff --git a/simpleperf/doc/scripts_reference.md b/simpleperf/doc/scripts_reference.md index 734c56d2..28476daf 100644 --- a/simpleperf/doc/scripts_reference.md +++ b/simpleperf/doc/scripts_reference.md @@ -13,7 +13,6 @@ - [report.py](#reportpy) - [report_html.py](#reporthtmlpy) - [inferno](#inferno) - - [purgatorio](#purgatorio) - [pprof_proto_generator.py](#pprofprotogeneratorpy) - [report_sample.py](#reportsamplepy) - [simpleperf_report_lib.py](#simpleperfreportlibpy) @@ -209,10 +208,6 @@ $ ./inferno.sh -sc --record_file perf.data $ ./inferno.sh -np surfaceflinger ``` -## purgatorio - -[purgatorio](../scripts/purgatorio/README.md) is a visualization tool to show samples in time order. - ## pprof_proto_generator.py It converts a profiling data file into pprof.proto, a format used by [pprof](https://github.com/google/pprof). |