Vulkan: Add GPU memory report and analysis documentation

This information should be generally searchable and available.

Bug: b/173636655
Change-Id: I5f8cad0f34f96c085ceea369d320863f20373c99
Reviewed-on: https://chromium-review.googlesource.com/c/angle/angle/+/2714232
Reviewed-by: Tim Van Patten <[email protected]>
Reviewed-by: Cody Northrop <[email protected]>
Commit-Queue: Ian Elliott <[email protected]>

doc/DebuggingTips.md

@@ -38,12 +38,21 @@ apitrace trace -o mytrace ./out/Debug/hello_triangle
 qapitrace mytrace
 ```
 
-## Enabling Debug Markers
+## Enabling General Logging
 
-ANGLE can emit debug-utils markers for every GLES API command that are visible to both Android
-GPU Inspector (AGI) and RenderDoc.  This support is compiled when the following GN args are set:
+Normally, ANGLE only logs errors and warnings (e.g. to Android logcat).  General logging, or
+additional levels of "trace" messages will be logged when the following GN arg is set:
 ```
 angle_enable_trace = true
+```
+
+## Enabling Debug-Utils Markers
+
+ANGLE can emit debug-utils markers for every GLES API command that are visible to both Android GPU
+Inspector (AGI) and RenderDoc.  This support requires
+[enabling general logging](#enabling-general-logging) as well as setting the following additional
+GN arg:
+```
 angle_enable_annotator_run_time_checks = true
 ```
 In addition, if the following GN arg is set, the API calls will output to Android's logcat:

doc/GPUMemoryAnalysis.md

@@ -0,0 +1,82 @@
+# GPU Memory Reporting and Analysis
+
+[MemRptExt]: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_device_memory_report.html
+[enabling-general-logging]: DebuggingTips.md#enabling-general-logging
+
+GPU memory usage data can be reported when using the Vulkan back-end with drivers that support the
+[VK_EXT_device_memory_report][MemRptExt] extension.  When enabled, ANGLE will produce log messages
+based on every allocation, free, import, unimport, and failed allocation of GPU memory.  This
+functionality requires [enabling general logging](#enabling-general-logging) as well as enabling
+one or two feature flags.
+
+## GPU Memory Reporting
+
+ANGLE registers a callback function with the Vulkan driver for the
+[VK_EXT_device_memory_report][MemRptExt] extension.  The Vulkan driver calls this callback for
+each of the following GPU memory events:
+
+- Allocation of GPU memory by ANGLE
+- Free of GPU memory by ANGLE
+- Import of GPU memory provided by another process (e.g. Android SurfaceFlinger)
+- Unimport of GPU memory provided by another process
+- Failed allocation
+
+The callback provides additional information about each event such as the size, the VkObjectType,
+and the address (see the extension documentation for more details).  ANGLE caches this information,
+and logs messages based on this information.  ANGLE keeps track of how much of each type of memory
+is allocated and imported.  For example, if a GLES command causes ANGLE five 4 KB descriptor set
+(VK_OBJECT_TYPE_DESCRIPTOR_SET) allocations, ANGLE will add 20 KB to the total of allocated
+descriptor set memory.
+
+ANGLE supports two types of memory reporting, both of which are enabled
+via feature flags:
+
+* `logMemoryReportStats` provides summary statistics at each eglSwapBuffers() command
+* `logMemoryReportCallbacks` provides per-callback information at the time of the callback
+
+Both feature flags can be enabled at the same time.  A simple way to enable either or both of these
+feature flags on Android is with with the following command:
+```
+adb shell setprop debug.angle.feature_overrides_enabled <feature>[:<feature>]
+```
+where `<feature>` is either `logMemoryReportStats` or `logMemoryReportCallbacks`.  Both can be
+enabled by putting a colon between them, such as the following:
+```
+adb shell setprop debug.angle.feature_overrides_enabled logMemoryReportCallbacks:logMemoryReportStats
+```
+
+Another way to enable either or both of these feature flags is by editing the `RendererVk.cpp` file,
+and changing `false` in the following lines to `true`:
+```
+    ANGLE_FEATURE_CONDITION(&mFeatures, logMemoryReportCallbacks, false);
+    ANGLE_FEATURE_CONDITION(&mFeatures, logMemoryReportStats, false);
+```
+
+Note: At this time, GPU memory reporting has only been tested and used on Android, where the logged
+information can be viewed with the `adb logcat` command.
+
+## GPU Memory Analysis
+
+GPU memory reporting can be combined with other forms of debugging in order to do analysis.  For
+example, for a GLES application/test that properly shuts down, the total size of each type of
+allocated and imported memory should be zero bytes at the end of the application/test.  If not, a
+memory leak exists, and the log can be used to determine where the leak occurs.
+
+If an application seems to be using too much GPU memory, enabling memory reporting can reveal which
+type of memory is being excessively used.
+
+Complex forms of analysis can be done by enabling logging of every GLES and EGL API command.  This
+can be enabled at compilation time by [enabling general logging](#enabling-general-logging) as well
+as setting the following GN arg:
+```
+angle_enable_trace_android_logcat = true
+```
+
+Combining that with enabling the `logMemoryReportCallbacks` feature flag will allow each memory
+allocation and import to be correlated with the GLES/EGL commands that caused it.  If more context
+is needed for the type of drawing and/or setup that is being done in a sea of GLES commands, this
+can also be combined with the use of a graphics debugger such as Android GPU Inspector (AGI) or
+RenderDoc.  The debugger can help you understand what the application is doing at the time of the
+particular GPU memory event is occuring.  For example, you might determine that the application is
+doing something to cause a memory leak; or you may get insight into what the game is doing that
+contributes to ANGLE using excessive amounts of GPU memory.