nixos/manual: add a section about common GPU acceleration issues

1 files changed, 59 insertions, 0 deletions

diff --git a/nixos/doc/manual/configuration/gpu-accel.xml b/nixos/doc/manual/configuration/gpu-accel.xml
index 0aa629cce98..dc806e8812d 100644
--- a/nixos/doc/manual/configuration/gpu-accel.xml
+++ b/nixos/doc/manual/configuration/gpu-accel.xml
@@ -190,4 +190,63 @@ GPU1:
       </para>
     </section>
   </section>
+
+  <section xml:id="sec-gpu-accel-common-issues">
+   <title>Common issues</title>
+
+   <section xml:id="sec-gpu-accel-common-issues-permissions">
+    <title>User permissions</title>
+
+    <para>
+     Except where noted explicitly, it should not be necessary to
+     adjust user permissions to use these acceleration APIs. In the default
+     configuration, GPU devices have world-read/write permissions
+     (<filename>/dev/dri/renderD*</filename>) or are tagged as
+     <code>uaccess</code> (<filename>/dev/dri/card*</filename>).  The
+     access control lists of devices with the <varname>uaccess</varname>
+     tag will be updated automatically when a user logs in through
+     <command>systemd-logind</command>. For example, if the user
+     <emphasis>jane</emphasis> is logged in, the access control list
+     should look as follows:
+
+     <screen><prompt>$</prompt> getfacl /dev/dri/card0
+# file: dev/dri/card0
+# owner: root
+# group: video
+user::rw-
+user:jane:rw-
+group::rw-
+mask::rw-
+other::---</screen>
+
+     If you disabled (this functionality of) <command>systemd-logind</command>,
+     you may need to add the user to the <code>video</code> group and
+     log in again.
+    </para>
+   </section>
+
+   <section xml:id="sec-gpu-accel-common-issues-mixing-nixpkgs">
+    <title>Mixing different versions of nixpkgs</title>
+
+    <para>
+     The <emphasis>Installable Client Driver</emphasis> (ICD)
+     mechanism used by OpenCL and Vulkan loads runtimes into its address
+     space using <code>dlopen</code>. Mixing an ICD loader mechanism and
+     runtimes from different version of nixpkgs may not work. For example,
+     if the ICD loader uses an older version of <package>glibc</package>
+     than the runtime, the runtime may not be loadable due to
+     missing symbols. Unfortunately, the loader will generally be quiet
+     about such issues.
+    </para>
+
+    <para>
+     If you suspect that you are running into library version mismatches
+     between an ICL loader and a runtime, you could run an application with
+     the <code>LD_DEBUG</code> variable set to get more diagnostic
+     information. For example, OpenCL can be tested with
+     <code>LD_DEBUG=files clinfo</code>, which should report missing
+     symbols.
+    </para>
+   </section>
+  </section>
 </chapter>