Help Manual

Installing and Running RGA

The tool is available for download on the RGA GitHub releases page.

Windows: use the .msi installer or .zip archive. For Vulkan®, the installer would also install the RGA Layer and hence is the recommended option.
Linux: use the .tgz archive.

To run the app, run the RadeonGPUAnalyzerGUI executable.

Startup dialog

The graphical user interface has been extended to support more than a single API, so you will now be prompted to select your default API of choice on startup. You can check the “Do not ask me again” check box to always launch the app in the desired mode.

Vulkan® Mode

The Home Page

At the top of the home page, you will find two tabs:

Start Tab

From the Start tab, you can create a new project or load an existing project.

Creating an RGA Vulkan® Project

The new RGA Vulkan® mode compiles Vulkan® pipelines, which are comprised of shaders and state. The shaders can come in the form of SPIR-V™ binaries or, alternatively, you can provide RGA GLSL source code, and the tool would pass the shaders through the front-end compiler (glslang) to generate the SPIR-V™ binaries for you.

To handle the state, we defined a JSON representation of the Vulkan® pipeline state:

.gpso file format for VkGraphicsPipelineCreateInfo, for Vulkan® graphics pipeline state
.cpso file format for VkComputePipelineCreateInfo, for Vulkan® compute pipeline state

You can think of those files as a “recipe” for creating the Vulkan® pipeline state in runtime. To compile your pipeline, RGA would spawn a separate process (named VulkanBackend), which would create the Vulkan® instance, configure the pipeline state according to the recipe, and create the VkShaderModule objects from your shaders.

When you create a project within the app, a default .gpso / .cpso file would be generated for you with a default state. The default state is just enough for compiling very basic shaders, however, for most practical use cases, you would have to edit the state to match your shaders (please see the “Pipeline State Editor” section for more details). In the case that the pipeline creation for your shaders fails, the compilation process would fall back to using the offline Vulkan® mode (-s vk-offline-spv). The following warning indicator is displayed in the bottom right corner of the application if this occurs.

The offline mode produces less accurate ISA disassembly and resource usage statistics, and therefore it is highly recommended to adjust the pipeline state to match your shaders so that the compilation can go through the driver and produce the best results.

In the Start tab for Vulkan® mode, you have two options:

Create a graphics pipeline
Create a compute pipeline

Graphics pipeline projects
- May contain a shader for every stage of the graphics pipeline: Vertex, Tessellation Control, Tessellation Evaluation, Geometry, and Fragment.
- A Vertex shader is required at minimum to successfully build the pipeline.
- Within the graphics pipeline project, you would be able to configure the Vulkan® graphics pipeline state in the UI
Compute pipeline projects
- May contain a single Compute shader stage.
- Within the compute pipeline project, you would be able to configure the Vulkan® compute pipeline state in the UI

You can also create a compute or graphics pipeline through the File menu by:

Clicking on File -> “Create new Vulkan® graphics pipeline” (Ctrl+Alt+G)
Clicking on File -> “Create new Vulkan® compute pipeline” (Ctrl+Alt+C)

You will then be prompted for an optional rename of your pipeline project:

RGA will use a yymmdd-hhmmss date-time string as a default name. Check the “Always use auto-generated project names” check box to instruct RGA to always use the default name without prompting for renaming.

Loading a Project

You can load an existing project (.rga file) using the Ctrl+Alt+O shortcut or by clicking on an item on the Recent menu in the home page (note that the project type can be seen in the symbol to the right of the recent project link):

It is also possible to load a project from the File -> “Open existing RGA project…” menu item:

Settings Tab

From the Settings tab, you can control the global settings:

Application Settings

The Application Settings view is used to configure global application settings that aren’t associated with a single API mode:

General
- Log file location: The folder in which RGA would generate log files. Upon startup RGA will clean up the log files that are older than 3 days.
- Project file location: The folder in which RGA would generate project files.
- Always use auto-generated project names: If checked, RGA will always use the auto-generated project name, without prompting for a rename when creating a new project.
- Default API on startup: RGA will always enter the selected API Mode upon startup.
- Color theme: “Detect OS” is the default. This will use the system’s setting for the color theme.
Disassembly View
- Disassembly view columns: The set of disassembly view columns which will be visible by default.
Source code editor
- Font & Font Size: Configure the default font style and size settings used in the shader source code editor.
- Open include files with: Select the default text editor application that’s launched when opening include files.
Input files
- Associate file extension association: Choose the set of file extensions used to associate RGA with various shader input source files.

Default Vulkan® Build Settings

General
- Target GPUs:
  These are the target architectures that the code would be built for. You can click the “…” button near this item to open RGA’s target GPUs dialog. When looking at the target devices, we need to consider 3 terms:
  
  Architecture: the name of the GPU HW architecture, such as Vega.
  
  Compute capability: the name of the architecture variant. From the compiler’s point of view, GPUs with the same compute capability are identical. Therefore, RGA treats all of the product names that share the same compute capability as a single Target GPU.
  
  Product name: this is the public name of the GPU product, such as “Radeon Instinct MI25” or “Radeon RX Vega”.
- Predefined macros:
  Preprocessor directives which can come in two forms:
  
  X, for example _WIN32 or _DEBUG
  
  X=Y, for example “RT_NUM=3”
  
  You can either enter the values manually with a “;” between each directive, or use the dedicated view (click the “…” button to show it). In case that a directive contains whitespace characters, make sure to wrap the directive with “”.
- Additional include directories:
  
  Additional paths which the compiler would use when searching for source files.
  
  You can either enter the values manually with a “;” between each path, or use the dedicated view (click the “…” button to show it). In case that a path contains whitespace characters, make sure to wrap the path with “”.
Vulkan® Options
- ICD location:
  
  Full path to a Vulkan® ICD. If given, RGA would load the given ICD explicitly instead of the Vulkan® loader. This setting is useful if you want RGA to use an older or newer AMD Vulkan® driver (amdvlk64.dll/.so) to compile your pipeline. You can just browse for the file here, and RGA would make sure to use that file instead of the system’s default.
- Enable validation layers:
  
  Enable Vulkan® validation layers. This feature is useful when the build process fails at or around the pipeline creation stage. If your compilation failed at the front-end stage (GLSL -> SPIR-V™ or SPIR-V™ text to SPIR-V™ binary), then you will probably get a meaningful error message in the build output from the front-end compiler (glslang). However, if the build failure fails deeper in the stack, there will be very limited error messages, since AMD’s shader compiler does not provide error messages. Enabling the validation layers can help shed light on the specific pipeline settings that was not configured properly or did not match your shaders.
- Additional glslang options:
  
  Additional options to be passed to glslang for Vulkan® front-end compilation (for example, “–target-env vulkan1.1 –suppress-warnings”). You can pass any options that are accepted by glslang here, and rga would pass those through to glslang when compiling your GLSL code or reassembling your SPIR-V™ binaries.
- Use alternative front-end compiler package:
  
  Path to alternative compiler’s binaries folder. The following executables are expected to be in this folder: glslangValidator, spirv-as, spirv-dis. If given, this package would be used instead of the glslang package that is bundled with RGA to compile GLSL to SPIR-V, disassemble SPIR-V™ binaries, reassemble SPIR-V™ binaries, etc.
- Name of output binary:
  
  The file name which will be used for the generated pipeline binary ELF file.
- Settings command line
  
  The command string which will be passed to the RGA backend when it is invoked. This command string is dynamically populated from the values that you set in the UI.

The Build View

After you add or create a new file, RGA will create a project for you and switch to the Build View. To learn how to create a project, please visit RGA’s Quickstart documentation.

The build view consists of 4 views: – File Menu – Source Code View – Disassembly View – Build Output View

Using the File Menu you can:

Create a template GLSL shader source file by clicking on “Create template GLSL file”.

Add an existing SPIR-V™ binary or GLSL source file to your project by clicking on “Add existing GLSL/SPIR-V file”.

Open the pipeline state editor by clicking on “Pipeline state”, or using the F9 shortcut.

Open the project-specific build settings by clicking on “Build settings”, or using the F8 shortcut. For more details about the build settings view, please see the Build Settings section.

Clicking on a shader stage file item will switch focus to that file, and display the file’s contents in the Source View and Disassembly View (if any content is available for that file). The current item is highlighted in yellow.

The user can add an existing shader file or create a new one by clicking on the “+” button in each stage.

The user can remove an existing file from a pipeline’s shader stage by hovering on the item and clicking on the remove button.

Pipeline State Editor

The pipeline state editor provides a tree representation of the Vulkan® pipeline state, allowing the user to edit a graphics or compute pipeline’s creation parameters. It is important to configure a project’s pipeline state to match the required shader inputs & outputs or the pipeline may fail to compile successfully.

The Pipeline State editor can be opened by clicking on the “Pipeline state” button within the file menu, or by using the F9 keyboard shortcut.

Several create info structures are available to be configured within this view depending on the project’s pipeline type:

Graphics pipeline
- VkGraphicsPipelineCreateInfo
- VkPipelineLayoutCreateInfo
- VkDescriptorSetLayoutCreateInfo array
- VkRenderPassCreateInfo
Compute pipeline
- VkComputePipelineCreateInfo
- VkPipelineLayoutCreateInfo
- VkDescriptorSetLayoutCreateInfo array

The pipeline state parameters can be searched using structure names or values. You can use the Ctrl+F (Edit -> Find) to open the search widget within the state tree:

If search results are found, the state tree will automatically scroll to the first occurrence. All search results are highlighted in orange, while the currently selected occurrence is highlighted with light gray.

Use the “Find Previous” and “Find Next” arrow buttons, or the F3 and Shift+F3 hotkeys, to step through all matches sequentially.

It is also possible to use the filter option while searching:

Searching with this option on will filter the state tree to display only the relevant sections:

The pipeline state can be loaded from an RGA pipeline state file. RGA stores the Vulkan® pipeline state in a JSON file:

.gpso file for graphics pipelines, with a representation of VkGraphicsPipelineCreateInfo
.cpso file for compute pipelines, with a representation of VkComputePipelineCreateInfo

These files can be serialized from your Vulkan® app in runtime using the RGA layer, a beta feature that ships with RGA. For more info about this feature, see the “Use the RGA Layer” section.

Source Code View

The Source Code View shows the source code for the currently selected item in the file menu.

On the left side of the Source Code View, you will find running line numbers.

You can use the Ctrl+F (Edit -> Find) and Ctrl+G (Edit -> Go to…) to search for a string or jump to a specific line.

After a successful build, when the disassembly view becomes visible alongside the Source Code View, you can double-click on the view’s black title bar to maximize it. You can also click on the resize icon at the top right corner to maximize/minimize the view:

Build Output View

When a build is triggered, the RGA command line app is being launched to execute the build. Its output would be streamed into the Build Output View.

Double-clicking on the top black title bar (or clicking on the resize button at its right corner) would maximize/minimize the Build Output View.

The Clear button at the top right corner will clear the text from the view.

Disassembly View

The disassembly for the selected shader stage will be displayed in the disassembly view on the right:

Memory instructions are colored in red to help you identify spots with high memory pressure
The Columns drop-down menu at the top can be used to customize the presented columns
If more than one GPU was targeted, use the drop-down on the top left corner to switch devices

The resource usage section under the disassembly table shows the GPU resources that are consumed by the ISA. The information found in the view is displayed as follows:

VGPR consumption: <used>/<available>

SGPR consumption: <used>/<available>

VGPR spills (if occurred, otherwise – not shown)

SGPR spills (if occurred, otherwise – not shown)

LDS consumption: <used>/<available>

Scratch memory usage

Instruction cache usage

In cases where performance hazards are detected due to the usage of a GPU resource, RGA will display a warning icon and highlight the relevant resources in yellow:

Resource hazards that may require the developer’s attention are defined as:

VGPR/SGPR hazard: there were register spills, or, <used> == <available>.

LDS hazard: <used> == <available> in LDS.

Scratch memory hazard: scratch memory is used.

Instruction cache hazard: code size is larger than the instruction cache.

VGPR Pressure Visualization

After successfully building your code, you will notice a new column in the disassembly view named “VGPR pressure”. This column is shown by default and can be hidden using the “Columns” dropdown. Below is a screenshot showing this column.

The column header text format is “VGPR pressure (used x; allocated: y/256)”, which provides a summary for the entire shader, where ‘x’ gives the total VGPRs used by the current shader and ‘y’ gives the total number of VGPRs allocated. Hovering over any of the column’s cells, will show a tooltip with a summary of the live VGPR at that specific instruction, with a hint about how many VGPRs need to be reduced to save a VGPR block at that instruction. Note that VGPRs are allocated in blocks, which vary in size. The VGPR block size is determined by the target GPU and, in certain cases, by specific characteristics of the shader, such as the wave size it was compiled for. The hint indicates how many VGPRs need to be freed to free up an entire block of VGPRs at that point of the shader:

Note that, when generating the hint, the tool will take into account the target GPU and the relevant shader characteristics for determining the VGPR allocation block size for you. When examining the VGPR pressure column cells, in addition to the numerical value, which gives the number of live VGPRs at that instruction, you would notice a utilization bar that visualizes the VGPR usage and the VGPR block utilization. The emptier the utilization bar is, the less of the allocated VGPR block is being utilized, which means that less VGPRs would need to be reduced to free up that block:

In the above screenshot, we have a shader with a VGPR allocation block size of 8 VGPRs. You can see that different lines have different colors in their visualization bar. The bar’s color would be greener as the live VGPR value at that instruction gets closer to 0 and redder as the value gets closer to 256. The lines where the visualization bar is full (where the VGPR usage value is a multiple of 8, like 104, 96, 88 etc.) show points in the shader where the VGPR allocation block is fully utilized. However, in lines where the bar is partially empty, not all allocated VGPRs are being used. The tooltip hint that we mentioned earlier will let you know how many VGPRs need to be reduced to free up that VGPR allocation block.

If the register pressure details of any instruction could not be generated, there will be a red hazard symbol as shown in the image below. The instructions that could not be parsed will have “N/A” in the VGPR pressure column. Hovering over the hazard symbol provides the count of instructions that could not be parsed in the form of a tooltip.

In case the number of VGPRs used hits the max on any instruction, there will be a yellow hazard symbol as shown in the image below.

As mentioned earlier, a visualization bar’s color would be greener as the live VGPR value at that instruction gets closer to 0 and redder as the value gets closer to 256. To calculate the color for each instruction’s visualization bar, we break down the 0-256 VGPR range into 8 ranges, each of which covers 32 VGPRs (0-32, 32-64 etc.). Each range is assigned a unique color starting with light green for the first range to dark red for the last range. Below is a screenshot showing various color ranges:

You can cycle through all the lines which have maximum VGPR pressure by pressing the F4 function key, or from the application’s Edit menu by selecting the “Go to next maximum VGPR pressure line” item, or by pressing the Ctrl+F4 shortcut. The lines will be highlighted as shown in the image below.

Selecting the “Go to next maximum VGPR pressure line” option in the disassembly view’s context menu also allows you to cycle through maximum live VGPR pressure lines. This option is shown in the image below.

Switching between kernels will reset the feature, and you will have to use one of the options mentioned above to see the maximum live VGPR pressure lines again. At this point the first maximum VGPR line for the current kernel will be highlighted. If the “VGPR pressure” column is currently hidden, pressing the F4 or Ctrl+F4 keys will have no effect, and the Edit menu item to show this feature will also be disabled.

Pressing the Shift+F4 key combination shows the matches in the reverse order.