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.

2 files changed, 105 insertions, 0 deletions

diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index 507d28814ea..6eb8f50baca 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 00000000000..61229390d07
--- /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 '&lt;nixpkgs&gt;' --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 '&lt;nixpkgs&gt;' --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>