Merge "simpleperf: split README.md in doc directory."

9 files changed, 125 insertions, 109 deletions

diff --git a/simpleperf/README.md b/simpleperf/doc/README.md
index eb8fca67..078d56b3 100644
--- a/simpleperf/README.md
+++ b/simpleperf/doc/README.md
@@ -752,9 +752,27 @@ to other formats. Below are two examples.
 
 ### Show flamegraph
 
-    $ python report_sample.py >out.perf
-    $ stackcollapse-perf.pl out.perf >out.folded
-    $ ./flamegraph.pl out.folded >a.svg
+After collecting perf.data, you can use [inferno](./inferno.md) to show
+flamegraphs.
+On non-Windows platforms:
+
+    $ ./inferno.sh -sc --symfs binary_cache
+
+On Windows platform:
+
+    $ ./inferno.bat -sc --symfs binary_cache
+
+Remove `--symfs binary_cache` if you selected not to collect binaries when
+using `app_profiler.py`.
+
+You can also build flamegraphs based on scripts in
+https://github.com/brendangregg/FlameGraph. Please make sure you have perl
+installed.
+
+    $ git clone https://github.com/brendangregg/FlameGraph.git
+    $ python report_sample.py --symfs binary_cache >out.perf
+    $ FlameGraph/stackcollapse-perf.pl out.perf >out.folded
+    $ FlameGraph/flamegraph.pl out.folded >a.svg
 
 
 ### Visualize using pprof
@@ -814,108 +832,3 @@ which may not support profiling features like dwarf based call graph.
 4. Old Android versions are likely to be shipped with Arm32 chips. In Arm32
 mode, stack frame based call graph doesn't work well.
 ```
-
-## Inferno
-
-![logo](./scripts/inferno/inferno_small.png)
-
-### Description
-
-Inferno is a flamegraph generator for native (C/C++) Android apps. It was
-originally written to profile and improve surfaceflinger performance
-(Android compositor) but it can be used for any native Android application
-. You can see a sample report generated with Inferno
-[here](./scripts/inferno/report.html). Report are self-contained in HTML so they can be
-exchanged easily.
-
-Notice there is no concept of time in a flame graph since all callstack are
-merged together. As a result, the width of a flamegraph represents 100% of
-the number of samples and the height is related to the number of functions on
-the stack when sampling occurred.
-
-
-![flamegraph sample](./scripts/inferno/main_thread_flamegraph.png)
-
-In the flamegraph featured above you can see the main thread of SurfaceFlinger.
-It is immediatly apparent that most of the CPU time is spent processing messages
-`android::SurfaceFlinger::onMessageReceived`. The most expensive task is to ask
- the screen to be refreshed as `android::DisplayDevice::prepare` shows in orange
-. This graphic division helps to see what part of the program is costly and
-where a developer's effort to improve performances should go.
-
-### Example of bottleneck
-
-A flamegraph give you instant vision on the CPU cycles cost centers but
-it can also be used to find specific offenders. To find them, look for
-plateaus. It is easier to see an example:
-
-![flamegraph sample](./scripts/inferno/bottleneck.png)
-
-In the previous flamegraph, two
-plateaus (due to `android::BufferQueueCore::validateConsistencyLocked`)
-are immediately apparent.
-
-### How it works
-Inferno relies on simpleperf to record the callstack of a native application
-thousands of times per second. Simpleperf takes care of unwinding the stack
-either using frame pointer (recommended) or dwarf. At the end of the recording
-`simpleperf` also symbolize all IPs automatically. The record are aggregated and
-dumps dumped to a file `perf.data`. This file is pulled from the Android device
-and processed on the host by Inferno. The callstacks are merged together to
-visualize in which part of an app the CPU cycles are spent.
-
-### How to use it
-
-Open a terminal and from `simpleperf/scripts` directory type:
-```
-./inferno.sh  (on Linux/Mac)
-./inferno.bat (on Windows)
-```
-
-Inferno will collect data, process them and automatically open your web browser
-to display the HTML report.
-
-### Parameters
-
-You can select how long to sample for, the color of the node and many other
-things. Use `-h` to get a list of all supported parameters.
-
-```
-./inferno.sh -h
-```
-
-### Troubleshooting
-
-#### Messy flame graph
-A healthy flame graph features a single call site at its base
-(see `scripts/inferno/report.html`).
-If you don't see a unique call site like `_start` or `_start_thread` at the base
-from which all flames originate, something went wrong. : Stack unwinding may
-fail to reach the root callsite. These incomplete
-callstack are impossible to merge properly. By default Inferno asks
- `simpleperf` to unwind the stack via the kernel and frame pointers. Try to
- perform unwinding with dwarf `-du`, you can further tune this setting.
-
-
-#### No flames
-If you see no flames at all or a mess of 1 level flame without a common base,
-this may be because you compiled without frame pointers. Make sure there is no
-` -fomit-frame-pointer` in your build config. Alternatively, ask simpleperf to
-collect data with dward unwinding `-du`.
-
-
-
-#### High percentage of lost samples
-
-If simpleperf reports a lot of lost sample it is probably because you are
-unwinding with `dwarf`. Dwarf unwinding involves copying the stack before it is
-processed. Try to use frame pointer unwinding which can be done by the kernel
-and it much faster.
-
-The cost of frame pointer is negligible on arm64 parameter but considerable
- on arm 32-bit arch (due to register pressure). Use a 64-bit build for better
- profiling.
-
-#### run-as: package not debuggable
-If you cannot run as root, make sure the app is debuggable otherwise simpleperf
-will not be able to profile it.
\ No newline at end of file
diff --git a/simpleperf/scripts/inferno/bottleneck.png b/simpleperf/doc/bottleneck.png
index 2c0e05c0..2c0e05c0 100644
--- a/simpleperf/scripts/inferno/bottleneck.png
+++ b/simpleperf/doc/bottleneck.png
diff --git a/simpleperf/doc/inferno.md b/simpleperf/doc/inferno.md
new file mode 100644
index 00000000..2f33e8dc
--- /dev/null
+++ b/simpleperf/doc/inferno.md
@@ -0,0 +1,103 @@
+## Inferno
+
+![logo](./inferno_small.png)
+
+### Description
+
+Inferno is a flamegraph generator for native (C/C++) Android apps. It was
+originally written to profile and improve surfaceflinger performance
+(Android compositor) but it can be used for any native Android application
+. You can see a sample report generated with Inferno
+[here](./report.html). Report are self-contained in HTML so they can be
+exchanged easily.
+
+Notice there is no concept of time in a flame graph since all callstack are
+merged together. As a result, the width of a flamegraph represents 100% of
+the number of samples and the height is related to the number of functions on
+the stack when sampling occurred.
+
+
+![flamegraph sample](./main_thread_flamegraph.png)
+
+In the flamegraph featured above you can see the main thread of SurfaceFlinger.
+It is immediatly apparent that most of the CPU time is spent processing messages
+`android::SurfaceFlinger::onMessageReceived`. The most expensive task is to ask
+ the screen to be refreshed as `android::DisplayDevice::prepare` shows in orange
+. This graphic division helps to see what part of the program is costly and
+where a developer's effort to improve performances should go.
+
+### Example of bottleneck
+
+A flamegraph give you instant vision on the CPU cycles cost centers but
+it can also be used to find specific offenders. To find them, look for
+plateaus. It is easier to see an example:
+
+![flamegraph sample](./bottleneck.png)
+
+In the previous flamegraph, two
+plateaus (due to `android::BufferQueueCore::validateConsistencyLocked`)
+are immediately apparent.
+
+### How it works
+Inferno relies on simpleperf to record the callstack of a native application
+thousands of times per second. Simpleperf takes care of unwinding the stack
+either using frame pointer (recommended) or dwarf. At the end of the recording
+`simpleperf` also symbolize all IPs automatically. The record are aggregated and
+dumps dumped to a file `perf.data`. This file is pulled from the Android device
+and processed on the host by Inferno. The callstacks are merged together to
+visualize in which part of an app the CPU cycles are spent.
+
+### How to use it
+
+Open a terminal and from `simpleperf/scripts` directory type:
+```
+./inferno.sh  (on Linux/Mac)
+./inferno.bat (on Windows)
+```
+
+Inferno will collect data, process them and automatically open your web browser
+to display the HTML report.
+
+### Parameters
+
+You can select how long to sample for, the color of the node and many other
+things. Use `-h` to get a list of all supported parameters.
+
+```
+./inferno.sh -h
+```
+
+### Troubleshooting
+
+#### Messy flame graph
+A healthy flame graph features a single call site at its base (see [here](./report.html)).
+If you don't see a unique call site like `_start` or `_start_thread` at the base
+from which all flames originate, something went wrong. : Stack unwinding may
+fail to reach the root callsite. These incomplete
+callstack are impossible to merge properly. By default Inferno asks
+ `simpleperf` to unwind the stack via the kernel and frame pointers. Try to
+ perform unwinding with dwarf `-du`, you can further tune this setting.
+
+
+#### No flames
+If you see no flames at all or a mess of 1 level flame without a common base,
+this may be because you compiled without frame pointers. Make sure there is no
+` -fomit-frame-pointer` in your build config. Alternatively, ask simpleperf to
+collect data with dward unwinding `-du`.
+
+
+
+#### High percentage of lost samples
+
+If simpleperf reports a lot of lost sample it is probably because you are
+unwinding with `dwarf`. Dwarf unwinding involves copying the stack before it is
+processed. Try to use frame pointer unwinding which can be done by the kernel
+and it much faster.
+
+The cost of frame pointer is negligible on arm64 parameter but considerable
+ on arm 32-bit arch (due to register pressure). Use a 64-bit build for better
+ profiling.
+
+#### run-as: package not debuggable
+If you cannot run as root, make sure the app is debuggable otherwise simpleperf
+will not be able to profile it.
diff --git a/simpleperf/scripts/inferno/inferno.png b/simpleperf/doc/inferno.png
index 0ce44431..0ce44431 100644
--- a/simpleperf/scripts/inferno/inferno.png
+++ b/simpleperf/doc/inferno.png
diff --git a/simpleperf/scripts/inferno/inferno_small.png b/simpleperf/doc/inferno_small.png
index 213fb1a2..213fb1a2 100644
--- a/simpleperf/scripts/inferno/inferno_small.png
+++ b/simpleperf/doc/inferno_small.png
diff --git a/simpleperf/scripts/inferno/main_thread_flamegraph.png b/simpleperf/doc/main_thread_flamegraph.png
index 56959da1..56959da1 100644
--- a/simpleperf/scripts/inferno/main_thread_flamegraph.png
+++ b/simpleperf/doc/main_thread_flamegraph.png
diff --git a/simpleperf/scripts/inferno/report.html b/simpleperf/doc/report.html
index 2695896c..2695896c 100644
--- a/simpleperf/scripts/inferno/report.html
+++ b/simpleperf/doc/report.html
diff --git a/simpleperf/scripts/inferno/report_bottleneck.html b/simpleperf/doc/report_bottleneck.html
index 0684a71f..0684a71f 100644
--- a/simpleperf/scripts/inferno/report_bottleneck.html
+++ b/simpleperf/doc/report_bottleneck.html
diff --git a/simpleperf/scripts/Android.mk b/simpleperf/scripts/Android.mk
index 77bbb9b9..e068bd42 100644
--- a/simpleperf/scripts/Android.mk
+++ b/simpleperf/scripts/Android.mk
@@ -16,7 +16,7 @@
 LOCAL_PATH := $(call my-dir)
 
 SIMPLEPERF_SCRIPT_LIST := $(wildcard $(LOCAL_PATH)/*.py $(LOCAL_PATH)/*.config) \
-                          $(LOCAL_PATH)/../README.md \
+                          $(LOCAL_PATH)/../doc \
                           $(LOCAL_PATH)/../demo \
                           $(LOCAL_PATH)/../testdata/perf_with_symbols.data \
                           $(LOCAL_PATH)/../testdata/perf_with_trace_offcpu.data