Android Build Tools

Android/android-ndk-r27d/simpleperf/app_api/cpp/simpleperf.h

@@ -0,0 +1,161 @@
+/*
+ * Copyright (C) 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include <sys/types.h>
+#include <unistd.h>
+
+#include <string>
+#include <vector>
+
+// A C++ API used to control simpleperf recording.
+namespace simpleperf {
+
+/**
+ * RecordOptions sets record options used by ProfileSession. The options are
+ * converted to a string list in toRecordArgs(), which is then passed to
+ * `simpleperf record` cmd. Run `simpleperf record -h` or
+ * `run_simpleperf_on_device.py record -h` for help messages.
+ *
+ * Example:
+ *   RecordOptions options;
+ *   options.setDuration(3).recordDwarfCallGraph().setOutputFilename("perf.data");
+ *   ProfileSession session;
+ *   session.startRecording(options);
+ */
+class RecordOptionsImpl;
+class RecordOptions {
+ public:
+  RecordOptions();
+  ~RecordOptions();
+  /**
+   * Set output filename. Default is perf-<month>-<day>-<hour>-<minute>-<second>.data.
+   * The file will be generated under simpleperf_data/.
+   */
+  RecordOptions& SetOutputFilename(const std::string& filename);
+
+  /**
+   * Set event to record. Default is cpu-cycles. See `simpleperf list` for all available events.
+   */
+  RecordOptions& SetEvent(const std::string& event);
+
+  /**
+   * Set how many samples to generate each second running. Default is 4000.
+   */
+  RecordOptions& SetSampleFrequency(size_t freq);
+
+  /**
+   * Set record duration. The record stops after `durationInSecond` seconds. By default,
+   * record stops only when stopRecording() is called.
+   */
+  RecordOptions& SetDuration(double duration_in_second);
+
+  /**
+   * Record some threads in the app process. By default, record all threads in the process.
+   */
+  RecordOptions& SetSampleThreads(const std::vector<pid_t>& threads);
+
+  /**
+   * Record dwarf based call graph. It is needed to get Java callstacks.
+   */
+  RecordOptions& RecordDwarfCallGraph();
+
+  /**
+   * Record frame pointer based call graph. It is suitable to get C++ callstacks on 64bit devices.
+   */
+  RecordOptions& RecordFramePointerCallGraph();
+
+  /**
+   * Trace context switch info to show where threads spend time off cpu.
+   */
+  RecordOptions& TraceOffCpu();
+
+  /**
+   * Translate record options into arguments for `simpleperf record` cmd.
+   */
+  std::vector<std::string> ToRecordArgs() const;
+
+ private:
+  RecordOptionsImpl* impl_;
+};
+
+/**
+ * ProfileSession uses `simpleperf record` cmd to generate a recording file.
+ * It allows users to start recording with some options, pause/resume recording
+ * to only profile interested code, and stop recording.
+ *
+ * Example:
+ *   RecordOptions options;
+ *   options.setDwarfCallGraph();
+ *   ProfileSession session;
+ *   session.StartRecording(options);
+ *   sleep(1);
+ *   session.PauseRecording();
+ *   sleep(1);
+ *   session.ResumeRecording();
+ *   sleep(1);
+ *   session.StopRecording();
+ *
+ * It aborts when error happens. To read error messages of simpleperf record
+ * process, filter logcat with `simpleperf`.
+ */
+class ProfileSessionImpl;
+class ProfileSession {
+ public:
+  /**
+   * @param appDataDir the same as android.content.Context.getDataDir().
+   *                   ProfileSession stores profiling data in appDataDir/simpleperf_data/.
+   */
+  ProfileSession(const std::string& app_data_dir);
+
+  /**
+   * ProfileSession assumes appDataDir as /data/data/app_package_name.
+   */
+  ProfileSession();
+  ~ProfileSession();
+
+  /**
+   * Start recording.
+   * @param options RecordOptions
+   */
+  void StartRecording(const RecordOptions& options);
+
+  /**
+   * Start recording.
+   * @param args arguments for `simpleperf record` cmd.
+   */
+  void StartRecording(const std::vector<std::string>& record_args);
+
+  /**
+   * Pause recording. No samples are generated in paused state.
+   */
+  void PauseRecording();
+
+  /**
+   * Resume a paused session.
+   */
+  void ResumeRecording();
+
+  /**
+   * Stop recording and generate a recording file under appDataDir/simpleperf_data/.
+   */
+  void StopRecording();
+
+ private:
+  ProfileSessionImpl* impl_;
+};
+
+}  // namespace simpleperf