Get started with Streamline

Overview

This tutorial describes how to use Streamline to capture a profile of a debuggable application running on an unrooted Android target with a  Mali^TM GPU. 

Follow the steps in each section to set up your environment, connect to the target device and capture a profile to analyze.

Before you begin

On your host machine:

1. Download and install the Arm Mobile Studio package appropriate to your host platform (Windows, Linux, or macOS).
2. Install Python 3.5 (or higher). You will need this to run the provided gator_me.py script, which uses the gatord agent to connect Streamline to your Android target.
3. Install Android Debug Bridge (ADB). ADB is available with the Android SDK platform tools, which are installed as part of Android Studio, or you can download them separately here.
4. Edit your PATH environment variable to add the paths to the Python3 directory and the Android SDK platform tools directory. 

Configure your device

On your device:

1. Ensure Developer Mode is enabled, then enable USB Debugging using Settings > Developer options.
2. Connect the target to the host through USB. 
3. Run the adb devices command on the host to check that connection is successful. If successful, this command returns the ID of your target.
   

   adb devices
   List of devices attached
   ce12345abcdf1a1234       device

   You should also be able to run adb shell without issues.
4. Install a debuggable application:
   • For Unity applications, select the Development Build option in Unity's Build Settings when building your application.
   • If you're not using Unity, ensure your application is marked as debuggable in the Android application manifest (see more on how to do this in the Android Studio documentation).

Connect Streamline to your device

Arm provides a Python script, gator_me.py that installs a daemon, gatord, on your device. Streamline uses this daemon to connect to unrooted Android devices and collect data. Follow these steps to run the script so that Streamline can communicate with your device.

1. On your host machine, navigate to the Streamline installation directory, <install_dir>/streamline/gator/ where you will find the gator_me.py script.
2. Run the gator_me.py script with the --daemon option, to supply the path to the gatord binary that will be installed on the device. For example:

   python3 gator_me.py --daemon <install_dir>/streamline/bin/arm64/gatord

   
   There are two versions of the gatord, for 32-bit or 64-bit architectures, located in the following directories:
   • <install_dir>/streamline/bin/arm64/ for Armv8 64-bit architectures.
   • <install_dir>/streamline/bin/arm/ for 32-bit architectures.
3. The script will return a numbered list of the Android package names for the debuggable applications that are installed on your device. Enter the number of the package you want to profile.
   
   The gator_me.py 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.

   Alternatively, if you know the Android package name of the app you want to profile you can specify it when running the script, using the --package option.

   python3 gator_me.py --package com.mycompany.myapp --daemon <install_dir>/streamline/bin/arm64/gatord

4. Launch Streamline:
   
   1. On Windows, from the Start menu, navigate to the Arm Mobile Studio folder, and select the Streamline shortcut.
   2. On macOS, go to the <install_dir>/streamline folder, and double-click the Streamline.app file.
   3. On Linux, go to the <install_dir>/streamline folder, and run the Streamline file:
      

      cd <install_dir>/streamline
       ./Streamline

5. Choose the Target tab, and enter localhost:8080 in the target name field. This value is the local TCP port that is specified in the gator_me.py script:
   
   

Choose a counter template

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. Choose the most appropriate template for the GPU in your target device.

1. From the Target tab, open the Counter Configuration dialog by selecting the button.
   
   
2. Choose Add counters from a template  to see the list of available templates. 
   
   
3. Choose a counter template appropriate for the target GPU in your target device. The number of counters in the template that your target device supports is shown next to each template. For example, here, 34 of the 38 available counters in the Mali Midgard template are supported in the connected device. 
   
4. Save your changes.
5. Optionally, select the Capture & analysis options button from the Target tab, to set additional capture options, including the sample rate and the capture duration. Refer to Capture options in the Arm Streamline User Guide for more details.

Capture a profile

1. In Streamline, select the Start Capture button  to start capturing data from the target device. 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 and waits for you to start the application on the device. 
2. Start the application you want to profile. Live view shows charts for each counter that you selected. 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:
   
3. Unless you specified a capture duration, click Stop capture to end the capture . Arm 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.
4. IMPORTANT: Switch back to the terminal running the gator_me.py script and press any key to terminate it. The script kills all processes that it started and removes gatord from the target.
5. Select the Switch and manage templates button  and select the same counter configuration template that you chose to create the capture.
   

Analyze your capture

Analyze the data in Streamline's Timeline view. The charts area is populated with the hardware counter activity for the counters you selected during the capture. Below the charts area is the details panel, which provides further metrics from your capture. Both the charts and details panel are aligned on the timeline.

1. Control the granularity of the data by selecting the time unit. For example, if you choose 50ms, every color-coded unit in the details panel represents data captured during a 50ms window.
2. Hover over a chart to see the values at that point on the timeline.
   
3. Click anywhere on the timeline and drag the handles on the cross-section marker to select a range of time to investigate more closely. The information shown in the details panel when in Processes and Samples modes updates to show data for the window of time you have defined.
   
   

   Note: If you define a region of time with the Cross-section marker, then change the view to a larger time unit where the Cross-section marker border cannot sit precisely, the border is displayed as a blurred line.

4. Unlike the filter controls, moving and expanding the Cross-section marker does not affect the data in the other report views. To do this, use the calipers to set the required time region. Drag the calipers to the required time region, or right-click on the timeline and select Set Left Caliper or Set Right Caliper. When you move the calipers, the Call Paths, Functions, and Code views update to show information for the selected region. 
   

For more information about how to analyze performance with Arm Streamline, see Analyze your capture in the Arm Streamline User Guide.

Disconnect Streamline from your target

1. IMPORTANT: On the host, switch back to the terminal running the gator_me.py script and press any key to terminate the script. The script kills all processes that it started and removes gatord from the target.
2. Unplug your device from your host machine.

Next steps

• Refer to the Streamline Documentation for detailed topics.
• Learn how to trace your application with Graphics Analyzer