Additional documentation for offline unwinds.

Add documentation to to OfflineUnwindUtils.h,
OfflineUnwindBenchmarks.cpp and UnwindOfflineTest.cpp to provide
additional context such as the relevance/importance of offline unwinds
as well as how to create the snapshots used by OfflineUnwindUtils.

Bug: 192012600
Test: N/A. Only adding documentation.
Change-Id: I9e6a9cec5dd51ce6016813c14b9fd5bda4f6963b

3 files changed, 42 insertions, 6 deletions

diff --git a/libunwindstack/benchmarks/OfflineUnwindBenchmarks.cpp b/libunwindstack/benchmarks/OfflineUnwindBenchmarks.cpp
index eaf88f4..b06c5ee 100644
--- a/libunwindstack/benchmarks/OfflineUnwindBenchmarks.cpp
+++ b/libunwindstack/benchmarks/OfflineUnwindBenchmarks.cpp
@@ -27,12 +27,13 @@
 #include "Utils.h"
 #include "utils/OfflineUnwindUtils.h"
 
+// This collection of benchmarks exercises Unwinder::Unwind for offline unwinds.
+//
+// See `libunwindstack/utils/OfflineUnwindUtils.h` for more info on offline unwinds
+// and b/192012600 for additional information regarding these benchmarks.
 namespace unwindstack {
 namespace {
 
-// This collection of benchmarks exercises Unwinder::Unwind for offline unwinds. For more info
-// on offline unwinds, see `libunwindstack/utils/OfflineUnwindUtils.h`.
-
 class OfflineUnwindBenchmark : public benchmark::Fixture {
  public:
   void TearDown(benchmark::State& state) override {
diff --git a/libunwindstack/tests/UnwindOfflineTest.cpp b/libunwindstack/tests/UnwindOfflineTest.cpp
index 2221b25..2261449 100644
--- a/libunwindstack/tests/UnwindOfflineTest.cpp
+++ b/libunwindstack/tests/UnwindOfflineTest.cpp
@@ -28,6 +28,10 @@
 #include "utils/MemoryFake.h"
 #include "utils/OfflineUnwindUtils.h"
 
+// This collection of tests exercises Unwinder::Unwind for offline unwinds.
+//
+// See `libunwindstack/utils/OfflineUnwindUtils.h` for more info on offline unwinds
+// and b/192012600 for additional information regarding offline unwind benchmarks.
 namespace unwindstack {
 namespace {
 
diff --git a/libunwindstack/utils/OfflineUnwindUtils.h b/libunwindstack/utils/OfflineUnwindUtils.h
index 27da78a..d6f6a75 100644
--- a/libunwindstack/utils/OfflineUnwindUtils.h
+++ b/libunwindstack/utils/OfflineUnwindUtils.h
@@ -25,14 +25,45 @@
 
 #include "MemoryOffline.h"
 
-namespace unwindstack {
-
 // These utils facilitate performing offline unwinds. Offline unwinds are similar to local
 // unwinds, however, instead of pausing the process to gather the current execution state
 // (stack, registers, Elf / maps), a snapshot of the process is taken. This snapshot data
 // is used at a later time (when the process is no longer running) to unwind the process
 // at the point the snapshot was taken.
-
+//
+// Offline unwinds simulate one of the most common use cases of the Unwinder. These types of
+// unwinds are performed by two of the largest clients of libunwindstack: Perfetto and Simpleperf.
+//
+// Offline unwind snapshots were obtained using the following approach:
+// 1. (Optional) Flash a virtual or physical device with the internal Android build rather than
+//    an AOSP build to have additional and more complex apps to unwind.
+// 2. Determine the pid of the app/process you want to unwind. View all of the running
+//    processes with `adb shell ps -A`  or `adb shell ps -A | grep name.of.process` if you know
+//    the (package) name of the process.
+// 3. (Optional) If you want to ensure that an application is compiled or that the compiled code is
+//    erased (e.g. want interpreter / JIT frames in the unwind), run `adb shell cmd package compile`
+//    based on the options provided here
+//    (https://source.android.com/devices/tech/dalvik/jit-compiler).
+// 4. Ensure the process is running and in a "desired state" when you execute
+//    `adb shell /bin/unwind_for_offline [options] pid`. For example:
+//   a. If you are unwinding the bluetooth process and want the unwind to contain the bluetooth
+//      ELF (libbluetooth.so), try to pair with a device over bluetooth. Make sure you use the
+//      `-t` and `-e` flags.
+//   b. You will likely see more variation in the thread snapshots (especially if you are trying
+//      to capture JIT/interpreter frames) if you ensure the app is not-idle when you run
+//      `unwind_for_offline`. E.g. immediately run unwind_for_offline after searching for a
+//      landmark in Google Maps.
+// 5. Grab the desired snapshot directories with `adb pull ...`
+// 6. (Optional) Reduce the size of copied ELFs:
+//   a. Move repeated ELFs to a common folder and replace those files in the individual snapshot
+//      directories with symbolic links.
+//   b. Strip ELFs of all sections that are not needed for unwinding and/or symbolization.
+//   c. Compress/Zip the entire snapshot directory.
+// 7. Use the path to the snapshot directory(ies) for the `offline_files_dirs` parameter to
+//    `OfflineUnwindUtils::Init`.
+//
+// See b/192012600 for additional information regarding Offline Unwind Benchmarks.
+namespace unwindstack {
 std::string GetOfflineFilesDirectory();
 
 std::string DumpFrames(const Unwinder& unwinder);