Install oneAPI for AMD GPUs - Guides - oneAPI for AMD GPUs - Products - Codeplay Developer (2024)

This release has been tested on the following platforms (using the upstream AMD GPU driver in the Linux kernel):

In theory this release should work with all devices that are compatible with ROCm.

• This release should work with all HIP 5.x and 6.x versions, but only HIP5.4.3, 5.7.1, 6.0.2 and 6.1.0 have been tested. Codeplay cannot guaranteecorrect operation with other HIP releases.

  • Each of the tested versions can be installed alongside another existing HIPinstallation. See theMulti-version ROCm Installationsection of the ROCm Installation Guide.

• This release should work across a wide array of AMD GPUs that are supportedby ROCm, but Codeplay cannot guarantee correct operation on untestedplatforms. AMD GPUs not officially supported by ROCm may also work.

• For a full list of AMD GPUs that are officially supported by ROCm Linux, seehere.

• The package has been tested on Ubuntu 22.04 only, but can be installed onany Linux systems.

• The “oneAPI for AMD GPUs” packages currently onlysupport Linux.

1. Install C++ development tools.

   You will need the following C++ development tools installed in order tobuild and run oneAPI applications: cmake, gcc, g++, make andpkg-config.

   The following console commands will install the above tools on the mostpopular Linux distributions:

   Ubuntu

   sudo apt updatesudo apt -y install cmake pkg-config build-essential

   Red Hat and Fedora

   sudo yum updatesudo yum -y install cmake pkgconfigsudo yum groupinstall "Development Tools"

   SUSE

   sudo zypper updatesudo zypper --non-interactive install cmake pkg-configsudo zypper --non-interactive install pattern devel_C_C++

   Verify that the tools are installed by running:

   See Also

   BannerText Windows Installer | BytesConfiguring g++-13 and g++-14 in VSCode tasks.json for macOSRosetta compilation error through newer gcc-g++ versionsVS2003 SP1 goes stupid on install | Bytes

   which cmake pkg-config make gcc g++

   You should see output similar to:

   /usr/bin/cmake/usr/bin/pkg-config/usr/bin/make/usr/bin/gcc/usr/bin/g++

2. Install an Intel® oneAPI Toolkitversion 2024.2.0, that contains the DPC++/C++ Compiler.

   • For example, the “Intel oneAPI Base Toolkit” should suit most use cases.

   • The Toolkit must be version 2024.2.0 - otherwise oneAPI forAMD GPUs cannot be installed.

3. Install the GPU driver and ROCm™ software stack for the AMD GPU.

   • For example, for ROCm 5.4.3, follow the steps described in theInstallation with install script guide.

   • Using the amdgpu-install installer is recommended, with the--usecase="dkms,graphics,opencl,hip,hiplibsdk" argument to ensure thatall required components are installed.

1. Download the latest oneAPI for AMD GPUs installer:

   1. Directly via Website

   2. Using Download API with cURL or WGET(requires an account)

2. Run the downloaded self-extracting installer:

   sh oneapi-for-amd-gpus-2024.2.0-rocm-5.4.3-linux.sh

   • The installer will search for an existing Intel oneAPI Toolkitversion 2024.2.0installation in common locations. If you have installed an Intel oneAPIToolkit in a custom location, use --install-dir /path/to/intel/oneapi.

   • If your Intel oneAPI Toolkit installation is outside your home directory,you may be required to run this command with elevated privileges, e.g.sudo.

1. To set up your oneAPI environment in your current session, source theIntel-provided setvars.sh script.

   For system-wide installations:

   . /opt/intel/oneapi/setvars.sh --include-intel-llvm

   For private installations (in the default location):

   . ~/intel/oneapi/setvars.sh --include-intel-llvm

   • The --include-intel-llvm option is required in order to add LLVM toolssuch as clang++ to the path.

   • Note that you will have to run this script in every new terminal session.For options to handle the setup automatically each session, see the relevantIntel oneAPI Toolkit documentation, such asSet Environment Variables for CLI Development.

     See Also

     Install oneAPI for AMD GPUs - Guides - oneAPI for AMD GPUs - Products - Codeplay Developer

2. Ensure that the HIP libraries and tools can be found in your environment:

   1. Run rocminfo - if it runs without any obvious errors in the outputthen your environment should be set up correctly.

   2. Otherwise, set your environment variables manually:

      export PATH=/PATH_TO_ROCM_ROOT/bin:$PATHexport LD_LIBRARY_PATH=/PATH_TO_ROCM_ROOT/lib:$LD_LIBRARY_PATH

      ROCm is commonly installed in /opt/rocm-x.x.x/.

To verify the DPC++ HIP plugin installation, the DPC++ sycl-ls tool can beused to make sure that SYCL now exposes the available AMD GPUs. You should seesomething similar to the following in the sycl-ls output if AMD GPUs are found:

[hip:gpu][hip:0] AMD HIP BACKEND, AMD Radeon PRO W6800 gfx1030 [HIP 60140.9]

• If the available AMD GPUs are correctly listed, then the DPC++ HIPplugin was correctly installed and set up.

• Otherwise, see the “Missing devices in sycl-ls output” section of theTroubleshooting documentation.

• Note that this command may also list other devices such as OpenCL™devices, Intel GPUs, or NVIDIA® GPUs, based on the available hardwareand DPC++ plugins installed.

1. Create a file simple-sycl-app.cpp with the following C++/SYCL code:

   #include <sycl/sycl.hpp>int main() { // Creating buffer of 4 ints to be used inside the kernel code sycl::buffer<int, 1> Buffer{4}; // Creating SYCL queue sycl::queue Queue{}; // Size of index space for kernel sycl::range<1> NumOfWorkItems{Buffer.size()}; // Submitting command group(work) to queue Queue.submit([&](sycl::handler &cgh) { // Getting write only access to the buffer on a device auto Accessor = Buffer.get_access<sycl::access::mode::write>(cgh); // Executing kernel cgh.parallel_for<class FillBuffer>( NumOfWorkItems, [=](sycl::id<1> WIid) { // Fill buffer with indexes Accessor[WIid] = static_cast<int>(WIid.get(0)); }); }); // Getting read only access to the buffer on the host. // Implicit barrier waiting for queue to complete the work. auto HostAccessor = Buffer.get_host_access(); // Check the results bool MismatchFound{false}; for (size_t I{0}; I < Buffer.size(); ++I) { if (HostAccessor[I] != I) { std::cout << "The result is incorrect for element: " << I << " , expected: " << I << " , got: " << HostAccessor[I] << std::endl; MismatchFound = true; } } if (!MismatchFound) { std::cout << "The results are correct!" << std::endl; } return MismatchFound;}

2. Compile the application with:

   icpx -fsycl -fsycl-targets=amdgcn-amd-amdhsa \ -Xsycl-target-backend --offload-arch=<ARCH> \ -o simple-sycl-app simple-sycl-app.cpp

   Where ARCH is the GPU architecture e.g. gfx1030, which you can check byrunning:

   rocminfo | grep 'Name: *gfx.*'

   You should see the GPU architecture in the output, for example:

    Name: gfx1030

3. Run the application with:

   ONEAPI_DEVICE_SELECTOR="hip:*" SYCL_PI_TRACE=1 ./simple-sycl-app

   You should see output like:

   SYCL_PI_TRACE[basic]: Plugin found and successfully loaded: libpi_hip.so [ PluginVersion: 15.51.1 ]SYCL_PI_TRACE[basic]: Plugin found and successfully loaded: libpi_unified_runtime.so [ PluginVersion: 15.51.1 ]SYCL_PI_TRACE[all]: Requested device_type: info::device_type::automaticSYCL_PI_TRACE[all]: Selected device: -> final score = 1500SYCL_PI_TRACE[all]: platform: AMD HIP BACKENDSYCL_PI_TRACE[all]: device: AMD Radeon PRO W6800The results are correct!

   If so, you have successfully set up and verified your oneAPI for AMD GPUsdevelopment environment, and you can begin developing oneAPI applications.

   The rest of this document provides general information on compiling andrunning oneAPI applications on AMD GPUs.

To compile a SYCL application for AMD GPUs, use the icpx compilerprovided with DPC++. For example:

icpx -fsycl -fsycl-targets=amdgcn-amd-amdhsa \ -Xsycl-target-backend=amdgcn-amd-amdhsa --offload-arch=gfx1030 \ -o sycl-app sycl-app.cpp

The following flags are required:

• -fsycl: Instructs the compiler to build the C++ source file inSYCL mode. This flag will also implicitly enable C++17 and automaticallylink against the SYCL runtime library.

• -fsycl-targets=amdgcn-amd-amdhsa: Instructs the compiler tobuild SYCL kernels for the AMD GPU target.

• -Xsycl-target-backend=amdgcn-amd-amdhsa --offload-arch=gfx1030:Instructs the compiler to build SYCL kernels for the gfx1030 AMDGPU architecture.

Note that when targeting an AMD GPU, the specific architecture of the GPUmust be provided.

For more information on available SYCL compilation flags, see theDPC++ Compiler User’s Manualor for information on all DPC++ compiler options see theCompiler Optionssection of the Intel oneAPI DPC++/C++ Compiler Developer Guide and Reference.

The icpx compiler is by default a lot more aggressive with optimizations thanthe regular clang++ driver, as it uses both -O2 and -ffast-math. In manycases this can lead to better performance but it can also lead to some issuesfor certain applications. In such cases it is possible to disable -ffast-mathby using -fno-fast-math and to change the optimization level by passing adifferent -O flag. It is also possible to directly use the clang++ driverwhich can be found in $releasedir/compiler/latest/linux/bin-llvm/clang++, toget regular clang++ behavior.

In addition to targeting AMD GPUs, you can build SYCL applications that can becompiled once and then run on a range of hardware. The following example showshow to output a single binary including device code that can run on AMD GPUs,NVIDIA GPUs, or any device that supports SPIR e.g. Intel GPUs.

icpx -fsycl -fsycl-targets=amdgcn-amd-amdhsa,nvptx64-nvidia-cuda,spir64 \ -Xsycl-target-backend=amdgcn-amd-amdhsa --offload-arch=gfx1030 \ -Xsycl-target-backend=nvptx64-nvidia-cuda --offload-arch=sm_80 \ -o sycl-app sycl-app.cpp

After compiling your SYCL application for an AMD target, you should alsoensure that the correct SYCL device representing the AMD GPU is selected atruntime.

In general, simply using the default device selector should select one of theavailable AMD GPUs. However in some scenarios, users may want to change theirSYCL application to use a more precise SYCL device selector, such as the GPUselector, or even a custom selector.

The environment variable ONEAPI_DEVICE_SELECTOR may be used to help the SYCLdevice selectors by restricting the set of devices that can be used. Forexample, to only allow devices exposed by the DPC++ HIP plugin:

export ONEAPI_DEVICE_SELECTOR="hip:*"

For more details on this environment variable, see theEnvironment Variables section of the oneAPI DPC++ Compiler documentation.Note: this environment variable will be deprecated in a subsequent release.