Get started with Streamline

This tutorial describes how to set up and run Streamline Performance Analyzer with an unrooted Android target with a  MaliTM GPU.

Before you begin

  1. On your host machine:
    1. Download and install the Arm Mobile Studio package appropriate to your host platform (Windows, Linux, or macOS).
    2. Download the gatorme helper script from GitHub. This script makes it easy for users with unrooted Android devices to install and use gatord, the agent that Streamline uses to collect data from the Android target.
    3. Install Android Debug Bridge (ADB). ADB is available with the Android SDK platform tools (https://developer.android.com/studio/releases/platform-tools.html). 
    4. The ADB executable, adb, must be accessible to the gatorme script, so ensure that the Android SDK platform tools directory is in the PATH environment variable.
  2. On your target device:
    1. Ensure Developer Mode is enabled, then enable USB Debugging using Settings > Developer options.
    2. Connect the target to the host. If the connection is succesful, running the adb devices command on the host should return the ID of your target and you should be able to run adb shell without issues.
    3. Install the application to be analyzed.

Procedure

  1. On the host, run the gatorme script to set up the target device so that Streamline can connect to it. Use the following command-line arguments:
    • The Android package name of the application you want to profile.
    • The short name of the MaliTM GPU on the target device, excluding the Mali- prefix, for example G72.
    • The path on the host to the gatord binary to install on the device. By default, this is the current working directory. Your Mobile Studio installation provides two versions of gatord, in the following directories:
      • <install_dir>/streamline/bin/arm/ for 32-bit architectures.
      • <install_dir>/streamline/bin/arm64/ for Armv8 64-bit architectures.
    For example:
    gatorme.bat com.arm.pa.paretrace G72 gatord
    The gatorme script does the following:
    • Kills and removes gatord and removes any counter configuration file that was previously created.
    • Enables perf profiling.
    • Copies gatord to the target.
    • Runs gatord inside the Android application sandbox.
    • Configures port forwarding.
    • Waits for you to configure and perform the capture in Streamline.
    • When the capture is complete, it kills and removes gatord.
  2. Launch Streamline and connect to the target. In the target name field, enter localhost:4242. This value is the local TCP port that is specified in the gatorme script:
  3. Configure the counters to collect. Press the Counter Configuration button, then choose Add counters from a template. Select a counter template appropriate for the target GPU from the drop-down list:

    Counter templates are pre-defined sets of counters that have been chosen to enable you to perform an initial performance review of both CPU and GPU behavior. Streamline notifies you if the target device does not support all the counters defined in the selected template.
  4. Optionally, select the Capture & analysis options button to set additional capture options, including the sample rate and the capture duration (by default unlimited).
  5. Select the Start Capture button  to start the capture. Specify the name and location on the host of the capture file that Streamline will create when the capture is complete. Streamline then switches to Live view.
  6. Start the application you want to profile. Live view shows charts for each counter that you selected in step 3. Below the charts is a list of running processes in your application with their CPU usage. The charts now start updating in real time to show the data that gatord captures from your running application:
  7. Stop the capture. Unless you specified a capture duration, press the Stop capture button to end the capture . Streamline stores the capture file in the location you specified previously and then prepares the capture for analysis. When complete, the capture appears in the Timeline view.
  8. Select the template in the Timeline view for visualization. Press the Switch and manage templates button  to select the same template that you used to create the capture in Step 3.
  9. Analyze the data. The Timeline view shows more data than Live view and provides extra ways to view it.
  10. On the host, switch back to the terminal running the gatorme script and press any key to terminate the script. The script kills all processes that it started and removes gatord from the target.