angle/doc/GPUMemoryAnalysis.md

GPU Memory Reporting and Analysis

GPU memory usage data can be reported when using the Vulkan back-end with drivers that support the VK_EXT_device_memory_report 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 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 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 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.