[Pkg-opencl-devel] Bug#976295: ocl-icd-libopencl1: add docs for AMD proprietary OpenCL library, since mesa's doesn't work

[Ximin Luo]

Package: ocl-icd-libopencl1
Version: 2.2.13-1
Severity: important

Dear Maintainer,

Currently Debian does not have a working OpenCL library for a lot of AMD graphics
drivers - mesa-opencl-icd does not work or often breaks; and ROCm is not yet
packaged in Debian.

The AMDGPU PRO OpenCL drivers work with the open source AMDGPU driver that is
already part of Linux, but the official installation instructions are a bit
convoluted. Here are simpler ones, please include them in the docs of this package:

1. Look for the latest linux drivers on the AMD website. For example at the time of
   writing this is:

   https://www.amd.com/en/support/kb/release-notes/rn-amdgpu-unified-linux-20-45

2. Download the ones for Ubuntu, e.g.:
   
   https://drivers.amd.com/drivers/linux/amdgpu-pro-20.45-1164792-ubuntu-20.04.tar.xz

3. Unpack the tarball. This contains a ./amdgpu-pro-install script, however
   it will attempt to install the proprietary driver AMDGPU-PRO which is not
   necessary for us. (And it likely won't work, due to wanting a too-old
   version of linux than is in Debian Unstable.) Instead, we can install the
   unpacked Debian packages directly. You will need to install either:

   - opencl-orca-amdgpu-pro-icd, for older GPUs, or
   - opencl-rocr-amdgpu-pro, for newer ones.

   They can be installed both simultaneously in case you aren't sure which one
   works, or you need to switch GPUs constantly. Since you also need to install
   their dependencies, it's easiest to do this by adding:

   ~~~~
   deb [ trusted=yes ] file:/path/where/you/extracted/ ./
   ~~~~

   to /etc/apt/sources.list.d/amdgpu-pro-local.list then running `apt-get update`.

   Then run `apt-get install opencl-orca-amdgpu-pro-icd opencl-rocr-amdgpu-pro`.

4. Finally run clinfo(1) with the right LD_LIBRARY_PATH to check that it worked.
   You should get something like:

   ~~~~
   $ LD_LIBRARY_PATH=/opt/amdgpu-pro/lib/x86_64-linux-gnu/ clinfo -l
   Platform #0: AMD Accelerated Parallel Processing
    `-- Device #0: Ellesmere
   Platform #1: Clover
    `-- Device #0: Radeon RX 580 Series (POLARIS10, DRM 3.39.0, 5.9.0-4-amd64, LLVM 11.0.0)
   ~~~~

   Clover being what is output by mesa-opencl-icd, unfortunately it doesn't work
   e.g. leela-zero runs into errors with it.

5. To avoid needing LD_LIBRARY_PATH, edit /etc/OpenCL/vendors/amdocl*.icd to
   instead contain the full path to the particular library.

Best,
Ximin

-- System Information:
Debian Release: bullseye/sid
  APT prefers testing
  APT policy: (990, 'testing'), (500, 'unstable-debug'), (500, 'testing-debug'), (500, 'stable'), (300, 'unstable'), (100, 'experimental'), (1, 'experimental-debug')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 5.9.0-4-amd64 (SMP w/4 CPU threads)
Locale: LANG=en_GB.utf8, LC_CTYPE=en_GB.utf8 (charmap=UTF-8), LANGUAGE=en_GB:en
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages ocl-icd-libopencl1 depends on:
ii  libc6  2.31-4

ocl-icd-libopencl1 recommends no packages.

Versions of packages ocl-icd-libopencl1 suggests:
ii  mesa-opencl-icd [opencl-icd]  20.2.3-1

-- no debconf information