GNOME Mutter Adds Debug Option To Override Multi-GPU Copy Mode

Written by Michael Larabel in GNOME on 20 February 2025 at 06:10 AM EST. Add A Comment

A new debug option was merged on Wednesday to Mutter Git ahead of the upcoming GNOME 48 release. This new debug option is to override the GPU copy mode handling for multi-GPU setups.

For those with multi-GPU systems and working to debug issues around performance or other issues particularly when driving a display with GNOME from the secondary GPU, the new "MUTTER_DEBUG_MULTI_GPU_FORCE_COPY_MODE" environment variable override may be useful.

MUTTER_DEBUG_MULTI_GPU_FORCE_COPY_MODE allows for changing the copy mode for buffers from the primary GPU to secondary GPU. The documentation on this newly-merged debug code explains:

"Mutter composites the buffer to be displayed on all displays on the primary GPU, regardless of which GPU the display is connected to.

Therefore, when a display is connected to a secondary GPU, the contents to be displayed on that display need to be copied from the primary GPU to the secondary GPU.

There are 3 copy modes available:

- Secondary GPU copy mode: The copy is performed by the secondary GPU. This is the default copy mode.

- Zero-copy mode: The primary GPU exports a framebuffer and the secondary GPU imports it. This mode is tried if the secondary GPU copy mode fails.

- Primary GPU copy mode: The primary GPU copies its contents to a dumb buffer and the secondary GPU scan-outs from it. First, the GPU is used to perform the copy and, if it fails, the copy is perform by the CPU. This mode is used if the zero-copy mode fails.

For debug purposes, it is possible to force the copy mode by setting the environment variable `MUTTER_DEBUG_MULTI_GPU_FORCE_COPY_MODE` to `zero-copy`, `primary-gpu-gpu` or `primary-gpu-cpu`."

More details via this merge for those in need of multi-GPU debugging with GNOME.