simpleperf: add app_api doc.

Also add a section about profileableFromShell
released apps.

Bug: none
Test: none.
Change-Id: I60b0baf8739a76b01b303915d962d4d2af9d7349

3 files changed, 107 insertions, 16 deletions

diff --git a/simpleperf/demo/README.md b/simpleperf/demo/README.md
index 61e74224..6f9317fb 100644
--- a/simpleperf/demo/README.md
+++ b/simpleperf/demo/README.md
@@ -2,10 +2,13 @@
 
 ## Table of Contents
 
-- [Introduction](#introduction)
-- [Profiling Java application](#profiling-java-application)
-- [Profiling Java/C++ application](#profiling-javac-application)
-- [Profiling Kotlin application](#profiling-kotlin-application)
+- [Examples of using simpleperf to profile Android applications](#examples-of-using-simpleperf-to-profile-android-applications)
+  - [Table of Contents](#table-of-contents)
+  - [Introduction](#introduction)
+  - [Profile a Java application](#profile-a-java-application)
+  - [Profile a Java/C++ application](#profile-a-javac-application)
+  - [Profile a Kotlin application](#profile-a-kotlin-application)
+- [Profile via app_api](#profile-via-appapi)
 
 ## Introduction
 
@@ -19,6 +22,8 @@ meaning of each directory is as below:
     SimpleperfExamplePureJava/   -- contains an Android Studio project using only Java code.
     SimpleperfExampleWithNative/ -- contains an Android Studio project using both Java and C++ code.
     SimpleperfExampleOfKotlin/   -- contains an Android Studio project using Kotlin code.
+    CppApi/                      -- contains an Android Studio project using c++ app_api to record.
+    JavaApi/                     -- contains an Android Studio project using Java app_api to record.
 
 It can be downloaded as below:
 
@@ -131,3 +136,47 @@ $ python app_profiler.py -p com.example.simpleperf.simpleperfexampleofkotlin
 # report_html.py generates profiling result in report.html.
 $ python report_html.py --add_source_code --source_dirs ../demo --add_disassembly
 ```
+
+# Profile via app_api
+
+Android Studio project: CppApi and JavaApi
+
+steps:
+1. Build and install the application:
+
+```sh
+# Open CppApi project with Android Studio,
+# and build this project sucessfully, otherwise the `./gradlew` command below will fail.
+$ cd CppApi
+
+# On windows, use "gradlew" instead.
+$ ./gradlew clean assemble
+$ adb install -r app/build/outputs/apk/debug/app-debug.apk
+```
+
+2. Prepare recording environment.
+
+```sh
+$ cd ../../scripts/
+$ python api_profiler.py prepare
+```
+
+3. Run the CppApi app.
+
+```sh
+# launch the app via cmdline, can also launch it on device.
+# A profiling file is generated each time running the app.
+$ adb shell am start simpleperf.demo.cpp_api/.MainActivity
+```
+
+4. Collect profiling data.
+
+```sh
+$ python api_profiler.py collect -p simpleperf.demo.cpp_api
+```
+
+5. Report profiling data.
+
+```sh
+$ python report_html.py -i simpleperf_data/* --aggregate-by-thread-name
+```
diff --git a/simpleperf/doc/android_application_profiling.md b/simpleperf/doc/android_application_profiling.md
index fae33df6..259c121e 100644
--- a/simpleperf/doc/android_application_profiling.md
+++ b/simpleperf/doc/android_application_profiling.md
@@ -11,14 +11,17 @@ Profiling an Android application involves three steps:
 
 ## Table of Contents
 
-- [Prepare an Android application](#prepare-an-android-application)
-- [Record and report profiling data](#record-and-report-profiling-data)
-- [Record and report call graph](#record-and-report-call-graph)
-- [Report in html interface](#report-in-html-interface)
-- [Show flamegraph](#show-flamegraph)
-- [Record both on CPU time and off CPU time](#record-both-on-cpu-time-and-off-cpu-time)
-- [Profile from launch](#profile-from-launch)
-- [Parse profiling data manually](#parse-profiling-data-manually)
+- [Android application profiling](#android-application-profiling)
+  - [Table of Contents](#table-of-contents)
+  - [Prepare an Android application](#prepare-an-android-application)
+  - [Record and report profiling data](#record-and-report-profiling-data)
+  - [Record and report call graph](#record-and-report-call-graph)
+  - [Report in html interface](#report-in-html-interface)
+  - [Show flamegraph](#show-flamegraph)
+  - [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)
+  - [Parse profiling data manually](#parse-profiling-data-manually)
 
 
 ## Prepare an Android application
@@ -37,9 +40,21 @@ change.
 For the release build type, Android studio sets android::debuggable="false" in AndroidManifest.xml,
 disables JNI checks and optimizes C/C++ code. However, security restrictions mean that only apps
 with android::debuggable set to true can be profiled. So simpleperf can only profile a release
-build under these two circumstances:
+build under these three circumstances:
 If you are on a rooted device, you can profile any app.
 
+If you are on Android >= Q, you can add profileableFromShell flag in AndroidManifest.xml, this makes
+a released app profileable by preinstalled profiling tools. In this case, simpleperf downloaded by
+adb will invoke simpleperf preinstalled in system image to profile the app.
+
+```
+<manifest ...>
+    <application ...>
+      <profileable android:shell="true" />
+    </application>
+</manifest>
+```
+
 If you are on Android >= O, we can use [wrap.sh](https://developer.android.com/ndk/guides/wrap-script.html)
 to profile a release build:
 Step 1: Add android::debuggable="true" in AndroidManifest.xml to enable profiling.
@@ -265,6 +280,24 @@ $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative
 # 3. Start the app manually on the device.
 ```
 
+## Control recording in application code
+
+Simpleperf supports controlling recording from application code. Below is the workflow:
+
+1. Run `api_profiler.py prepare` to enable simpleperf recording on a device. The script needs to run
+   every time the device reboots.
+
+2. Link simpleperf app_api code in the application. The app needs to be debuggable or
+   profileableFromShell as described [here](#prepare-an-android-application). Then the app can
+   use the api to start/pause/resume/stop recording. To start recording, the app_api forks a child
+   process running simpleperf, and uses pipe files to send commands to the child process. After
+   recording, a profiling data file is generated.
+
+3. Run `api_profiler.py collect -p <package_name>` to collect profiling data files to host.
+
+Examples are CppApi and JavaApi in [demo](https://android.googlesource.com/platform/system/extras/+/master/simpleperf/demo).
+
+
 ## Parse profiling data manually
 
 We can also write python scripts to parse profiling data manually, by using
diff --git a/simpleperf/doc/scripts_reference.md b/simpleperf/doc/scripts_reference.md
index 02831cc9..28476daf 100644
--- a/simpleperf/doc/scripts_reference.md
+++ b/simpleperf/doc/scripts_reference.md
@@ -6,7 +6,8 @@
   - [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](#runsimpleperfwithoutusbconnectionpy)
+  - [api_profiler.py](#apiprofilerpy)
+  - [run_simpleperf_without_usb_connection.py](#runsimpleperfwithoutusbconnectionpy)
   - [binary_cache_builder.py](#binarycachebuilderpy)
   - [run_simpleperf_on_device.py](#runsimpleperfondevicepy)
   - [report.py](#reportpy)
@@ -75,10 +76,18 @@ after recording has started.
 $ python app_profiler.py -p com.example.simpleperf.simpleperfexamplewithnative -a .MainActivity
 ```
 
-### run_simpleperf_without_usb_connection.py
+## api_profiler.py
+
+api_profiler.py is used to control recording in application code. It does preparation work
+before recording, and collects profiling data files after recording.
+
+[Here](./android_application_profiling.md#control-recording-in-application-code) are the details.
+
+## run_simpleperf_without_usb_connection.py
 
 run_simpleperf_without_usb_connection.py records profiling data while the USB cable isn't
-connected. Below is an example.
+connected. Maybe api_profiler.py is more suitable, which also don't need USB cable when recording.
+Below is an example.
 
 ```sh
 $ python run_simpleperf_without_usb_connection.py start \