diff options
author | Daniël de Kok <me@danieldk.eu> | 2020-07-16 20:23:05 +0200 |
---|---|---|
committer | Daniël de Kok <me@danieldk.eu> | 2020-07-17 13:35:49 +0200 |
commit | 45edd3b41848f57e9863c0b4c3aa2d0cc2d24350 (patch) | |
tree | fdab8bfde9286ef33cec7be0b8e0cc5ac3bd453c /nixos/doc/manual | |
parent | 831ccff80bfe85f576025963c160a3bd8439aaed (diff) |
nixos/manual: add a section about enabling OpenCL for AMD GPUs
- Begin a new chapter "GPU Acceleration", this should also cover VA-API, OpenGL, Vulkan, etc. - Add a general blurb about OpenCL and how to check whether OpenCL devices are found. - Add a section about enabling OpenCL for AMD GPUs specifically.
Diffstat (limited to 'nixos/doc/manual')
-rw-r--r-- | nixos/doc/manual/configuration/configuration.xml | 1 | ||||
-rw-r--r-- | nixos/doc/manual/configuration/gpu-accel.xml | 104 |
2 files changed, 105 insertions, 0 deletions
diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 507d28814ead3..6eb8f50bacac6 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -18,6 +18,7 @@ <xi:include href="user-mgmt.xml" /> <xi:include href="file-systems.xml" /> <xi:include href="x-windows.xml" /> + <xi:include href="gpu-accel.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.xml b/nixos/doc/manual/configuration/gpu-accel.xml new file mode 100644 index 0000000000000..61229390d07a9 --- /dev/null +++ b/nixos/doc/manual/configuration/gpu-accel.xml @@ -0,0 +1,104 @@ +<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 devides + 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. However, OpenCL Image support is provided through the + non-free <package>rocm-runtime-ext</package> package. This package can + be added to the same configuration option, but requires that + <varname>allowUnfree</varname> option is is enabled for nixpkgs. Full + OpenCL support on supported AMD GPUs is thus enabled as follows: + + <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [ + rocm-opencl-icd + rocm-runtime-ext +];</programlisting> + </para> + + <para> + It is also possible to use the OpenCL Image extension without a + system-wide installation of the <package>rocm-runtime-ext</package> + package by setting the <varname>ROCR_EXT_DIR</varname> environment + variable to the directory that contains the extension: + + <screen><prompt>$</prompt> export \ +ROCR_EXT_DIR=`nix-build '<nixpkgs>' --no-out-link -A rocm-runtime-ext`/lib/rocm-runtime-ext</screen> + </para> + + <para> + With either approach, you can verify that OpenCL Image support + is indeed working with the <command>clinfo</command> command: + + <screen><prompt>$</prompt> clinfo | grep Image + Image support Yes</screen> + </para> + </section> + </section> +</chapter> |