git.iko.soy/typeable/nixpkgs
on master help sign in
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.

commit45edd3b41848f57e9863c0b4c3aa2d0cc2d24350 authorDaniël de Kok <me@danieldk.eu> dateThu 16 Jul 2020, 20:23 (6 years ago) parent831ccff
2 files changed+105
nixos/doc/manual/configuration/configuration.xml+1 nixos/doc/manual/configuration/gpu-accel.xml+104
nixos/doc/manual/configuration/configuration.xml+1
@@ -18,6 +18,7 @@
1818 <xi:include href="user-mgmt.xml" />
1919 <xi:include href="file-systems.xml" />
2020 <xi:include href="x-windows.xml" />
21+ <xi:include href="gpu-accel.xml" />
2122 <xi:include href="xfce.xml" />
2223 <xi:include href="networking.xml" />
2324 <xi:include href="linux-kernel.xml" />
nixos/doc/manual/configuration/gpu-accel.xmlnew file+104
@@ -0,0 +1,104 @@
1+<chapter xmlns="http://docbook.org/ns/docbook"
2+ xmlns:xlink="http://www.w3.org/1999/xlink"
3+ xmlns:xi="http://www.w3.org/2001/XInclude"
4+ version="5.0"
5+ xml:id="sec-gpu-accel">
6+ <title>GPU acceleration</title>
7+
8+ <para>
9+ NixOS provides various APIs that benefit from GPU hardware
10+ acceleration, such as VA-API and VDPAU for video playback; OpenGL and
11+ Vulkan for 3D graphics; and OpenCL for general-purpose computing.
12+ This chapter describes how to set up GPU hardware acceleration (as far
13+ as this is not done automatically) and how to verify that hardware
14+ acceleration is indeed used.
15+ </para>
16+
17+ <para>
18+ Most of the aforementioned APIs are agnostic with regards to which
19+ display server is used. Consequently, these instructions should apply
20+ both to the X Window System and Wayland compositors.
21+ </para>
22+
23+ <section xml:id="sec-gpu-accel-opencl">
24+ <title>OpenCL</title>
25+
26+ <para>
27+ <link xlink:href="https://en.wikipedia.org/wiki/OpenCL">OpenCL</link> is a
28+ general compute API. It is used by various applications such as
29+ Blender and Darktable to accelerate certain operations.
30+ </para>
31+
32+ <para>
33+ OpenCL applications load drivers through the <emphasis>Installable Client
34+ Driver</emphasis> (ICD) mechanism. In this mechanism, an ICD file
35+ specifies the path to the OpenCL driver for a particular GPU family.
36+ In NixOS, there are two ways to make ICD files visible to the ICD
37+ loader. The first is through the <varname>OCL_ICD_VENDORS</varname>
38+ environment variable. This variable can contain a directory which
39+ is scanned by the ICL loader for ICD files. For example:
40+
41+ <screen><prompt>$</prompt> export \
42+ OCL_ICD_VENDORS=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/</screen>
43+ </para>
44+
45+ <para>
46+ The second mechanism is to add the OpenCL driver package to
47+ <xref linkend="opt-hardware.opengl.extraPackages"/>. This links the
48+ ICD file under <filename>/run/opengl-driver</filename>, where it will
49+ be visible to the ICD loader.
50+ </para>
51+
52+ <para>
53+ The proper installation of OpenCL drivers can be verified through
54+ the <command>clinfo</command> command of the <package>clinfo</package>
55+ package. This command will report the number of hardware devides
56+ that is found and give detailed information for each device:
57+ </para>
58+
59+ <screen><prompt>$</prompt> clinfo | head -n3
60+Number of platforms 1
61+Platform Name AMD Accelerated Parallel Processing
62+Platform Vendor Advanced Micro Devices, Inc.</screen>
63+
64+ <section xml:id="sec-gpu-accel-opencl-amd">
65+ <title>AMD</title>
66+
67+ <para>
68+ Modern AMD <link
69+ xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
70+ Core Next</link> (GCN) GPUs are supported through the
71+ <package>rocm-opencl-icd</package> package. Adding this package to
72+ <xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL
73+ support. However, OpenCL Image support is provided through the
74+ non-free <package>rocm-runtime-ext</package> package. This package can
75+ be added to the same configuration option, but requires that
76+ <varname>allowUnfree</varname> option is is enabled for nixpkgs. Full
77+ OpenCL support on supported AMD GPUs is thus enabled as follows:
78+
79+ <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
80+ rocm-opencl-icd
81+ rocm-runtime-ext
82+];</programlisting>
83+ </para>
84+
85+ <para>
86+ It is also possible to use the OpenCL Image extension without a
87+ system-wide installation of the <package>rocm-runtime-ext</package>
88+ package by setting the <varname>ROCR_EXT_DIR</varname> environment
89+ variable to the directory that contains the extension:
90+
91+ <screen><prompt>$</prompt> export \
92+ROCR_EXT_DIR=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A rocm-runtime-ext`/lib/rocm-runtime-ext</screen>
93+ </para>
94+
95+ <para>
96+ With either approach, you can verify that OpenCL Image support
97+ is indeed working with the <command>clinfo</command> command:
98+
99+ <screen><prompt>$</prompt> clinfo | grep Image
100+ Image support Yes</screen>
101+ </para>
102+ </section>
103+ </section>
104+</chapter>