summary refs log tree commit diff
path: root/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml')
-rw-r--r--nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml239
1 files changed, 239 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
new file mode 100644
index 00000000000..8e780c5dee9
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
@@ -0,0 +1,239 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-gpu-accel">
+  <title>GPU acceleration</title>
+  <para>
+    NixOS provides various APIs that benefit from GPU hardware
+    acceleration, such as VA-API and VDPAU for video playback; OpenGL
+    and Vulkan for 3D graphics; and OpenCL for general-purpose
+    computing. This chapter describes how to set up GPU hardware
+    acceleration (as far as this is not done automatically) and how to
+    verify that hardware acceleration is indeed used.
+  </para>
+  <para>
+    Most of the aforementioned APIs are agnostic with regards to which
+    display server is used. Consequently, these instructions should
+    apply both to the X Window System and Wayland compositors.
+  </para>
+  <section xml:id="sec-gpu-accel-opencl">
+    <title>OpenCL</title>
+    <para>
+      <link xlink:href="https://en.wikipedia.org/wiki/OpenCL">OpenCL</link>
+      is a general compute API. It is used by various applications such
+      as Blender and Darktable to accelerate certain operations.
+    </para>
+    <para>
+      OpenCL applications load drivers through the <emphasis>Installable
+      Client Driver</emphasis> (ICD) mechanism. In this mechanism, an
+      ICD file specifies the path to the OpenCL driver for a particular
+      GPU family. In NixOS, there are two ways to make ICD files visible
+      to the ICD loader. The first is through the
+      <literal>OCL_ICD_VENDORS</literal> environment variable. This
+      variable can contain a directory which is scanned by the ICL
+      loader for ICD files. For example:
+    </para>
+    <programlisting>
+$ export \
+  OCL_ICD_VENDORS=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/
+</programlisting>
+    <para>
+      The second mechanism is to add the OpenCL driver package to
+      <xref linkend="opt-hardware.opengl.extraPackages" />. This links
+      the ICD file under <literal>/run/opengl-driver</literal>, where it
+      will be visible to the ICD loader.
+    </para>
+    <para>
+      The proper installation of OpenCL drivers can be verified through
+      the <literal>clinfo</literal> command of the clinfo package. This
+      command will report the number of hardware devices that is found
+      and give detailed information for each device:
+    </para>
+    <programlisting>
+$ clinfo | head -n3
+Number of platforms  1
+Platform Name        AMD Accelerated Parallel Processing
+Platform Vendor      Advanced Micro Devices, Inc.
+</programlisting>
+    <section xml:id="sec-gpu-accel-opencl-amd">
+      <title>AMD</title>
+      <para>
+        Modern AMD
+        <link xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
+        Core Next</link> (GCN) GPUs are supported through the
+        rocm-opencl-icd package. Adding this package to
+        <xref linkend="opt-hardware.opengl.extraPackages" /> enables
+        OpenCL support:
+      </para>
+      <programlisting language="bash">
+hardware.opengl.extraPackages = [
+  rocm-opencl-icd
+];
+</programlisting>
+    </section>
+    <section xml:id="sec-gpu-accel-opencl-intel">
+      <title>Intel</title>
+      <para>
+        <link xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8">Intel
+        Gen8 and later GPUs</link> are supported by the Intel NEO OpenCL
+        runtime that is provided by the intel-compute-runtime package.
+        For Gen7 GPUs, the deprecated Beignet runtime can be used, which
+        is provided by the beignet package. The proprietary Intel OpenCL
+        runtime, in the intel-ocl package, is an alternative for Gen7
+        GPUs.
+      </para>
+      <para>
+        The intel-compute-runtime, beignet, or intel-ocl package can be
+        added to <xref linkend="opt-hardware.opengl.extraPackages" /> to
+        enable OpenCL support. For example, for Gen8 and later GPUs, the
+        following configuration can be used:
+      </para>
+      <programlisting language="bash">
+hardware.opengl.extraPackages = [
+  intel-compute-runtime
+];
+</programlisting>
+    </section>
+  </section>
+  <section xml:id="sec-gpu-accel-vulkan">
+    <title>Vulkan</title>
+    <para>
+      <link xlink:href="https://en.wikipedia.org/wiki/Vulkan_(API)">Vulkan</link>
+      is a graphics and compute API for GPUs. It is used directly by
+      games or indirectly though compatibility layers like
+      <link xlink:href="https://github.com/doitsujin/dxvk/wiki">DXVK</link>.
+    </para>
+    <para>
+      By default, if <xref linkend="opt-hardware.opengl.driSupport" />
+      is enabled, mesa is installed and provides Vulkan for supported
+      hardware.
+    </para>
+    <para>
+      Similar to OpenCL, Vulkan drivers are loaded through the
+      <emphasis>Installable Client Driver</emphasis> (ICD) mechanism.
+      ICD files for Vulkan are JSON files that specify the path to the
+      driver library and the supported Vulkan version. All successfully
+      loaded drivers are exposed to the application as different GPUs.
+      In NixOS, there are two ways to make ICD files visible to Vulkan
+      applications: an environment variable and a module option.
+    </para>
+    <para>
+      The first option is through the
+      <literal>VK_ICD_FILENAMES</literal> environment variable. This
+      variable can contain multiple JSON files, separated by
+      <literal>:</literal>. For example:
+    </para>
+    <programlisting>
+$ export \
+  VK_ICD_FILENAMES=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json
+</programlisting>
+    <para>
+      The second mechanism is to add the Vulkan driver package to
+      <xref linkend="opt-hardware.opengl.extraPackages" />. This links
+      the ICD file under <literal>/run/opengl-driver</literal>, where it
+      will be visible to the ICD loader.
+    </para>
+    <para>
+      The proper installation of Vulkan drivers can be verified through
+      the <literal>vulkaninfo</literal> command of the vulkan-tools
+      package. This command will report the hardware devices and drivers
+      found, in this example output amdvlk and radv:
+    </para>
+    <programlisting>
+$ vulkaninfo | grep GPU
+                GPU id  : 0 (Unknown AMD GPU)
+                GPU id  : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
+     ...
+GPU0:
+        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
+        deviceName     = Unknown AMD GPU
+GPU1:
+        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
+</programlisting>
+    <para>
+      A simple graphical application that uses Vulkan is
+      <literal>vkcube</literal> from the vulkan-tools package.
+    </para>
+    <section xml:id="sec-gpu-accel-vulkan-amd">
+      <title>AMD</title>
+      <para>
+        Modern AMD
+        <link xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
+        Core Next</link> (GCN) GPUs are supported through either radv,
+        which is part of mesa, or the amdvlk package. Adding the amdvlk
+        package to <xref linkend="opt-hardware.opengl.extraPackages" />
+        makes amdvlk the default driver and hides radv and lavapipe from
+        the device list. A specific driver can be forced as follows:
+      </para>
+      <programlisting language="bash">
+hardware.opengl.extraPackages = [
+  pkgs.amdvlk
+];
+
+# To enable Vulkan support for 32-bit applications, also add:
+hardware.opengl.extraPackages32 = [
+  pkgs.driversi686Linux.amdvlk
+];
+
+# Force radv
+environment.variables.AMD_VULKAN_ICD = &quot;RADV&quot;;
+# Or
+environment.variables.VK_ICD_FILENAMES =
+  &quot;/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json&quot;;
+</programlisting>
+    </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 (<literal>/dev/dri/renderD*</literal>) or are tagged
+        as <literal>uaccess</literal>
+        (<literal>/dev/dri/card*</literal>). The access control lists of
+        devices with the <literal>uaccess</literal> tag will be updated
+        automatically when a user logs in through
+        <literal>systemd-logind</literal>. For example, if the user
+        <emphasis>jane</emphasis> is logged in, the access control list
+        should look as follows:
+      </para>
+      <programlisting>
+$ getfacl /dev/dri/card0
+# file: dev/dri/card0
+# owner: root
+# group: video
+user::rw-
+user:jane:rw-
+group::rw-
+mask::rw-
+other::---
+</programlisting>
+      <para>
+        If you disabled (this functionality of)
+        <literal>systemd-logind</literal>, you may need to add the user
+        to the <literal>video</literal> 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 <literal>dlopen</literal>. 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 glibc 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 <literal>LD_DEBUG</literal> variable set to
+        get more diagnostic information. For example, OpenCL can be
+        tested with <literal>LD_DEBUG=files clinfo</literal>, which
+        should report missing symbols.
+      </para>
+    </section>
+  </section>
+</chapter>