diff --git a/content/install-guides/ams.md b/content/install-guides/ams.md index 1914033ce6..aee5d6ef8d 100644 --- a/content/install-guides/ams.md +++ b/content/install-guides/ams.md @@ -12,6 +12,7 @@ additional_search_terms: - mali - immortalis - cortex-a +- Install Arm Mobile Studio ### Estimated completion time in minutes (please use integer multiple of 5) @@ -32,41 +33,117 @@ test_maintenance: true test_images: - ubuntu:latest --- -[Arm Performance Studio](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio%20for%20Mobile) (formally known as `Arm Mobile Studio`) is a performance analysis tool suite for various application developers: - -* Android application developers -* Linux application developers in Embedded and Cloud segments +[Arm Performance Studio](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio) is a performance analysis tool suite for Android and Linux application developers It comprises of a suite of easy-to-use tools that show you how well your game or app performs on production devices, so that you can identify problems that might cause slow performance, overheat the device, or drain the battery. -[Frame Advisor](https://developer.arm.com/Tools%20and%20Software/Frame%20Advisor) is available in `2023.5` and later. - -[RenderDoc for Arm GPUs](https://community.arm.com/arm-community-blogs/b/graphics-gaming-and-vr-blog/posts/beyond-mobile-arm-mobile-studio-is-now-arm-performance-studio) is available in `2024.0` and later. +| Component | Functionality | +|----------|-------------| +| [Streamline](https://developer.arm.com/Tools%20and%20Software/Streamline%20Performance%20Analyzer) | Capture a performance profile that shows all the performance counter activity from the device. | +| [Performance Advisor](https://developer.arm.com/Tools%20and%20Software/Performance%20Advisor) | Generate an easy-to-read performance summary from an annotated Streamline capture, and get actionable advice about where you should optimize. | +| [Frame Advisor](https://developer.arm.com/Tools%20and%20Software/Frame%20Advisor) | Capture the API calls and rendering from a problem frame and get comprehensive geometry metrics to discover what might be slowing down your application. | +| [Mali Offline Compiler](https://developer.arm.com/Tools%20and%20Software/Mali%20Offline%20Compiler) | Analyze how efficiently your shader programs perform on a range of Mali GPUs. | +| [RenderDoc for Arm GPUs](https://developer.arm.com/Tools%20and%20Software/RenderDoc%20for%20Arm%20GPUs) | The industry-standard tool for debugging Vulkan graphics applications, including early support for Arm GPU extensions and Android features. | -[Graphics Analyzer](https://developer.arm.com/Tools%20and%20Software/Graphics%20Analyzer) is no longer provided. The final release was provided in the `2024.2` release. -All features of Arm Performance Studio are available free of charge without any additional license as of the `2022.4` release. +All features of Arm Performance Studio are available free of charge without any additional license. ## How do I install Arm Performance Studio? Arm Performance Studio is supported on Windows, Linux, and macOS hosts. Download the appropriate installer from [Arm Performance Studio Downloads](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio#Downloads). -Full installation and application launch instructions are given in the Arm Performance Studio [Release Notes](https://developer.arm.com/documentation/107649). +Full details about the supported OS and Android versions are given in the Arm Performance Studio [Release Notes](https://developer.arm.com/documentation/107649). ### How do I install Arm Performance Studio on Windows? -Run the supplied `Arm_Performance_Studio__windows_x86-64.exe` installer, and follow on-screen instructions. +Run the supplied `Arm_Performance_Studio__windows_x86-64.exe` installer, and follow the on-screen instructions. + +To open Streamline, Frame Advisor or RenderDoc for Arm GPUs, go to the Windows Start menu and search for the name of the tool you want to open. + +Performance Advisor is a feature of the Streamline command-line application. To generate a performance report, you must first run the provided Python script to enable Streamline to collect frame data from the device. This process is described in detail in the [Get started with Performance Advisor tutorial](https://developer.arm.com/documentation/102478/latest). After you have captured a profile with Streamline, run the `Streamline-cli -pa` command on the Streamline capture file. This command is added to your `PATH` environment variable during installation, so it can be used from anywhere. + + ```console + Streamline-cli.exe -pa my_capture.apc + ``` + +To run Mali Offline Compiler, open a command terminal, navigate to your work directory, and run the `malioc` command on a shader program. The malioc command is added to your `PATH` environment variable during installation, so can be used from anywhere + + ```console + malioc.exe my_shader.frag + ``` + +### macOS + +Arm Performance Studio is provided as a `.dmg` package. To mount it, double-click the `.dmg` package and follow the instructions. The Arm Performance Studio directory tree is copied to the Applications directory on your local file system for easy access. + +Arm recommends that you set the permissions for the installation directory to prevent other users from writing to it. This is typically achieved with the `chmod` command. For example, + +``` +chmod go-w +``` + +Open Streamline, Frame Advisor or RenderDoc for Arm GPUs directly from the Arm Performance Studio directory in your Applications directory. For example, to open Streamline, go to the `/streamline directory` and open the `Streamline.app` file. + +To run Performance Advisor, go to the `/streamline` directory, and double-click the `Streamline-cli-launcher` file. Your computer will ask you to allow Streamline to control the Terminal application. Allow this. The Performance Advisor launcher opens the Terminal application and updates your `PATH` environment variable so you can run Performance Advisor from any directory. + +Performance Advisor is a feature of the Streamline command-line application. To generate a performance report, you must first run the provided Python script to enable Streamline to collect frame data from the device. This process is described in detail in the [Get started with Performance Advisor tutorial](https://developer.arm.com/documentation/102478/latest) tutorial. After you have captured a profile with Streamline, run the `Streamline-cli -pa` command on the Streamline capture file to generate a performance report: + +``` +Streamline-cli -pa my_capture.apc +``` + +To run Mali Offline Compiler, go to the `/mali_offline_compiler` directory, and double-click the `mali_offline_compiler_launcher` file. The Mali Offline Compiler launcher opens the Terminal application and updates your `PATH` environment variable so you can run the `malioc` command from any directory. To generate a shader analysis report, run the `malioc` command on a shader program: + +``` +malioc my_shader.frag +``` + +On some versions of macOS, you might see a message that Mali Offline Compiler is not recognized as an application from an identified developer. To enable Mali Offline Compiler, cancel this message, then open **System Preferences > Security and Privacy** and select **Allow Anyway** for the `malioc` application. ### How do I install Arm Performance Studio on Linux? -Unpack the supplied `Arm Performance Studio` bundle to the desired location. For example: -```console -tar -xf Arm_Performance_Studio_2024.3_linux_x86-64.tgz +Arm Performance Studio is provided as a gzipped tar archive. Extract this tar archive to your preferred location, using a recent version (1.13 or later) of GNU tar: + +``` +tar xvzf Arm_Performance_Studio_2025.1_linux.tgz +``` + +Arm recommends that you set the permissions for the installation directory to prevent other users from writing to it. This is typically achieved with the `chmod` command. For example: + ``` +chmod go-w +``` + +You might find it useful to edit your `PATH` environment variable to add the paths to the `Streamline-cli` and `malioc` executables so that you can run them from any directory. Add the following commands to the .bashrc file in your home directory, so that they are set whenever you initialize a shell session: + +``` +PATH=$PATH://streamline +PATH=$PATH://mali_offline_compiler +``` + ### How do I install Arm Performance Studio on macOS? -Run the supplied `Arm_Performance_Studio__macos_x86-64.dmg` installer, and follow on-screen instructions. +To open Streamline, Frame Advisor or RenderDoc for Arm GPUs, go to the installation directory, open the folder for the tool you want to open and run the application file. For example: + +``` +cd /streamline +./Streamline +``` + +Performance Advisor is a feature of the Streamline command-line application. To use it to generate a performance report, you must first run the provided Python script to enable Streamline to collect frame data from the device. This process is described in detail in the Get started with Performance Advisor tutorial. After you have captured a profile with Streamline, go to the `installation_directory>/streamline` directory and run the `Streamline-cli -pa` command on the Streamline capture file to generate a performance report: + +``` +cd /performance_advisor +./Streamline-cli -pa my_capture.apc +``` + +To run Mali Offline Compiler, go to the `installation_directory>/mali_offline_compiler` directory and run the `malioc` command on a shader program: + +``` +cd /mali_offline_compiler +./malioc my_shader.frag +``` ## How do I get started with Arm Performance Studio? -See the [Get started with Arm Performance Studio for Mobile](/learning-paths/mobile-graphics-and-gaming/ams/) learning path for a collection of tutorials for each component of Performance Studio. +See the [Get started with Arm Performance Studio](/learning-paths/mobile-graphics-and-gaming/ams/) learning path for an overview of how to run each tool in Arm Performance Studio. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/_index.md b/content/learning-paths/mobile-graphics-and-gaming/ams/_index.md index 2dedfb83f8..f1986dd510 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/_index.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/_index.md @@ -1,5 +1,5 @@ --- -title: Get started with Arm Performance Studio for mobile +title: Get started with Arm Performance Studio description: Learn how to use each of the tools supplied with Arm Performance Studio (formerly known as Arm Mobile Studio). @@ -12,10 +12,12 @@ learning_objectives: - Get started profiling and optimizing your application. prerequisites: - - An appropriate Android device. These [devices](https://developer.arm.com/Tools%20and%20Software/Arm%20Mobile%20Studio#Supported-Devices) have been tested internally within Arm, and confirmed to work with Arm Performance Studio. - - Arm Performance Studio supports applications built with OpenGL ES versions 2.0 to 3.2, or Vulkan versions 1.0 to 1.2. For OpenGL ES applications, your device must be running Android 10 or later. For Vulkan applications, your device must be running Android 9 or later. + - An Android device. + - Arm Performance Studio supports applications built with OpenGL ES versions 2.0 to 3.2, or Vulkan versions 1.0 to 1.2. + - For OpenGL ES applications, your device must be running Android 10 or later. + - For Vulkan applications, your device must be running Android 9 or later. - A debuggable build of your application. - - Download and install Arm Performance Studio from [Product Download Hub](https://developer.arm.com/downloads/view/MOBST-PRO0). It is supported on Windows, Linux, and macOS host platforms. + - Download [Arm Performance Studio](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio#Downloads) and install it, following the [Install Guide](/install-guides/ams). It is supported on Windows, Linux, and macOS host platforms. - Download and install [Android SDK Platform tools](https://developer.android.com/studio/releases/platform-tools.html). Required for [Android Debug bridge (adb)](https://developer.android.com/studio/command-line/adb). author: Ronan Synnott @@ -44,9 +46,9 @@ further_reading: link: https://developer.arm.com/documentation/102478 type: documentation - resource: - title: Graphics Analyzer video tutorial - link: https://www.youtube.com/watch?v=6j68rtcTYRc - type: website + title: Frame Advisor video tutorial + link: https://developer.arm.com/Additional%20Resources/Video%20Tutorials/Capture%20and%20analyze%20a%20problem%20frame%20with%20Frame%20Advisor + type: video - resource: title: Get started with Mali Offline Compiler Tutorial link: https://developer.arm.com/documentation/102468 diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/ams.md b/content/learning-paths/mobile-graphics-and-gaming/ams/ams.md index 215c90f703..45e31c9d72 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/ams.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/ams.md @@ -14,8 +14,7 @@ layout: "learningpathall" | [Streamline](https://developer.arm.com/Tools%20and%20Software/Streamline%20Performance%20Analyzer) | Capture a performance profile that shows all the performance counter activity from the device. | | [Performance Advisor](https://developer.arm.com/Tools%20and%20Software/Performance%20Advisor) | Generate an easy-to-read performance summary from an annotated Streamline capture, and get actionable advice about where you should optimize. | | [Frame Advisor](https://developer.arm.com/Tools%20and%20Software/Frame%20Advisor) | Capture the API calls and rendering from a problem frame and get comprehensive geometry metrics to discover what might be slowing down your application. | -| [Graphics Analyzer](https://developer.arm.com/Tools%20and%20Software/Graphics%20Analyzer) | Analyze OpenGL ES and Vulkan API calls in your application, to identify rendering defects and investigate problem scenes. | | [Mali Offline Compiler](https://developer.arm.com/Tools%20and%20Software/Mali%20Offline%20Compiler) | Analyze how efficiently your shader programs perform on a range of Mali GPUs. | -| [RenderDoc for Arm GPUs](https://renderdoc.org) | The industry-standard tool for debugging Vulkan graphics applications, including early support for Arm GPU extensions and Android features. | +| [RenderDoc for Arm GPUs](https://developer.arm.com/Tools%20and%20Software/RenderDoc%20for%20Arm%20GPUs) | The industry-standard tool for debugging Vulkan graphics applications, including early support for Arm GPU extensions and Android features. | Arm Performance Studio is supported on Windows, Linux, and macOS hosts. See the [Install Guide](/install-guides/ams) for installation instructions. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/fa.md b/content/learning-paths/mobile-graphics-and-gaming/ams/fa.md index 021ea8d1ba..417db5f7f5 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/fa.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/fa.md @@ -7,15 +7,15 @@ weight: 8 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -[Frame Advisor](https://developer.arm.com/Tools%20and%20Software/Frame%20Advisor) is a developer tool designed to offer in-depth frame-based analysis for mobile graphics in Android applications. By capturing the API calls and rendering processes of a specific frame, you can identify potential performance bottlenecks that may be causing slowdowns in your application. +[Frame Advisor](https://developer.arm.com/Tools%20and%20Software/Frame%20Advisor) offers in-depth frame-based analysis for mobile graphics in Android applications. By capturing the API calls and rendering processes of a specific frame, you can identify potential performance bottlenecks that may be causing slowdowns in your application. ## Prerequisites -Build your application, and setup the Android device as described in the [Streamline](/learning-paths/mobile-graphics-and-gaming/ams/streamline/) instructions. +Build your application, and setup the Android device as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). ## Connect to the device -1. When Frame Advisor opens, select `New trace` to start a new trace. +1. Open Frame Advisor and select `New trace` to start a new trace. ![Frame Advisor launch screen](images/fa_launch_screen.png) diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/ga.md b/content/learning-paths/mobile-graphics-and-gaming/ams/ga.md deleted file mode 100644 index 7e6e399411..0000000000 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/ga.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -# User change -title: "Graphics Analyzer" - -weight: 9 # 1 is first, 2 is second, etc. - -# Do not modify these elements -layout: "learningpathall" ---- -Graphics Analyzer is a tool to help `OpenGL ES` and `Vulkan` developers get the best out of their applications through analysis at the API level. - -The tool allows you to observe API call arguments and return values, and interact with a running target application to investigate the effect of individual API calls. It highlights attempted misuse of the API, and gives recommendations for improvements. - -**Note:** Graphics Analyzer is no longer in active development. You can still get Graphics Analyzer as part of [Arm Performance Studio 2024.2](https://artifacts.tools.arm.com/arm-performance-studio/2024.2/), but it is no longer available in later versions of the suite. For a more lightweight tool, try [Frame Advisor](https://developer.arm.com/Tools%20and%20Software/Frame%20Advisor), which enables you to capture and analyze rendering and geometry data for a single frame. For graphics debugging, we recommend RenderDoc for Arm GPUs. Both tools are available for free as part of [Arm Performance Studio](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio). - -## Prerequisites - -Build your application, and setup your Android device as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). - -## Capture data from the device - -1. In Graphics Analyzer, select `Debug` > `Device Manager`, then select your device from the list of detected devices. - -1. Select the required APIs (OpenGL ES and/or Vulkan) for your application. -![Device Manager #center](images/ga_device_manager.png "Device Manager") - -1. Click `Start capture` to connect to the device and install Graphics Analyzer daemon on the device. - -1. Start the application on the device, and interact as desired. Graphics Analyzer will collect API calls from the device. - - * To collect `Frame Buffer` data, pause the application when you reach the frame of interest. - - * Click the `camera` icon to capture the frame buffer output. - - * You can also enable `Overdraw`, `Shader`, and/or `Fragment count` data to be captured. Click the `camera` icon to capture this data. - -1. When you have captured enough data, click `Stop tracing`. Graphics Analyzer will stop collecting data, remove the daemon(s), and process the captured data. - -## Analyze the capture - -The captured data will be processed into a report that the user can manually examine. The frames are listed in the `Trace Outline` view. A full description of the capabilities is given in the [Graphics Analyzer User Guide](https://developer.arm.com/documentation/101545/latest/The-Graphics-Analyzer-interface). - -Understanding the output of the report is key to the usefulness of Graphics Analyzer. This [video tutorial](https://developer.arm.com/Additional%20Resources/Video%20Tutorials/Arm%20Mali%20GPU%20Training%20-%20EP3-4) shows how to make use of the features of Graphics Analyzer. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_capture_controls.png b/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_capture_controls.png new file mode 100644 index 0000000000..9c6923366d Binary files /dev/null and b/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_capture_controls.png differ diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_event_browser.png b/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_event_browser.png new file mode 100644 index 0000000000..f5cfc068b1 Binary files /dev/null and b/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_event_browser.png differ diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_full_ui.png b/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_full_ui.png new file mode 100644 index 0000000000..75d51bb6aa Binary files /dev/null and b/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_full_ui.png differ diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_replay_context.png b/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_replay_context.png new file mode 100644 index 0000000000..1262dafe75 Binary files /dev/null and b/content/learning-paths/mobile-graphics-and-gaming/ams/images/rd_replay_context.png differ diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/malioc.md b/content/learning-paths/mobile-graphics-and-gaming/ams/malioc.md index fc735b08d8..760343b1b5 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/malioc.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/malioc.md @@ -9,13 +9,29 @@ layout: "learningpathall" --- Mali Offline Compiler is a command-line tool that you can use to compile all shaders and kernels from OpenGL ES and Vulkan, and generate a performance report for the GPU of interest. +In a terminal, test that Mali Offline Compiler is installed correctly, by typing: + +``` +malioc --help +``` + +The `--help` option returns usage instructions and the full list of available options for the malioc command. +Note + +{{% notice %}} +On macOS, Mali Offline Compiler might not be recognised as an application from an identified developer. To enable Mali Offline Compiler, open **System Preferences > Security & Privacy**, and select **Allow Anyway** for the `malioc` item. +{{% /notice %}} + ## Supported GPUs To see the full list of [supported GPUs](https://developer.arm.com/documentation/101863/latest/Platform-support/GPU-support) use: + ```console malioc --list ``` + To get information on [API support](https://developer.arm.com/documentation/101863/latest/Platform-support/API-support) for a given GPU, use: + ```console malioc --info --core ``` diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/pa.md b/content/learning-paths/mobile-graphics-and-gaming/ams/pa.md index 661d8aaca7..be3098a655 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/pa.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/pa.md @@ -7,7 +7,9 @@ weight: 7 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -Now that you have seen an example Performance Advisor report, you can use it with your own application. Performance Advisor runs on a Streamline capture file, so the first step is to take a capture with Streamline. Streamline must capture extra frame data from the device, which Performance Advisor needs to generate a report. To capture the extra frame data, you must first run the provided Python script, `streamline_me.py`. +Now that you have seen a [Performance Advisor example report](/learning-paths/mobile-graphics-and-gaming/ams/pa_example/), you can use it to capture data from your own application. + +Performance Advisor runs on a Streamline capture file, so the first step is to take a capture with Streamline. Streamline must capture extra frame data from the device, which Performance Advisor needs to generate a report. To capture the extra frame data, you must first run the provided Python script, `streamline_me.py`. This script does the following: @@ -17,11 +19,10 @@ This script does the following: ## Before you begin -Performance Advisor uses a Python script to connect to your device. You will need `Python 3.6` or later installed on your host machine. +Performance Advisor uses a Python script to connect to your device. You will need `Python 3.8` or later installed on your host machine. Build your application, and setup the Android device as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). - ## Connect to the device 1. Open a terminal or command prompt, navigate to the `Arm Performance Studio` install directory and locate the `streamline_me.py` script: @@ -31,16 +32,17 @@ Build your application, and setup the Android device as described in [Setup task ``` 1. Run the script, enabling frame boundaries, with: + ```console python3 streamline_me.py --lwi-mode=counters ``` - To capture the Vulkan API, you also need to include the `--lwi-api=vulkan` option. {{% notice Tip %}} To see all available options, use `python3 streamline_me.py --help` {{% /notice %}} 1. The script returns a numbered list of the Android package names for the debuggable applications that are installed on your device. Enter the number of the application you want to profile. + ```python Searching for devices: RZ8MC03VVEW / SM-A505FN found @@ -59,6 +61,7 @@ To see all available options, use `python3 streamline_me.py --help` 5) com.sample.texturedteapot 0) Exit script ``` + The script identifies the GPU in the device, installs the daemon application and layer library, then waits for you to complete the capture in Streamline. 1. Leave the terminal window open, as you need to come back to it after the capture is complete, to stop the script. When the script ends, any captured screenshots are saved to the directory you specified, and the daemon application and layer library are uninstalled from the device. Do not unplug the device until the script has ended. @@ -82,14 +85,22 @@ See the [Get started with Performance Advisor Tutorial](https://developer.arm.co 1. In the terminal window, navigate to the location where you stored the Streamline capture file (`.apc`). 1. Run Streamline's `streamline-cli` command with the `-pa` option on the Streamline capture file to generate the report. The default name is `report.html`. + ```console streamline-cli -pa my_capture.apc ``` + The available options are documented in the [Performance Advisor User Guide](https://developer.arm.com/documentation/102009/latest/Command-line-options/The-pa-command), else can be seen with: + ```console streamline-cli -pa -h ``` - They can also be passed within an [options file](https://developer.arm.com/documentation/102009/latest/Command-line-options/The-pa-command/pa-command-line-options-file). + + To pass a list of options in a separate file to `Streamline-cli -pa`, use: + + ``` + Streamline-cli -pa "@" + ``` ## Generate a JSON performance report diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/renderdoc.md b/content/learning-paths/mobile-graphics-and-gaming/ams/renderdoc.md new file mode 100644 index 0000000000..f5e529c70b --- /dev/null +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/renderdoc.md @@ -0,0 +1,52 @@ +--- +# User change +title: "RenderDoc for Arm GPUs" + +weight: 9 # 1 is first, 2 is second, etc. + +# Do not modify these elements +layout: "learningpathall" +--- +[RenderDoc for Arm GPUs](https://developer.arm.com/Tools%20and%20Software/RenderDoc%20for%20Arm%20GPUs) is an Arm fork of the [RenderDoc](https://renderdoc.org/) open-source debugger. The Arm release includes support for API features and extensions that are available on the latest Arm GPUs, but not yet supported in upstream RenderDoc. Arm intends to contribute changes to the upstream project, but some Arm-specific or Android-specific features may only be available in the Arm fork. + +## Prerequisites + +Build your application, and setup the Android device as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). + +## Connect to the device + +1. Open RenderDoc for Arm GPUs and select your connected device from the **Replay Context** dropdown list at the bottom left of the RenderDoc UI. + + ![Replay Context dropdown location in RenderDoc](images/rd_replay_context.png) + + The RenderDoc APK starts running on your target. + + If you don't see your device, check that your device is setup correctly as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). + +1. Navigate to the **Launch Application** tab, and set the Executable Path to the application that you want to debug. Click the **Browse** button to view all of the installed application packages on the target and find the `.exe` file. + +1. Click **Launch**, to start the application running on your target. After a successful launch, a new target-specific tab opens in the UI where you can select the frames that you want to capture. + + ![Capture frame controls in RenderDoc](images/rd_capture_controls.png) + + As your application runs, you can choose to: + + * Capture one or more frames immediately + * Capture one or more frames after a delay + * Capture one or more frames after a specific frame + + Use these controls to take captures of your application as it runs on the target device. Captured frames are stored temporarily on the device. + +1. When you have finished capturing the frames of interest, stop the application that you are debugging. Keep RenderDoc running though, as this is needed so that you can analyze and debug your captures. + +1. Select a capture from the **Captures collected** window and click **Open**. When the frame has loaded, it is displayed on the target and in the **Texture Viewer** tab, and the **Event Browser** is populated. + + ![A captured frame loaded into RenderDoc](images/rd_full_ui.png) + + By default, the **Event Browser** shows all `action()` events, which include draws, copies, and clears. Enter a search term in the **Filter** dropdown to filter these events. + + ![Event Browser in RenderDoc](images/rd_event_browser.png) + + Selected events are highlighted with a green flag. All the other windows in the UI update to display information that is specific to the selected event. You can use this to view the render state and data resources that are used by the current event, and view the GPU output that resulted from it. + +See the [RenderDoc documentation](https://renderdoc.org/docs/index.html#) to explore the full list of features. \ No newline at end of file diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks.md b/content/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks.md index 5ea0ca31af..f2d4540540 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks.md @@ -9,15 +9,33 @@ layout: "learningpathall" --- ## Installation -1. Download Arm Performance Studio and follow the installation instructions in the [Release Note](https://developer.arm.com/documentation/107649/latest/). +1. [Download Arm Performance Studio](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio#Downloads) and follow the installation instructions in the [Install Guide](/install-guides/ams). Details about changes since the last release can be found in the [Release Note](https://developer.arm.com/documentation/107649/latest/). 1. Ensure you have installed [Android Debug Bridge (adb)](https://developer.android.com/studio/command-line/adb). `adb` is available with the Android SDK platform tools, which are installed as part of Android Studio. Alternatively, you can download them separately as part of the Android SDK platform tools. -1. Performance Advisor uses a Python script to connect to your device. To run this script, you will need [Python](https://www.python.org/downloads/) 3.6 or later installed. +1. Performance Advisor uses a Python script to connect to your device. To run this script, you will need [Python](https://www.python.org/downloads/) 3.8 or later installed. + +## Update your PATH environment variable (Linux and macOS) + +Edit your `PATH` environment variable to add the paths to the Streamline and Mali Offline Compiler executables. This is so that you can run Streamline's `Streamline-cli -pa` command and Mali Offline Compiler's `malioc` command from any directory. This step is not necessary on Windows, as this is done automatically when Arm Performance Studio is installed. + +On macOS, edit your `/etc/paths` file to add the following paths: + +``` +//streamline +//mali_offline_compiler +``` + +On Linux, edit your `PATH` environment variable to add the paths to the Performance Advisor executable. Add this command to the `.bashrc` file in your home directory, so that this environment variable is set whenever you initialize a shell session. + + ``` + PATH=$PATH://streamline + PATH=$PATH://mali_offline_compiler +``` ## Build your application The application must be compiled with debug enabled, as well as additional options to facilitate call stack unwinding by Streamline. -* To set [Unity](https://unity.com/) applications to be debuggable, enable [Development Build](https://docs.unity3d.com/2021.1/Documentation/Manual/android-BuildProcess.html) in `Build settings`. +* To set [Unity](https://unity.com/) applications to be debuggable, enable [Development Build](https://docs.unity3d.com/6000.0/Documentation/Manual/android-BuildProcess.html) in `Build settings`. * In Android Studio, use a build variant that includes `debuggable true` (`isDebuggable = true` in Kotlin scripts) in the build configuration. * In Unreal Engine, open `Project Settings > Project > Packaging > Project`, and ensure that the `For Distribution` checkbox is not set. * For C++ or Java applications, refer to the [Target setup guide for Android](https://developer.arm.com/documentation/101813/latest/Target-Setup/Compile-your-application) for instructions on how to compile your application with the right options. @@ -32,10 +50,13 @@ To assist with readability and add context, you can optionally include [annotati 1. Enable `USB Debugging` under `Settings > Developer options`. If your device asks you to authorize connection to your computer, confirm the connection. 1. Connect the device to the host through USB and approve the debug connection on the device when prompted. 1. To test the connection, run the `adb devices` command in a command terminal. If successful, this returns the ID of your device: + ```command adb devices List of devices attached ce12345abcdf1a1234 device ``` + If you see that the device is listed as `unauthorized`, try disabling and re-enabling `USB Debugging` on the device, and accept the authorization prompt to enable connection to the computer. + 1. Install the [debuggable](https://developer.android.com/studio/debug) application on the device. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/streamline.md b/content/learning-paths/mobile-graphics-and-gaming/ams/streamline.md index 871874223c..d11ebab333 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/streamline.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/streamline.md @@ -22,7 +22,6 @@ Now that you have seen an [Arm Streamline example capture](/learning-paths/mobil Optionally, you can set a preferred location to store your captures using `Window` > `Preferences` > `Data Locations`. New reports will be created in the topmost folder specified. {{% /notice %}} - ## Capture data 1. Click `Start capture` to start capturing profile data from the device. Enter a name and location for the capture file. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/supporting_tools.md b/content/learning-paths/mobile-graphics-and-gaming/ams/supporting_tools.md index fb5d1a4924..adec0314da 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/supporting_tools.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/supporting_tools.md @@ -10,8 +10,16 @@ layout: "learningpathall" Arm provides the following projects to further assist application developers: -* [Unity Integration package](https://github.com/ARM-software/mobile-studio-integration-for-unity/). Integrate this package in to your Unity application during development and gain the ability to add more application awareness to Performance Advisor and Streamline profiling reports. This package exports key software counters from the Unity profiler to Streamline, and also exports a C# API to allow developers to export custom annotations and software counters that can be visualized in performance reports. -* [Unity System Metrics for Mali package](https://forum.unity.com/threads/introducing-system-metrics-mali-package.1126178/). Integrate this package in to your Unity application during development and visualize frame-based Arm GPU performance metrics using the Unity profiler. This allows efficient early triage of performance problems in-editor, allowing developers to switching to Streamline only when they need to investigate rendering performance issues in more detail. -* [Arm ASTC Encoder texture compressor](https://github.com/ARM-software/astc-encoder) is an advanced lossy texture compression format for the OpenGL ES and Vulkan graphics APIs. The ASTC Encoder (astcenc) compressor is the Arm best-in-class texture compressor for this format, available as an open-source project on GitHub. -* [libGPUInfo library](https://github.com/ARM-software/libGPUInfo) is a small utility library that enables applications to query the configuration of the Arm Immortalis or Arm Mali GPU present in the system. This information enables you to adjust application workload complexity to match the performance capability of the current device. -* [Hardware Counter Pipe (HWCPipe) library](https://github.com/ARM-software/HWCPipe) is a utility library that gives applications the ability to sample Mali GPU performance counters. This allows hardware performance data to be integrated data directly in to an application or custom developer tooling. \ No newline at end of file +[Unity Integration package](https://github.com/ARM-software/mobile-studio-integration-for-unity/). Integrate this package in to your Unity application during development and gain the ability to add more application awareness to Performance Advisor and Streamline profiling reports. This package exports key software counters from the Unity profiler to Streamline, and also exports a C# API to allow developers to export custom annotations and software counters that can be visualized in performance reports. + +[Unity System Metrics for Mali package](https://forum.unity.com/threads/introducing-system-metrics-mali-package.1126178/). Integrate this package in to your Unity application during development and visualize frame-based Arm GPU performance metrics using the Unity profiler. This allows efficient early triage of performance problems in-editor, allowing developers to switching to Streamline only when they need to investigate rendering performance issues in more detail. + +[Godot integration package](https://github.com/ARM-software/arm-performance-studio-integration-for-godot). This package provides an open-source Godot game engine integration for Streamline and Performance Advisor. It contains GDScript bindings for the Streamline annotation API, allowing users to export custom software counters, and event annotations. + +[Arm ASTC Encoder texture compressor](https://github.com/ARM-software/astc-encoder) is an open-source texture compressor for the Adaptive Scalable Texture Compression (ASTC) texture format. It supports all block sizes, all color profiles, as well as both 2D and volumetric 3D textures. The astcenc compressor can be built as either a standalone command-line application or a library that can be integrated into an existing asset creation pipeline. + +[libGPUInfo library](https://github.com/ARM-software/libGPUInfo) is an open-source utility that can be integrated into an application to query the configuration of the Arm GPU present in the system, including the GPU model, shader core count, shader core performance characteristics, and cache size. This information can be used to adjust the application workload at runtime to match the capabilities of the device being used. + +[libGPUCounters library](https://github.com/ARM-software/libGPUCounters) is an open-source utility that allows applications to select and sample a set of Arm GPU performance counters. This library provides access to the same counter data that can be visualized in the Streamline tool, allowing integration of Arm GPU data into custom tooling. + +[libGPULayers library](https://github.com/ARM-software/libGPULayers) is an open-source project that provides tooling to quickly create new Vulkan layers for Android, as well as some off-the-shelf layers that can be used during development. diff --git a/content/learning-paths/smartphones-and-mobile/ams/images/rd_capture_controls.png b/content/learning-paths/smartphones-and-mobile/ams/images/rd_capture_controls.png new file mode 100644 index 0000000000..9c6923366d Binary files /dev/null and b/content/learning-paths/smartphones-and-mobile/ams/images/rd_capture_controls.png differ diff --git a/content/learning-paths/smartphones-and-mobile/ams/images/rd_replay_context.png b/content/learning-paths/smartphones-and-mobile/ams/images/rd_replay_context.png new file mode 100644 index 0000000000..1262dafe75 Binary files /dev/null and b/content/learning-paths/smartphones-and-mobile/ams/images/rd_replay_context.png differ diff --git a/content/learning-paths/smartphones-and-mobile/ams/renderdoc.md b/content/learning-paths/smartphones-and-mobile/ams/renderdoc.md new file mode 100644 index 0000000000..7f2524b639 --- /dev/null +++ b/content/learning-paths/smartphones-and-mobile/ams/renderdoc.md @@ -0,0 +1,64 @@ +--- +# User change +title: "RenderDoc for Arm GPUs" + +weight: 9 # 1 is first, 2 is second, etc. + +# Do not modify these elements +layout: "learningpathall" +--- +RenderDoc for Arm GPUs is an Arm fork of the RenderDoc open-source graphics API debugger. The Arm release includes support for API features and extensions that are available on the latest Arm GPUs, but are not yet supported in upstream RenderDoc. + +The primary purpose of RenderDoc is to help you diagnose rendering problems that occur in your application. When you have captured a frame you can use the tool to interactively explore all of its API calls and rendering events. By stepping through the frame you can identify the problematic rendering events, and then review the configuration used by the event to root cause the problem. + +## Prerequisites + +Build a debuggable version of your application, and setup your Android device as described in [Setup tasks](/learning-paths/smartphones-and-mobile/ams/setup_tasks/). + +## Capture data from the device + +1. Connect your Android device to your host machine using USB. +1. Select your connected Android device from the **Replay Context** dropdown list at the bottom left of the RenderDoc UI. + + ![Replay Context dropdown location in RenderDoc](images/rd_replay_context.png "Replay Context dropdown location in RenderDoc") + + If you do not see your target listed in the dropdown list, run adb devices in a command-line utility. The utility returns the ID and prompts RenderDoc to list the target. If it does not, see the setup tasks to check you have set up the target correctly. + + {{% notice %}} + A red cross next to your target indicates that you have not run RenderDoc on this target before. When you connect for the first time, RenderDoc installs its capture and replay application on the target. Now the target is shown as connected in the dropdown list. + {{% /notice %}} + + After connecting, the RenderDoc app starts running on your target. + +1. Navigate to the Launch Application tab in RenderDoc for Arm® GPUs. Here: + 1. Set the Executable Path to the application you want to debug. Click the Browse button to view all the installed application packages on the target. Choose the required application package folder and select the activity executable within it. + 1. Optionally, you can specify the Working Directory. If you do not specify this, the capture is temporarily saved in the same location as the executable. + 1. You can also specify additional Capture Options and specify a list of frames to capture, in the Actions section. + +1. Click Launch, to start the application running on your target. After a successful launch, a new target-specific tab opens in the UI and from here you can capture your frames. You can: + 1. Capture one or more frames immediately + 1. Capture one or more frames after a delay + 1. Capture one or more frames after a specific frame + + ![Capture frame controls](images/rd_capture_controls.png "Capture frame controls in RenderDoc") + + Captured frames are stored temporarily on the target. + +1. When you have finished capturing the frames of interest, keep the application running on the target while you save the frames you want to debug. Click Save and then choose a location on your machine. Or you can click Open to view them directly without saving. When you click Save, RenderDoc disconnects from the target. + +1. To stop the mobile application running, use the Android swipe control to close the application. Keep the RenderDoc application running though, so that you can analyze and debug your captures. + +## Load a saved capture + +You can either load a frame capture for analysis directly after capture, or you can load a previously saved frame capture. + +1. Ensure that your Android target is connected to your computer, and select your target from the Replay Context dropdown list. + +1. If you have just taken a new frame capture, select the capture from the Captures collected window and click Open. Alternatively, you can load a previously saved frame capture from the File > Open Capture menu. + + When the frame has loaded, it is displayed on the target and in the Texture Viewer tab, and the Event Browser is populated in RenderDoc for Arm GPUs. + +## Analyze the capture + + +