nixos: nixos/doc/manual/configuration/gpu-accel.xml to CommonMark
This commit is contained in:
parent
f04b9023e3
commit
5ad28f4197
|
@ -19,7 +19,7 @@
|
||||||
<xi:include href="file-systems.xml" />
|
<xi:include href="file-systems.xml" />
|
||||||
<xi:include href="../from_md/configuration/x-windows.chapter.xml" />
|
<xi:include href="../from_md/configuration/x-windows.chapter.xml" />
|
||||||
<xi:include href="../from_md/configuration/wayland.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="xfce.xml" />
|
||||||
<xi:include href="networking.xml" />
|
<xi:include href="networking.xml" />
|
||||||
<xi:include href="linux-kernel.xml" />
|
<xi:include href="linux-kernel.xml" />
|
||||||
|
|
204
nixos/doc/manual/configuration/gpu-accel.chapter.md
Normal file
204
nixos/doc/manual/configuration/gpu-accel.chapter.md
Normal file
|
@ -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.
|
|
@ -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>
|
|
244
nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
Normal file
244
nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
Normal file
|
@ -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>
|
Loading…
Reference in a new issue