From a4035fc68e6684bc46fbf131982e799661e4f9c3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Exp=C3=B3sito?= <jexposit@redhat.com>
Date: Tue, 14 Jan 2025 15:53:57 +0100
Subject: [PATCH] docs/multi-gpu: Document mutter-device-preferred-primary

Add documentation explaining how to change the primary GPU using a udev
rule.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/4218>
---
 README.md        |  1 +
 doc/multi-gpu.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 doc/multi-gpu.md

diff --git a/README.md b/README.md
index 81eacc967..8c2b009a4 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,7 @@ documentation and API references below first.
 - [Building and Running](doc/building-and-running.md)
 - [Debugging](doc/debugging.md)
 - [Monitor configuration](doc/monitor-configuration.md)
+- [Multi-GPU](doc/multi-gpu.md)
 
 ## API Reference
 
diff --git a/doc/multi-gpu.md b/doc/multi-gpu.md
new file mode 100644
index 000000000..bce1b1963
--- /dev/null
+++ b/doc/multi-gpu.md
@@ -0,0 +1,42 @@
+# Multi-GPU
+
+## Selecting the primary GPU
+
+When multiple GPUs are present in the same system, Mutter applies a series of
+rules to select one of them as primary. However, it is possible to manually
+select a different GPU by using a udev rule.
+
+To illustrate it with an example, I'm going to make the NVIDIA GPU in my system
+to be selected as the primary GPU.
+
+Start by finding the vendor and device IDs of the target GPU:
+
+```bash
+$ lspci -nn
+[...]
+24:00.0 VGA compatible controller [0300]: NVIDIA Corporation AD107 [GeForce RTX 4060] [10de:2882] (rev a1)
+```
+
+In this case, we are looking for the vendor ID (10de) and the product (2882).
+
+Next, create rule to set the desired GPU as primary. Make sure to replace the
+vendor and device IDs:
+
+```bash
+$ cat /etc/udev/rules.d/61-mutter-preferred-primary-gpu.rules
+SUBSYSTEM=="drm", ENV{DEVTYPE}=="drm_minor", ENV{DEVNAME}=="/dev/dri/card[0-9]", SUBSYSTEMS=="pci", ATTRS{vendor}=="0x10de", ATTRS{device}=="0x2882", TAG+="mutter-device-preferred-primary"
+```
+
+Finally, restart and check that the desired GPU was selected:
+
+```bash
+$ journalctl -b0 /usr/bin/gnome-shell
+[...]
+Device '/dev/dri/card1' prefers shadow buffer
+Added device '/dev/dri/card1' (nouveau) using non-atomic mode setting.
+Device '/dev/dri/card2' prefers shadow buffer
+Added device '/dev/dri/card2' (amdgpu) using atomic mode setting.
+Created gbm renderer for '/dev/dri/card1'
+Created gbm renderer for '/dev/dri/card2'
+GPU /dev/dri/card1 selected primary given udev rule
+```