diff options
| -rw-r--r-- | nixos/doc/manual/configuration/configuration.xml | 2 | ||||
| -rw-r--r-- | nixos/doc/manual/configuration/gpu-accel.chapter.md | 204 | ||||
| -rw-r--r-- | nixos/doc/manual/configuration/gpu-accel.xml | 262 | ||||
| -rw-r--r-- | nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml | 244 |
4 files changed, 449 insertions, 263 deletions
diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index adc3a88b3d8..b24399a2f2a 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -19,7 +19,7 @@ <xi:include href="file-systems.xml" /> <xi:include href="../from_md/configuration/x-windows.chapter.xml" /> <xi:include href="../from_md/configuration/wayland.chapter.xml" /> - <xi:include href="gpu-accel.xml" /> + <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" /> <xi:include href="xfce.xml" /> <xi:include href="networking.xml" /> <xi:include href="linux-kernel.xml" /> diff --git a/nixos/doc/manual/configuration/gpu-accel.chapter.md b/nixos/doc/manual/configuration/gpu-accel.chapter.md new file mode 100644 index 00000000000..5540250e1da --- /dev/null +++ b/nixos/doc/manual/configuration/gpu-accel.chapter.md @@ -0,0 +1,204 @@ +# GPU acceleration {#sec-gpu-accel} + +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. + +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. + +## OpenCL {#sec-gpu-accel-opencl} + +[OpenCL](https://en.wikipedia.org/wiki/OpenCL) is a general compute API. +It is used by various applications such as Blender and Darktable to +accelerate certain operations. + +OpenCL applications load drivers through the *Installable Client Driver* +(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 `OCL_ICD_VENDORS` environment variable. This variable can contain a +directory which is scanned by the ICL loader for ICD files. For example: + +```ShellSession +$ export \ + OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/ +``` + +The second mechanism is to add the OpenCL driver package to +[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages). +This links the ICD file under `/run/opengl-driver`, where it will be visible +to the ICD loader. + +The proper installation of OpenCL drivers can be verified through the +`clinfo` command of the clinfo package. This command will report the +number of hardware devices that is found and give detailed information +for each device: + +```ShellSession +$ clinfo | head -n3 +Number of platforms 1 +Platform Name AMD Accelerated Parallel Processing +Platform Vendor Advanced Micro Devices, Inc. +``` + +### AMD {#sec-gpu-accel-opencl-amd} + +Modern AMD [Graphics Core +Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are +supported through the rocm-opencl-icd package. Adding this package to +[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages) +enables OpenCL support: + +```nix +hardware.opengl.extraPackages = [ + rocm-opencl-icd + ]; +``` + +### Intel {#sec-gpu-accel-opencl-intel} + +[Intel Gen8 and later +GPUs](https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8) +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. + +The intel-compute-runtime, beignet, or intel-ocl package can be added to +[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages) +to enable OpenCL support. For example, for Gen8 and later GPUs, the following +configuration can be used: + +```nix +hardware.opengl.extraPackages = [ + intel-compute-runtime + ]; +``` + +## Vulkan {#sec-gpu-accel-vulkan} + +[Vulkan](https://en.wikipedia.org/wiki/Vulkan_(API)) is a graphics and +compute API for GPUs. It is used directly by games or indirectly though +compatibility layers like +[DXVK](https://github.com/doitsujin/dxvk/wiki). + +By default, if [`hardware.opengl.driSupport`](options.html#opt-hardware.opengl.driSupport) +is enabled, mesa is installed and provides Vulkan for supported hardware. + +Similar to OpenCL, Vulkan drivers are loaded through the *Installable +Client Driver* (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. + +The first option is through the `VK_ICD_FILENAMES` environment variable. +This variable can contain multiple JSON files, separated by `:`. For +example: + +```ShellSession +$ export \ + VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json +``` + +The second mechanism is to add the Vulkan driver package to +[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages). +This links the ICD file under `/run/opengl-driver`, where it will be +visible to the ICD loader. + +The proper installation of Vulkan drivers can be verified through the +`vulkaninfo` command of the vulkan-tools package. This command will +report the hardware devices and drivers found, in this example output +amdvlk and radv: + +```ShellSession +$ 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 +``` + +A simple graphical application that uses Vulkan is `vkcube` from the +vulkan-tools package. + +### AMD {#sec-gpu-accel-vulkan-amd} + +Modern AMD [Graphics Core +Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are +supported through either radv, which is part of mesa, or the amdvlk +package. Adding the amdvlk package to +[`hardware.opengl.extraPackages`](options.html#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: + +```nix +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"; +``` + +## Common issues {#sec-gpu-accel-common-issues} + +### User permissions {#sec-gpu-accel-common-issues-permissions} + +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 +(`/dev/dri/renderD*`) or are tagged as `uaccess` (`/dev/dri/card*`). The +access control lists of devices with the `uaccess` tag will be updated +automatically when a user logs in through `systemd-logind`. For example, +if the user *jane* is logged in, the access control list should look as +follows: + +```ShellSession +$ getfacl /dev/dri/card0 +# file: dev/dri/card0 +# owner: root +# group: video +user::rw- +user:jane:rw- +group::rw- +mask::rw- +other::--- +``` + +If you disabled (this functionality of) `systemd-logind`, you may need +to add the user to the `video` group and log in again. + +### Mixing different versions of nixpkgs {#sec-gpu-accel-common-issues-mixing-nixpkgs} + +The *Installable Client Driver* (ICD) mechanism used by OpenCL and +Vulkan loads runtimes into its address space using `dlopen`. 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. + +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 `LD_DEBUG` variable set to get more diagnostic information. For +example, OpenCL can be tested with `LD_DEBUG=files clinfo`, which should +report missing symbols. diff --git a/nixos/doc/manual/configuration/gpu-accel.xml b/nixos/doc/manual/configuration/gpu-accel.xml deleted file mode 100644 index 9aa9be86a06..00000000000 --- a/nixos/doc/manual/configuration/gpu-accel.xml +++ /dev/null @@ -1,262 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - 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 <varname>OCL_ICD_VENDORS</varname> - environment variable. This variable can contain a directory which - is scanned by the ICL loader for ICD files. For example: - - <screen><prompt>$</prompt> export \ - OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/</screen> - </para> - - <para> - The second mechanism is to add the OpenCL driver package to - <xref linkend="opt-hardware.opengl.extraPackages"/>. This links the - ICD file under <filename>/run/opengl-driver</filename>, where it will - be visible to the ICD loader. - </para> - - <para> - The proper installation of OpenCL drivers can be verified through - the <command>clinfo</command> command of the <package>clinfo</package> - package. This command will report the number of hardware devices - that is found and give detailed information for each device: - </para> - - <screen><prompt>$</prompt> clinfo | head -n3 -Number of platforms 1 -Platform Name AMD Accelerated Parallel Processing -Platform Vendor Advanced Micro Devices, Inc.</screen> - - <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 - <package>rocm-opencl-icd</package> package. Adding this package to - <xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL - support: - - <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ - rocm-opencl-icd - ];</programlisting> - </para> - </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 - <package>intel-compute-runtime</package> package. For Gen7 GPUs, - the deprecated Beignet runtime can be used, which is provided - by the <package>beignet</package> package. The proprietary Intel - OpenCL runtime, in the <package>intel-ocl</package> package, is - an alternative for Gen7 GPUs. - </para> - - <para> - The <package>intel-compute-runtime</package>, <package>beignet</package>, - or <package>intel-ocl</package> 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: - - <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ - intel-compute-runtime - ];</programlisting> - - </para> - </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, - <package>mesa</package> 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 <varname>VK_ICD_FILENAMES</varname> - environment variable. This variable can contain multiple JSON files, separated by - <literal>:</literal>. For example: - - <screen><prompt>$</prompt> export \ - VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json</screen> - </para> - - <para> - The second mechanism is to add the Vulkan driver package to - <xref linkend="opt-hardware.opengl.extraPackages"/>. This links the - ICD file under <filename>/run/opengl-driver</filename>, where it will - be visible to the ICD loader. - </para> - - <para> - The proper installation of Vulkan drivers can be verified through - the <command>vulkaninfo</command> command of the <package>vulkan-tools</package> - package. This command will report the hardware devices and drivers found, - in this example output amdvlk and radv: - </para> - - <screen><prompt>$</prompt> 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</screen> - - <para> - A simple graphical application that uses Vulkan is <command>vkcube</command> - from the <package>vulkan-tools</package> 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 <package>mesa</package>, or the <package>amdvlk</package> package. - Adding the <package>amdvlk</package> 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: - - <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ - pkgs.<package>amdvlk</package> - ]; - - # To enable Vulkan support for 32-bit applications, also add: - <xref linkend="opt-hardware.opengl.extraPackages32"/> = [ - pkgs.driversi686Linux.<package>amdvlk</package> - ]; - - # Force radv - <xref linkend="opt-environment.variables"/>.AMD_VULKAN_ICD = "RADV"; - # Or - <xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES = - "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; - </programlisting> - </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> 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..ec646810184 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml @@ -0,0 +1,244 @@ +<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 + <link xlink:href="options.html#opt-hardware.opengl.extraPackages"><literal>hardware.opengl.extraPackages</literal></link>. + 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 + <link xlink:href="options.html#opt-hardware.opengl.extraPackages"><literal>hardware.opengl.extraPackages</literal></link> + 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 + <link xlink:href="options.html#opt-hardware.opengl.extraPackages"><literal>hardware.opengl.extraPackages</literal></link> + 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 + <link xlink:href="options.html#opt-hardware.opengl.driSupport"><literal>hardware.opengl.driSupport</literal></link> + 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 + <link xlink:href="options.html#opt-hardware.opengl.extraPackages"><literal>hardware.opengl.extraPackages</literal></link>. + 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 + <link xlink:href="options.html#opt-hardware.opengl.extraPackages"><literal>hardware.opengl.extraPackages</literal></link> + 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> |