Merge "simpleperf: add doc to show annotated source code and disassembly."

2 files changed, 42 insertions, 11 deletions

diff --git a/simpleperf/doc/README.md b/simpleperf/doc/README.md
index 271b7de9..f0cddd2a 100644
--- a/simpleperf/doc/README.md
+++ b/simpleperf/doc/README.md
@@ -20,10 +20,11 @@ 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)
     - [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)
   - [Bugs and contribution](#bugs-and-contribution)
 
 
@@ -204,6 +205,27 @@ To use app_profiler.py:
 $ python app_profiler.py -lib <unstripped_dir>
 ```
 
+### Show annotated source code and disassembly
+
+To show hot places at source code and instruction level, we need to show source code and
+disassembly with event count annotation. Simpleperf supports showing annotated source code and
+disassembly for C++ code and fully compiled Java code. Simpleperf supports two ways to do it:
+
+1. Through report_html.py:
+
+  a. Generate perf.data and pull it on host.
+  b. Generate binary_cache, containing elf files with debug information. Use -lib option to add
+     libs with debug info. Do it with
+     `binary_cache_builder.py -i perf.data -lib <dir_of_lib_with_debug_info>`.
+  c. Use report_html.py to generate report.html with annotated source code and disassembly,
+     as described [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/scripts_reference.md#report_html_py).
+
+2. Through pprof.
+
+  a. Generate perf.data and binary_cache as above.
+  b. Use pprof_proto_generator.py to generate pprof proto file. `pprof_proto_generator.py`.
+  c. Use pprof to report a function with annotated source code, as described [here](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/doc/scripts_reference.md#pprof_proto_generator_py).
+
 ## Bugs and contribution
 
 Bugs and feature requests can be submitted at http://github.com/android-ndk/ndk/issues.
diff --git a/simpleperf/doc/scripts_reference.md b/simpleperf/doc/scripts_reference.md
index 746da76a..02831cc9 100644
--- a/simpleperf/doc/scripts_reference.md
+++ b/simpleperf/doc/scripts_reference.md
@@ -2,17 +2,19 @@
 
 ## Table of Contents
 
-- [app_profiler.py](#app_profilerpy)
+- [Scripts reference](#scripts-reference)
+  - [Table of Contents](#table-of-contents)
+  - [app_profiler.py](#appprofilerpy)
     - [Profile from launch of an application](#profile-from-launch-of-an-application)
-- [run_simpleperf_without_usb_connection.py](#run_simpleperf_without_usb_connectionpy)
-- [binary_cache_builder.py](#binary_cache_builderpy)
-- [run_simpleperf_on_device.py](#run_simpleperf_on_devicepy)
-- [report.py](#reportpy)
-- [report_html.py](#report_htmlpy)
-- [inferno](#inferno)
-- [pprof_proto_generator.py](#pprof_proto_generatorpy)
-- [report_sample.py](#report_samplepy)
-- [simpleperf_report_lib.py](#simpleperf_report_libpy)
+    - [run_simpleperf_without_usb_connection.py](#runsimpleperfwithoutusbconnectionpy)
+  - [binary_cache_builder.py](#binarycachebuilderpy)
+  - [run_simpleperf_on_device.py](#runsimpleperfondevicepy)
+  - [report.py](#reportpy)
+  - [report_html.py](#reporthtmlpy)
+  - [inferno](#inferno)
+  - [pprof_proto_generator.py](#pprofprotogeneratorpy)
+  - [report_sample.py](#reportsamplepy)
+  - [simpleperf_report_lib.py](#simpleperfreportlibpy)
 
 
 ## app_profiler.py
@@ -204,7 +206,14 @@ It converts a profiling data file into pprof.proto, a format used by [pprof](htt
 ```sh
 # Convert perf.data in the current directory to pprof.proto format.
 $ python pprof_proto_generator.py
+# Show report in pdf format.
 $ pprof -pdf pprof.profile
+
+# Show report in html format. To show disassembly, add --tools option like:
+#  --tools=objdump:<ndk_path>/toolchains/llvm/prebuilt/linux-x86_64/aarch64-linux-android/bin
+# To show annotated source or disassembly, select `top` in the view menu, click a function and
+# select `source` or `disassemble` in the view menu.
+$ pprof -http=:8080 pprof.profile
 ```
 
 ## report_sample.py