1# GPU Memory Reporting and Analysis 2 3[MemRptExt]: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_device_memory_report.html 4[enabling-general-logging]: DebuggingTips.md#enabling-general-logging 5 6GPU memory usage data can be reported when using the Vulkan back-end with drivers that support the 7[VK_EXT_device_memory_report][MemRptExt] extension. When enabled, ANGLE will produce log messages 8based on every allocation, free, import, unimport, and failed allocation of GPU memory. This 9functionality requires [enabling general logging](#enabling-general-logging) as well as enabling 10one or two feature flags. 11 12## GPU Memory Reporting 13 14ANGLE registers a callback function with the Vulkan driver for the 15[VK_EXT_device_memory_report][MemRptExt] extension. The Vulkan driver calls this callback for 16each of the following GPU memory events: 17 18- Allocation of GPU memory by ANGLE 19- Free of GPU memory by ANGLE 20- Import of GPU memory provided by another process (e.g. Android SurfaceFlinger) 21- Unimport of GPU memory provided by another process 22- Failed allocation 23 24The callback provides additional information about each event such as the size, the VkObjectType, 25and the address (see the extension documentation for more details). ANGLE caches this information, 26and logs messages based on this information. ANGLE keeps track of how much of each type of memory 27is allocated and imported. For example, if a GLES command causes ANGLE five 4 KB descriptor set 28(VK_OBJECT_TYPE_DESCRIPTOR_SET) allocations, ANGLE will add 20 KB to the total of allocated 29descriptor set memory. 30 31ANGLE supports two types of memory reporting, both of which are enabled 32via feature flags: 33 34* `logMemoryReportStats` provides summary statistics at each eglSwapBuffers() command 35* `logMemoryReportCallbacks` provides per-callback information at the time of the callback 36 37Both feature flags can be enabled at the same time. A simple way to enable either or both of these 38feature flags on Android is with with the following command: 39``` 40adb shell setprop debug.angle.feature_overrides_enabled <feature>[:<feature>] 41``` 42where `<feature>` is either `logMemoryReportStats` or `logMemoryReportCallbacks`. Both can be 43enabled by putting a colon between them, such as the following: 44``` 45adb shell setprop debug.angle.feature_overrides_enabled logMemoryReportCallbacks:logMemoryReportStats 46``` 47 48Another way to enable either or both of these feature flags is by editing the `RendererVk.cpp` file, 49and changing `false` in the following lines to `true`: 50``` 51 ANGLE_FEATURE_CONDITION(&mFeatures, logMemoryReportCallbacks, false); 52 ANGLE_FEATURE_CONDITION(&mFeatures, logMemoryReportStats, false); 53``` 54 55Note: At this time, GPU memory reporting has only been tested and used on Android, where the logged 56information can be viewed with the `adb logcat` command. 57 58## GPU Memory Analysis 59 60GPU memory reporting can be combined with other forms of debugging in order to do analysis. For 61example, for a GLES application/test that properly shuts down, the total size of each type of 62allocated and imported memory should be zero bytes at the end of the application/test. If not, a 63memory leak exists, and the log can be used to determine where the leak occurs. 64 65If an application seems to be using too much GPU memory, enabling memory reporting can reveal which 66type of memory is being excessively used. 67 68Complex forms of analysis can be done by enabling logging of every GLES and EGL API command. This 69can be enabled at compilation time by [enabling general logging](#enabling-general-logging) as well 70as setting the following GN arg: 71``` 72angle_enable_trace_android_logcat = true 73``` 74 75Combining that with enabling the `logMemoryReportCallbacks` feature flag will allow each memory 76allocation and import to be correlated with the GLES/EGL commands that caused it. If more context 77is needed for the type of drawing and/or setup that is being done in a sea of GLES commands, this 78can also be combined with the use of a graphics debugger such as Android GPU Inspector (AGI) or 79RenderDoc. The debugger can help you understand what the application is doing at the time of the 80particular GPU memory event is occuring. For example, you might determine that the application is 81doing something to cause a memory leak; or you may get insight into what the game is doing that 82contributes to ANGLE using excessive amounts of GPU memory. 83