diff options
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.xml | 239 |
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 '<nixpkgs>' --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 '<nixpkgs>' --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 = "RADV"; +# Or +environment.variables.VK_ICD_FILENAMES = + "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; +</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> |