Client framebuffer management

Starting with Android 13, new framebuffers, used during client composition, are allocated whenever the display resolution changes. This allocation is performed by SurfaceFlinger on the next invalidate cycle after a resolution change.

Framebuffer management during resolution switches

Resolution changes occur due to one of the following two scenarios:

  • A hotplug event, initiated by Hardware Composer (HWC), which occurs when swapping from one external display to a different external display that has a different default resolution.

    During a hotplug event, the handles to the old framebuffers are released when the old display data is deallocated.

  • A display mode switch initiated by SurfaceFlinger, which occurs when the user changes the resolution with user settings, or an app changes the resolution with preferredDisplayModeId.

    During a display mode switch, the handles to existing client framebuffers are released by SurfaceFlinger before calling setActiveConfig or setActiveConfigWithConstraints.

To avoid catastrophic problems, such as memory fragmentation, on devices that don't reserve enough memory for the old and new framebuffers, it's critical that HWC ceases to use the old framebuffers and releases any handles to these framebuffers as shown in the following cases:

Releasing the handles allows the framebuffer memory to be fully deallocated prior to the allocation of new framebuffers that SurfaceFlinger performs during the next invalidate cycle.

Recommendations for framebuffer management

If HWC doesn't release handles to old framebuffers in time, the new framebuffer allocation takes place before the old framebuffer deallocation. This can cause catastrophic problems when the new allocation fails due to fragmentation or other issues. Even worse, if HWC doesn't release these handles at all, a memory leak can occur.

To avoid catastrophic allocation failures, follow these recommendations:

  • If HWC needs to continue using the old client framebuffers until the new client framebuffers are provided, then it’s critical to reserve enough memory for both the old and new framebuffers, and possibly run defragmentation algorithms on the framebuffer memory space.

  • Allocate a dedicated memory pool for the framebuffers that's separate from the rest of the graphic buffer memory. This is important because between deallocation and reallocation of the framebuffers, a third-party process can attempt to allocate graphics memory. If the same graphics memory pool is used by the framebuffer and if the graphics memory is full, the third-party process can occupy the graphics memory previously allocated by a framebuffer, thus leaving insufficient memory for the framebuffer reallocation or, possibly fragmenting the memory space.

Test framebuffer management

OEMs are advised to test for proper client framebuffer memory management across resolution switches for their device, described as follows:

  • For hotplug events, simply unplug and reconnect two different displays with different resolutions.

  • For mode switches, use the ModeSwitchingTestActivity CTS Verifier test to initiate a mode switch for testing framebuffer memory behavior. This test can visually identify problems that are hard to detect programmatically.