Update documentation for v1.9 release

GPUOpen-Tools · Apr 24, 2024 · f7de119 · f7de119
1 parent 05a87f8
commit f7de119
Show file tree

Hide file tree

Showing 39 changed files with 81 additions and 43 deletions.
diff --git a/.gitignore b/.gitignore
@@ -11,6 +11,6 @@ documentation/build
 documentation/source/_build
 source/frontend/util/version.h
 Buildinfo.properties
-external
 .vscode
 *.aps
+
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017-2023 Advanced Micro Devices, Inc.
+Copyright (c) 2017-2024 Advanced Micro Devices, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/RELEASE_NOTES.txt b/RELEASE_NOTES.txt
@@ -1,11 +1,15 @@
-Radeon™ Memory Visualizer V1.8 12/07/2023
+Radeon™ Memory Visualizer V1.9 04/24/2024
 -----------------------------------------
 
-V1.8 Changes
+V1.9 Changes
 ------------------------------------
-1) The Resource usage size timeline calculations take resource aliasing into account.
-2) Unbound memory sizes are included on the Resource usage size timeline.
-3) Bug/stability fixes.
+1) Improved resource list sorting.
+2) Implicit resource detection for heap resources.
+3) Conversion of heaps to resource buffers disabled if implicit heap detection is available.
+4) Improved "Filter by size" sliders shown with min and max values.
+5) Named virtual allocations.
+6) The default timeline has been changed to "Virtual memory heap" and the "Committed memory" timeline view has been removed.
+7) Bug/stability fixes.
 
 Known Issues
 ------------------------------------
@@ -25,6 +29,12 @@ Known Issues
 Release Notes History
 ------------------------------------
 
+V1.8 Changes
+------------------------------------
+1) The Resource usage size timeline calculations take resource aliasing into account.
+2) Unbound memory sizes are included on the Resource usage size timeline.
+3) Bug/stability fixes.
+
 V1.7 Changes
 ------------------------------------
 1) Aliased Resource size calculation improvements on Resource overview pane.

diff --git a/documentation/source/allocation_explorer.rst b/documentation/source/allocation_explorer.rst
@@ -30,3 +30,4 @@ The table under the allocation display shows a list of all the resources in the
 chosen allocation. These resources can be filtered using the search box text
 filter and also by size using the "**Filter by size**" slider on the right.
 Double-clicking on a resource will navigate to the **Resource details** pane.
+
diff --git a/documentation/source/allocation_overview.rst b/documentation/source/allocation_overview.rst
@@ -48,3 +48,4 @@ box. This way, allocations can be filtered by size, heap type or number of
 resources.
 
 Double-clicking on a resource will jump to the **Allocation explorer**.
+
diff --git a/documentation/source/carousel.rst b/documentation/source/carousel.rst
@@ -16,6 +16,10 @@ The **Committed memory** shows the amount of memory that this application has
 committed to physical memory for each of the heap types. Ideally, all memory
 that the application has requested should be in physical memory.
 
+Note that the amount of committed memory displayed across different tabs of RMV is calculated
+based on low-level data from the graphics driver and may not directly correspond to memory allocations/deallocations
+made using the graphics API.
+
 .. image:: media/snapshot/carousel_committed_memory.png
 
 The **Requested virtual memory** shows which memory was requested from which heap.
@@ -39,3 +43,4 @@ memory, this will be seen in the *Allocation overview* pane for each allocation.
 
 The carousel is also shown in the **Snapshot delta** pane but here it shows the
 differences between the 2 selected snapshots.
+
diff --git a/documentation/source/conf.py b/documentation/source/conf.py
@@ -46,17 +46,17 @@
 
 # General information about the project.
 project = u'Radeon Memory Visualizer'
-copyright = u'2018-2023, Advanced Micro Devices, Inc. All rights reserved'
+copyright = u'2018-2024, Advanced Micro Devices, Inc. All rights reserved'
 author = u'AMD Developer Tools'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'1.8.0'
+version = u'1.9.0'
 # The full version, including alpha/beta/rc tags.
-release = u'1.8.0'
+release = u'1.9.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/documentation/source/heap_overview.rst b/documentation/source/heap_overview.rst
@@ -35,24 +35,21 @@ mean the application gets it. If the application requests too much memory,
 a warning message is displayed. The bar is also color coded to show whether
 the memory type is oversubscribed or is close to being oversubscribed.
 
-The 'total size' bar shows the total amount of physical memory in the heap.
+The **"Total size"** bar shows the total amount of physical memory in the heap.
 
-The "Requested" bar shows how much memory the application has requested. This
+The **"Requested"** bar shows how much memory the application has requested. This
 should give an indication of the memory footprint of the application.
+Memory is requested when allocations are made e.g. by creating ``ID3D12Heap`` (D3D12)
+or ``VkDeviceMemory`` (Vulkan).
 Memory requests typically request virtual memory under the hood and it is up
 to the driver to make sure that virtual memory is mapped to physical memory
 when and where appropriate.
+An allocation may not appear in RMV until a first resource is placed in it.
 
-The "Bound" bar shows how much memory has been bound to resources. If there is
+The **"Bound"** bar shows how much memory has been bound to resources, e.g. buffers or textures (images). If there is
 substantially more requested memory than bound memory, it may indicate that
 memory has been requested but is not actually being used by the application.
 
-The "Committed" bar shows how much memory has been mapped to physical memory.
-If the amount of committed memory is substantially less than the amount of
-memory requested, it may indicate that there are other tasks running on the
-system that are consuming memory or the application itself is using more
-memory than is physically available.
-
 The middle column shows a series of statistics for the heap memory type, such
 as where the memory resides (in system or video memory), whether it is mapped
 on the CPU and some statistics on the allocations.
@@ -61,3 +58,4 @@ The right column shows the makeup of the resource types in each of the heaps.
 From this, it can be determined if certain resource types are in the optimum
 memory type for the particular resource (maybe there's a render target in system
 memory when ideally it should be in local memory).
+
diff --git a/documentation/source/index.rst b/documentation/source/index.rst
@@ -50,8 +50,8 @@ How to load a trace
 
 There are a few ways to load a trace into RMV.
 
-1) Use the “File/Open trace” pull down menu, or the “File/Recent
-   trace” pull down menu item.
+1) Use the "File/Open trace" pull down menu, or the "File/Recent
+   trace" pull down menu item.
 
   Note that RMV is also capable of loading Radeon GPU Detective (.rgd) files.
   In order to view .rgd file names in the File open dialog box, be sure to select
@@ -61,10 +61,10 @@ There are a few ways to load a trace into RMV.
 
 .. image:: media/open_file_rgd.png
 
-2) Go to the “Welcome” view and click on the “Open a Radeon Memory
-   trace…”
+2) Go to the "Welcome" view and click on the "Open a Radeon Memory
+   trace…"
 
-3) Go to the “Welcome” view and click on a trace that you have
+3) Go to the "Welcome" view and click on a trace that you have
    previously loaded in the Recent list.
 
 .. image:: media/welcome_1.png
@@ -210,13 +210,20 @@ specifically the section "Naming Objects"
 DirectX 12 resource naming
 --------------------------
 Memory traces for DirectX applications captured with the Radeon Developer Panel
-can include unique names for image-based resources.  Names can be assigned to
-DirectX resources using the ID3D12Object::SetName() method.  Calling the SetName()
+can include unique names for resources like heaps, buffers and textures.  Names can be assigned to
+DirectX resources using the ``ID3D12Object::SetName()`` method.
+For more information, please review the Microsoft DirectX 12 documentation.
+
+Calling the ``SetName()``
 method results in ETW (Event Tracing for Windows) events being emitted and picked
-up by the Panel.  This resource naming information is then included in the RMV trace
+up by the Panel. This resource naming information is then included in the RMV trace
 file.
-
-For more information, please review the Microsoft DirectX 12 documentation.
+Due to the asynchronous nature of the event tracing, memory events that happen a short time before the process exit
+may show up incorrectly in RMV in terms of naming, as well as
+marking and filtering out implicit heaps (created for committed resources)
+and implicit buffers (that D3D12 runtime creates automatically for every explicitly created heap).
+To overcome this problem, it is recommended to introduce a delay of few seconds
+between memory events of interest and the process exit.
 
 Viewing resource names
 ----------------------
@@ -251,4 +258,5 @@ Microsoft is a registered trademark of Microsoft Corporation in the US and other
 Windows is a registered trademark of Microsoft Corporation in the US and other jurisdictions.
 
 
-© 2018-2023 Advanced Micro Devices, Inc. All rights reserved.
+© 2018-2024 Advanced Micro Devices, Inc. All rights reserved.
+
diff --git a/documentation/source/media/compare/memory_leak_finder_1.png b/documentation/source/media/compare/memory_leak_finder_1.png
diff --git a/documentation/source/media/compare/snapshot_delta_1.png b/documentation/source/media/compare/snapshot_delta_1.png
diff --git a/documentation/source/media/rgp_interop.png b/documentation/source/media/rgp_interop.png
diff --git a/documentation/source/media/settings/themes_and_colors_1.png b/documentation/source/media/settings/themes_and_colors_1.png
diff --git a/documentation/source/media/snapshot/allocation_explorer_1.png b/documentation/source/media/snapshot/allocation_explorer_1.png
diff --git a/documentation/source/media/snapshot/allocation_explorer_2.png b/documentation/source/media/snapshot/allocation_explorer_2.png
diff --git a/documentation/source/media/snapshot/allocation_overview_1.png b/documentation/source/media/snapshot/allocation_overview_1.png
diff --git a/documentation/source/media/snapshot/allocation_overview_2.png b/documentation/source/media/snapshot/allocation_overview_2.png
diff --git a/documentation/source/media/snapshot/allocation_overview_3.png b/documentation/source/media/snapshot/allocation_overview_3.png
diff --git a/documentation/source/media/snapshot/allocation_overview_4.png b/documentation/source/media/snapshot/allocation_overview_4.png
diff --git a/documentation/source/media/snapshot/carousel_resource_types.png b/documentation/source/media/snapshot/carousel_resource_types.png
diff --git a/documentation/source/media/snapshot/heap_overview_1.png b/documentation/source/media/snapshot/heap_overview_1.png
diff --git a/documentation/source/media/snapshot/heap_overview_2.png b/documentation/source/media/snapshot/heap_overview_2.png
diff --git a/documentation/source/media/snapshot/resource_details_1.png b/documentation/source/media/snapshot/resource_details_1.png
diff --git a/documentation/source/media/snapshot/resource_list_1.png b/documentation/source/media/snapshot/resource_list_1.png
diff --git a/documentation/source/media/snapshot/resource_overview_1.png b/documentation/source/media/snapshot/resource_overview_1.png
diff --git a/documentation/source/media/snapshot/resource_overview_2.png b/documentation/source/media/snapshot/resource_overview_2.png
diff --git a/documentation/source/media/snapshot/resource_overview_3.png b/documentation/source/media/snapshot/resource_overview_3.png
diff --git a/documentation/source/media/snapshot/resource_overview_4.png b/documentation/source/media/snapshot/resource_overview_4.png
diff --git a/documentation/source/media/timeline_1.png b/documentation/source/media/timeline_1.png
diff --git a/documentation/source/media/timeline_empty.png b/documentation/source/media/timeline_empty.png
diff --git a/documentation/source/media/vk_resource_naming_1.png b/documentation/source/media/vk_resource_naming_1.png
diff --git a/documentation/source/memory_leak_finder.rst b/documentation/source/memory_leak_finder.rst
@@ -17,3 +17,4 @@ allow the snapshot to be viewed in the SNAPSHOT tab. If a resource is common to
 both snapshots, the base snapshot will be used.
 
 .. image:: media/compare/memory_leak_finder_1.png
+
diff --git a/documentation/source/resource_details.rst b/documentation/source/resource_details.rst
@@ -31,3 +31,4 @@ made resident at some point and then paged out).
 Not all events have all the parameters listed in the table. In this case, the
 entry will be marked as 'n/a' - not applicable. For example, the physical memory
 address isn't applicable for a virtual allocation event.
+
diff --git a/documentation/source/resource_list.rst b/documentation/source/resource_list.rst
@@ -32,3 +32,4 @@ Mousing over a memory size cell in the table will display a tooltip showing the
 exact number of bytes.
 
 .. image:: media/snapshot/resource_list_1.png
+
diff --git a/documentation/source/resource_overview.rst b/documentation/source/resource_overview.rst
@@ -25,9 +25,19 @@ include in the resource view according to which heap was the preferred container
 for the resource at the time the resource was created. You can do this by
 checking one or more heaps you wish to include resources from.
 
-The resource usage drop down allows selection of resources according to their
-usage type. Again, this is achieved by checking one or more resource types. For
-example, unbound resources are not shown by default but this can be changed.
+The resource usage drop down allows filtering of resources according to their
+usage type. Again, this is achieved by checking or unchecking one or more
+resource types. For example, unchecking the Buffer checkbox will hide buffer
+resources from the diagram.
+
+In addition to the resource usage types, this drop down combo box also includes
+Heap and Unbound checkboxes to show heaps or unbound memory regions on the diagram.
+The Heap checkbox selection is mutually exclusive with the resource usage type
+checkboxes. The diagram can show either heaps or resource usage types. Note that
+the size of heap blocks displayed in the Resource overview diagram are calculated
+based on the total actual size. Overlapped resources are not taken into account
+when calculating the heap block size. DX12 heaps created implicitly for committed
+resources are not shown in this mode.
 
 These combo boxes appear on several of the UI's and they are all independent
 ie changing heap types on one pane won't affect the heap types on the other
@@ -84,8 +94,8 @@ resource blocks are displayed on the Resource overview pane and size of the bloc
 relative to other resources.  When there is an overlap with one or more resources,
 the overlapped portion of the resource with the highest priority is displayed.
 The priority is based on three factors. The first being the resource usage type
-in the order of importance listed in the resource type legend (the rightmost type
-is the highest priority and the leftmost is the lowest priority).  If overlapping
+in the order of importance listed in the resource type legend (the leftmost type
+is the highest priority and the rightmost is the lowest priority).  If overlapping
 resources have the same usage type, they are then compared by size.  The smallest
 sized resource has the highest priority.  If the size of the resources is also
 the same, the value of the resource identifier is used to make the final decision.
@@ -104,3 +114,4 @@ Note that the sum of the aliased resource sizes (2 KiB, 3 Kib 1 KiB and 2 KiB)
 total 8 KiB plus the non-aliased resource size of 2 KiB adds up to match the
 reported Total allocated and bound size.
 
+
diff --git a/documentation/source/settings.rst b/documentation/source/settings.rst
@@ -30,3 +30,4 @@ cycles, milliseconds, seconds or minutes very quickly.
 .. image:: media/settings/keyboard_shortcuts_1.png
 
 All users are encouraged to adopt these keystrokes while using RMV.
+
diff --git a/documentation/source/snapshot_delta.rst b/documentation/source/snapshot_delta.rst
@@ -14,3 +14,4 @@ tab can be used to switch the snapshots.
 
 .. image:: media/compare/snapshot_delta_1.png
 
+
diff --git a/documentation/source/timeline.rst b/documentation/source/timeline.rst
@@ -31,35 +31,33 @@ Timeline graph
 --------------
 The **Timeline graph** displays a visual representation of memory related events
 contained in the trace that occurred over a period of time along the horizontal axis.
-There are four viewing modes:
+There are three viewing modes:
 
-1. Committed (the default view)
+1. Virtual memory heap
 
 2. Resource usage count
 
-3. Virtual memory heap
-
-4. Resource usage size
+3. Resource usage size
 
 The viewing mode can be changed by selecting from the combo box above the top-left
 of the timeline. Note that with previous releases of RMV, the default Timeline view was
-"Resource usage size." The default mode is now "Committed."
+"Resource usage size." The default mode is now "Virtual memory heap."
 
 A color legend below the timeline will indicate what resources are represented by the
 colors in the timeline.
 
 When the mouse is over the timeline, the tooltip help will show information
 about the memory allocated at the time corresponding to the mouse position. The
 time can be seen from the ruler above the graph. The most abundant resources
-are listed and the rest are combined in the last entry as "Other".
+are listed and the rest are combined in the last entry as "Other."
 
 Starting with release 1.8, RMV takes overlapping resources (i.e., aliased
 resources) into account when calculating usage type sizes on the timeline. When
 RMV detects multiple resources that are bound to sections of virtual memory that
 overlap, the usage size is attributed to the resource with the highest importance.
 This is reflected in the height of bars on the "Resource usage size" timeline and
 also, the values displayed on the tooltip when the mouse hovers over a point on
-the timeline graph. The priority of resource importance's matches the order of
+the timeline graph. The priority of resource importance's matches the order of 
 resource types displayed on the legend below the "Resource usage size" timeline
 graph. Resource types towards the left side of the legend have higher priority
 and those towards the right have lower priority. In past releases of RMV, the
@@ -183,3 +181,4 @@ memory trace was taken, showing such things as the name of the video card and
 the memory bandwidth.
 
 .. image:: media/device_config_1.png
+
diff --git a/samples/sample_trace.rmv b/samples/sample_trace.rmv
Original file line number	Diff line number	Diff line change
Expand Up		@@ -30,3 +30,4 @@ The table under the allocation display shows a list of all the resources in the
		chosen allocation. These resources can be filtered using the search box text
		filter and also by size using the "Filter by size" slider on the right.
		Double-clicking on a resource will navigate to the Resource details pane.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -48,3 +48,4 @@ box. This way, allocations can be filtered by size, heap type or number of
		resources.

		Double-clicking on a resource will jump to the Allocation explorer.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -17,3 +17,4 @@ allow the snapshot to be viewed in the SNAPSHOT tab. If a resource is common to
		both snapshots, the base snapshot will be used.

		.. image:: media/compare/memory_leak_finder_1.png
Original file line number	Diff line number	Diff line change
Expand Up		@@ -31,3 +31,4 @@ made resident at some point and then paged out).
		Not all events have all the parameters listed in the table. In this case, the
		entry will be marked as 'n/a' - not applicable. For example, the physical memory
		address isn't applicable for a virtual allocation event.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -32,3 +32,4 @@ Mousing over a memory size cell in the table will display a tooltip showing the
		exact number of bytes.

		.. image:: media/snapshot/resource_list_1.png
Original file line number	Diff line number	Diff line change
Expand Up		@@ -30,3 +30,4 @@ cycles, milliseconds, seconds or minutes very quickly.
		.. image:: media/settings/keyboard_shortcuts_1.png

		All users are encouraged to adopt these keystrokes while using RMV.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -14,3 +14,4 @@ tab can be used to switch the snapshots.

		.. image:: media/compare/snapshot_delta_1.png