Repository: pocl/pocl
Pull request #1837: Add documentation for how to setup and use DPC++ with PoCL
Author: login: tneval
Created: 2025-03-12T16:17:06Z | Merged: 2025-03-24T07:52:52Z

Addresses #1801
- Added DPC++ documentation.
- Fixed reference to POCL_DRIVER_VERSION_OVERRIDE.


Diff:
diff --git a/doc/sphinx/source/sycl_dpcpp.rst b/doc/sphinx/source/sycl_dpcpp.rst
new file mode 100644
index 0000000000..ed7bca74c7
--- /dev/null
+++ b/doc/sphinx/source/sycl_dpcpp.rst
@@ -0,0 +1,248 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles. Installing the oneAPI Base Toolkit is the simplest way to install DPC++ and its dependencies.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed to run SYCL applications with PoCL.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required here)
+
+After installation, run the initialization script to set the environment variables::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+.. important::
+   ``setvars.sh`` must be run in every new shell session unless added to ``.bashrc`` (or an equivalent).
+
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected).:
+
+.. code-block:: none
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``:
+
+.. code-block:: none
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from the `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+You must check out and build a version of ``llvm-spirv`` that corresponds to the LLVM
+version PoCL uses as its kernel compiler. For example, if the PoCL kernel compiler uses
+**LLVM 18**, then ``llvm-spirv`` should be checked out from the ``llvm_release_180`` branch.
+
+.. note::
+   DPC++ ships with its own ``llvm-spirv``, which is typically based on the latest release.
+   However, this version is intended for internal usage by DPC++ and cannot be used by PoCL.
+
+
+.. warning::
+   Although the versions of ``llvm-spirv`` used by DPC++ and PoCL do not have to be an exact
+   match, it is recommended to use versions that are reasonably close to each other.
+
+
+Example PoCL build:
+
+.. code-block:: none
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+    ninja install
+
+To make PoCL visible to the ICD loader, either register the PoCL ICD (https://github.com/KhronosGroup/OpenCL-ICD-Loader#registering-icds)
+or set the ``OCL_ICD_FILENAMES`` or ``OCL_ICD_VENDORS`` environment variables. ``OCL_ICD_VENDORS`` only works on Linux/Android,
+whereas ``OCL_ICD_FILENAMES`` works on all platforms (see https://github.com/KhronosGroup/OpenCL-ICD-Loader#table-of-debug-environment-variables
+for more information).
+
+On Linux:
+
+.. code-block:: none
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
+
+
+Compiling with DPC++ using PoCL as the backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If using proprietary DPC++, there is one additional step.
+By default PoCL is blocked by the DPC++ runtime. To enable PoCL, we need to set the ``SYCL_DEVICE_ALLOWLIST``
+environment variable. This variable is a comma-separated list of parameters that the DPC++ runtime uses to select allowed devices.
+It can be used quite flexibly. For example, to select only CPU devices:
+
+.. code-block:: none
+
+    export SYCL_DEVICE_ALLOWLIST="DeviceType:cpu"
+
+To allow all available devices, use:
+
+.. code-block:: none
+
+    export SYCL_DEVICE_ALLOWLIST=""
+
+
+To select only PoCL, you can use the PoCL vendor ID:
+
+.. code-block:: none
+
+    export SYCL_DEVICE_ALLOWLIST="DeviceVendorId:0x10006"
+
+
+For more information about how to use the DPC++ environment variables, see:
+
+https://github.com/intel/llvm/blob/sycl/sycl/doc/EnvironmentVariables.md
+
+Now that everything is set up, verify that PoCL is detected:
+
+.. code-block:: none
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Portable Computing Language, cpu-znver1-AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 PoCL HSTR: cpu-x86_64-pc-linux-gnu-znver1
+
+Below is a simple SYCL program to test the setup. It selects the device automatically, so this will drop the possible GPUs out of the list:
+
+.. code-block:: none
+
+    export ONEAPI_DEVICE_SELECTOR=opencl:cpu
+
+.. code-block:: c++
+
+    // hello_nd_range.cpp
+    #include <sycl/sycl.hpp>
+    #include <iostream>
+
+    #define SUB_GROUP_SIZE 2
+
+    using namespace sycl;
+
+    int main() {
+        constexpr int global_size = 8;
+        constexpr int local_size = 4;
+
+        queue q;
+        {
+            q.submit([&](handler &h) {
+
+                std::cout << "One dimensional nd_range with global_size: " << global_size << ", local_size: " << local_size << ", sg_size: " << SUB_GROUP_SIZE << "\n";
+
+                range<1> global(global_size);
+                range<1> local(local_size);
+                nd_range<1> range(global, local);
+
+                h.parallel_for(range, [=](nd_item<1> idx) [[sycl::reqd_sub_group_size(SUB_GROUP_SIZE)]] {
+
+                    int workgroup_id_x = idx.get_group(0);
+                    int global_id_x = idx.get_global_id(0);
+                    int local_id_x = idx.get_local_id(0);
+                    int sg_local_id = idx.get_sub_group().get_local_id();
+                    int sg_id = idx.get_sub_group().get_group_id();
+                    sycl::ext::oneapi::experimental::printf("hello from: (global_id %d) (local_id: %d) (wg_id: %d) (sg_id: %d) (sg_local id: %d)\n",global_id_x, local_id_x,workgroup_id_x, sg_id, sg_local_id);
+                });
+            }).wait();
+        }
+        return 0;
+    }
+
+Compile and run (use ``icpx`` for proprietary version, and ``clang++`` for open-source version)::
+
+    clang++ hello_nd_range.cpp -fsycl -o hello
+    ./hello
+
+    One dimensional nd_range with global_size: 8, local_size: 4, sg_size: 2
+    hello from: (global_id 0) (local_id: 0) (wg_id: 0) (sg_id: 0) (sg_local id: 0)
+    hello from: (global_id 1) (local_id: 1) (wg_id: 0) (sg_id: 0) (sg_local id: 1)
+    hello from: (global_id 2) (local_id: 2) (wg_id: 0) (sg_id: 1) (sg_local id: 0)
+    hello from: (global_id 3) (local_id: 3) (wg_id: 0) (sg_id: 1) (sg_local id: 1)
+    hello from: (global_id 4) (local_id: 0) (wg_id: 1) (sg_id: 0) (sg_local id: 0)
+    hello from: (global_id 5) (local_id: 1) (wg_id: 1) (sg_id: 0) (sg_local id: 1)
+    hello from: (global_id 6) (local_id: 2) (wg_id: 1) (sg_id: 1) (sg_local id: 0)
+    hello from: (global_id 7) (local_id: 3) (wg_id: 1) (sg_id: 1) (sg_local id: 1)
diff --git a/doc/sphinx/source/using.rst b/doc/sphinx/source/using.rst
index d828dcdcb8..310795dbbe 100644
--- a/doc/sphinx/source/using.rst
+++ b/doc/sphinx/source/using.rst
@@ -152,7 +152,7 @@ pocl.
 
  Overrides the vendor id reported by PoCL for the CPU drivers.
  For example, setting the vendor id to be 32902 (0x8086) and setting the driver
- version using **POCL_DRIVER_VER_OVERRIDE** to "2023.16.7.0.21_160000" (or such) can
+ version using **POCL_DRIVER_VERSION_OVERRIDE** to "2023.16.7.0.21_160000" (or such) can
  be used to convince binary-distributed DPC++ compilers to compile and run SYCL
  programs on the PoCL-CPU driver.
 
@@ -453,4 +453,5 @@ pocl.
   the local size, global offset zero or non-zero and maximum grid size.
   The specialization can be disabled by setting this environment variable to 0.
 
-.. include:: macos.rst
\ No newline at end of file
+.. include:: macos.rst
+.. include:: sycl_dpcpp.rst
\ No newline at end of file


Reviews:
user: login: pjaaskel
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-03-13T11:34:59Z
user: login: franz
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-13T11:47:47Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:03:34Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:03:50Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:24:21Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:24:28Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:24:37Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:25:20Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:25:31Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:27:54Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:29:59Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:31:09Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T16:02:17Z
user: login: bashbaug
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T16:07:45Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T16:10:46Z
user: login: pjaaskel
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-13T16:54:30Z
user: login: pjaaskel
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-13T16:58:17Z
user: login: Pennycook
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-14T12:14:36Z
user: login: pjaaskel
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-14T14:03:31Z
user: login: franz
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-15T19:32:21Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T14:22:11Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T14:24:25Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T14:31:58Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T14:33:43Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T14:37:04Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T16:18:09Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T16:19:22Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T16:19:39Z
user: login: tneval
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T16:19:47Z
user: login: franz
body: Looks good overall. Was just wondering if we should merge this somehow with the ARM SYCL document, but that can be done in a separate PR
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-22T19:51:26Z
user: login: pjaaskel
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-24T07:48:39Z
user: login: pjaaskel
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-24T07:52:44Z

Review comments:
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: ```suggestion
SYCL is a programming model that enables single-source C++ development for
```
Check grammar.
created_at: 2025-03-13T11:22:19Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: Check when writing about DPC++ and SYCL. A runtime might or might not support OpenCL/SPIR-V. Initially it was a must, but they diverged in this front and it's not required to be a layer on OpenCL.
created_at: 2025-03-13T11:23:40Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: ```suggestion
DPC++ is Intel's implementation of SYCL, and the toolchain flow, when PoCL is used as the OpenCL backend is as follows:
```
created_at: 2025-03-13T11:24:16Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: ```suggestion
- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
```
created_at: 2025-03-13T11:24:53Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: ```suggestion
- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
```
created_at: 2025-03-13T11:25:10Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: The URL seems like it will break soon. Perhaps we should not copy the instructions for DPC++ installation here, but just link to a landing page in the Intel site?
created_at: 2025-03-13T11:26:40Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: It's "Intel(R) oneAPI DPC++/C++ Compiler" while the open-source C++ compiler is "oneAPI DPC++/C++ Compiler". Just somewhere state the former is binary distributed with Intel-only-known modifications and latter open source.
created_at: 2025-03-13T11:30:00Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+
+The installer can be run with different options, either via the GUI or command line.
+
+To install with GUI::
+
+    sh ./intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+The oneAPI Base Toolkit includes various components, some of which have dependencies.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+Open-source DPC++ installation
+------------------------------
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: ```suggestion
    git clone git@github.com:intel/llvm
```
Right?
created_at: 2025-03-13T11:31:16Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+
+The installer can be run with different options, either via the GUI or command line.
+
+To install with GUI::
+
+    sh ./intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+The oneAPI Base Toolkit includes various components, some of which have dependencies.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+Open-source DPC++ installation
+------------------------------
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm.
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+-----------------------
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert SPIR-V back to LLVM IR.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: ```suggestion
dependency because PoCL needs to convert the SPIR-V DPC++ produces back to LLVM IR.
```
created_at: 2025-03-13T11:31:50Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+
+The installer can be run with different options, either via the GUI or command line.
+
+To install with GUI::
+
+    sh ./intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+The oneAPI Base Toolkit includes various components, some of which have dependencies.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+Open-source DPC++ installation
+------------------------------
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm.
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+-----------------------
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert SPIR-V back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version (Do not use it with PoCL - it is meant for internal use by DPC++).
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: ```suggestion
- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. It cannot be used with PoCL, it is meant for internal use by DPC++.
```
created_at: 2025-03-13T11:32:39Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+
+The installer can be run with different options, either via the GUI or command line.
+
+To install with GUI::
+
+    sh ./intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+The oneAPI Base Toolkit includes various components, some of which have dependencies.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+Open-source DPC++ installation
+------------------------------
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm.
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+-----------------------
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert SPIR-V back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version (Do not use it with PoCL - it is meant for internal use by DPC++).
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
+
+
+Compiling with DPC++ using PoCL as the backend
+----------------------------------------------
+If using proprietary DPC++, there are a few additional steps. Proprietary DPC++
+expects the Intel OpenCL runtime so we have to make PoCL appear as one::
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: ```suggestion
expects the Intel OpenCL runtime so we have to make PoCL fake itself as one::
```
created_at: 2025-03-13T11:33:43Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+
+The installer can be run with different options, either via the GUI or command line.
+
+To install with GUI::
+
+    sh ./intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+The oneAPI Base Toolkit includes various components, some of which have dependencies.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+Open-source DPC++ installation
+------------------------------
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm.
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+-----------------------
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert SPIR-V back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version (Do not use it with PoCL - it is meant for internal use by DPC++).
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
+
+
+Compiling with DPC++ using PoCL as the backend
+----------------------------------------------
+If using proprietary DPC++, there are a few additional steps. Proprietary DPC++
+expects the Intel OpenCL runtime so we have to make PoCL appear as one::
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: franz
body: IMO a more idiomatic English term would be: "pretend to be"
created_at: 2025-03-13T11:47:46Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Fixed.
created_at: 2025-03-13T15:03:34Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Rewrote this.
created_at: 2025-03-13T15:03:50Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Fixed.
created_at: 2025-03-13T15:24:20Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Fixed.
created_at: 2025-03-13T15:24:28Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Fixed.
created_at: 2025-03-13T15:24:37Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Done.
created_at: 2025-03-13T15:25:20Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+
+The installer can be run with different options, either via the GUI or command line.
+
+To install with GUI::
+
+    sh ./intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+The oneAPI Base Toolkit includes various components, some of which have dependencies.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+Open-source DPC++ installation
+------------------------------
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Yup
created_at: 2025-03-13T15:25:31Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+
+The installer can be run with different options, either via the GUI or command line.
+
+To install with GUI::
+
+    sh ./intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+The oneAPI Base Toolkit includes various components, some of which have dependencies.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+Open-source DPC++ installation
+------------------------------
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm.
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+-----------------------
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert SPIR-V back to LLVM IR.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Fixed.
created_at: 2025-03-13T15:27:54Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+
+The installer can be run with different options, either via the GUI or command line.
+
+To install with GUI::
+
+    sh ./intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+The oneAPI Base Toolkit includes various components, some of which have dependencies.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+Open-source DPC++ installation
+------------------------------
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm.
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+-----------------------
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert SPIR-V back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version (Do not use it with PoCL - it is meant for internal use by DPC++).
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Fixed.
created_at: 2025-03-13T15:29:59Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+
+The installer can be run with different options, either via the GUI or command line.
+
+To install with GUI::
+
+    sh ./intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
+
+The oneAPI Base Toolkit includes various components, some of which have dependencies.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+Open-source DPC++ installation
+------------------------------
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm.
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+-----------------------
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert SPIR-V back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version (Do not use it with PoCL - it is meant for internal use by DPC++).
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
+
+
+Compiling with DPC++ using PoCL as the backend
+----------------------------------------------
+If using proprietary DPC++, there are a few additional steps. Proprietary DPC++
+expects the Intel OpenCL runtime so we have to make PoCL appear as one::
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: I'm leaning to 'pretend' as well, faking is cheap.
created_at: 2025-03-13T15:31:09Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
+------------------------------------
+
+DPC++ is available with various bundles, but the oneAPI Base Toolkit is a safe bet:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+There are multiple ways to obtain the installer. For the offline GUI installer (check the website above for the latest version)::
+
+    wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/dfc4a434-838c-4450-a6fe-2fa903b75aa7/intel-oneapi-base-toolkit-2025.0.1.46_offline.sh
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Agree, changed it.
created_at: 2025-03-13T16:02:17Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: bashbaug
body: I generally don't recommend using `OCL_ICD_VENDORS` to "install" new ICDs unless you really know what you're doing, because this overrides the ICDs listed in `/etc/OpenCL/vendors` and is hence "subtractive".  Should we recommend using `OCL_ICD_FILENAMES` instead?  Or, even better, can this step be described in a general POCL doc, since this part isn't DPC++-specific?

Note also: `OCL_ICD_VENDORS` does not work on Windows.
created_at: 2025-03-13T16:04:31Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
+
+
+Compiling with DPC++ using PoCL as the backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If using proprietary DPC++, there are a few additional steps. Proprietary DPC++
+expects the Intel OpenCL runtime, so we need to make PoCL pretend to be one::
+
+    unset OCL_ICD_FILENAMES
+    export POCL_DRIVER_VERSION_OVERRIDE=2023.16.7.0.21_160000
+    export POCL_CPU_VENDOR_ID_OVERRIDE=32902
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: bashbaug
body: Instead of setting up POCL to masquerade as the CPU OpenCL runtime, could we describe how to setup [SYCL_DEVICE_ALLOWLIST](https://github.com/intel/llvm/blob/sycl/sycl/doc/EnvironmentVariables.md#sycl_device_allowlist) to allow POCL device in addition to other OpenCL implementations?
created_at: 2025-03-13T16:05:10Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: bashbaug
body: This is a longer-term comment and not something to fix in this PR, but food for thought:

This part about needing the right `llvm-spirv` seems like a brittle part of the process, so we should think whether we can make some impovements here.  Some ideas: add a suffix to `llvm-spirv` to indicate the version of LLVM it is built for, allowing for both e.g. `llvm-spirv-18` and `llvm-spirv-21` to be in the path at the same time.  Or, can POCL statically link with a library equivalent of `llvm-spirv`, so the right executable is not needed?
created_at: 2025-03-13T16:07:39Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,197 @@
+==========================================
+Using PoCL as the OpenCL backend for DPC++
+==========================================
+
+SYCL is programming model that enables single-source C++ development for
+heterogenous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, relying on lower-level implementations like OpenCL for device
+offloading.
+
+If the OpenCL backend is used, the SYCL runtime translates the SYCL API calls
+into corresponding OpenCL API calls and forwards them to the OpenCL runtime.
+
+DPC++ is Intel's implementation of SYCL, and the toolchain flow is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (Proprietary or open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Propietary oneAPI DPC++ installation
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: I'm stating their respective official names and using those in the subtitles. Other than that, I'm sticking with 'proprietary' and 'open-source' because it makes it easier to follow. Do you agree?
created_at: 2025-03-13T16:10:46Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
+
+
+Compiling with DPC++ using PoCL as the backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If using proprietary DPC++, there are a few additional steps. Proprietary DPC++
+expects the Intel OpenCL runtime, so we need to make PoCL pretend to be one::
+
+    unset OCL_ICD_FILENAMES
+    export POCL_DRIVER_VERSION_OVERRIDE=2023.16.7.0.21_160000
+    export POCL_CPU_VENDOR_ID_OVERRIDE=32902
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: Sounds better. I didn't know it's possible to expand the allowed list this way.
created_at: 2025-03-13T16:54:29Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: Does DPC++ use llvm-spirv for SPIR-V input or just for output? I mean, does this problem go away after it switches to the LLVM's SPIRV backend instead?
created_at: 2025-03-13T16:58:17Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: Pennycook
body: A reader may infer from the use of "safe" here that other ways of acquiring DPC++ are "unsafe". Maybe:

```suggestion
DPC++ is available in various bundles. Installing the oneAPI Base Toolkit is the simplest
way to install DPC++ and its dependencies.
```
created_at: 2025-03-14T10:54:48Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: Pennycook
body: ```suggestion
The oneAPI Base Toolkit includes various components, some of which are not needed to run
SYCL applications with PoCL.
```

Somebody might need them, they're just not needed here.
created_at: 2025-03-14T10:57:21Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: Pennycook
body: Nit: This might be a personal style preference, but I think parentheses imply that the statement is an unimportant aside. In this case, it's important that the reader pay attention to the fact this step needs to be repeated.

```suggestion
After installation, run the initialization script to set environment variables. Note that this must be done in every new shell session unless added to ``.bashrc``::

    source <path-to-oneapi-installation>/setvars.sh
```

Or, if the PoCL documentation is configured for admonitions, maybe even:

```suggestion
After installation, run the initialization script to set environment variables::

    source <path-to-oneapi-installation>/setvars.sh

.. important:: 
   This script must be run in every new shell session unless added to ``.bashrc``.
```
created_at: 2025-03-14T11:03:02Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: Pennycook
body: ```suggestion
    $ sycl-ls
```

I usually do something like this to distinguish between the command being run and its output.  If this doesn't match the convention used elsewhere in the PoCL documentation, you can ignore me.
created_at: 2025-03-14T11:03:20Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: Pennycook
body: ```suggestion
    $ icpx --version
```
created_at: 2025-03-14T11:03:29Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: Pennycook
body: ```suggestion
The sources for the open-source DPC++ compiler can be obtained from the `DPC++ repository <https://github.com/intel/llvm>`__.
```
created_at: 2025-03-14T11:03:44Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: Pennycook
body: I think this description is too long, and the most important information (i.e., which version of `llvm-spirv` somebody needs to install) is buried in the middle of it.

I recommend rewriting it similar to the below:
```suggestion
You must check out and build a version of ``llvm-spirv`` that corresponds to the LLVM version PoCL uses as its kernel compiler. For example, if the PoCL kernel compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.

.. note::
   DPC++ ships with its own ``llvm-spirv``, which is typically based on the latest release. However, this version is intended for internal usage by DPC++ and cannot be used by PoCL.
   
.. warning::
   Although the versions of ``llvm-spirv`` used by DPC++ and PoCL do not have to be an exact match, it is recommended to use versions that are reasonably close to each other.
```
created_at: 2025-03-14T11:16:05Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: Pennycook
body: > Or, even better, can this step be described in a general POCL doc, since this part isn't DPC++-specific?

If this step gets moved somewhere else, I think we should at least keep something here that acts as a pointer to that part of the documentation.  The default behavior of DPC++ (as I understand it) is to look for its own `libOpenCL.so` and ignore the ICDs completely, so somebody running SYCL on PoCL needs to know to pay close attention to which libraries and ICDs are being loaded.
created_at: 2025-03-14T11:18:44Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
+
+
+Compiling with DPC++ using PoCL as the backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If using proprietary DPC++, there are a few additional steps. Proprietary DPC++
+expects the Intel OpenCL runtime, so we need to make PoCL pretend to be one::
+
+    unset OCL_ICD_FILENAMES
+    export POCL_DRIVER_VERSION_OVERRIDE=2023.16.7.0.21_160000
+    export POCL_CPU_VENDOR_ID_OVERRIDE=32902
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: Pennycook
body: I think we should improve the documentation for `SYCL_DEVICE_ALLOWLIST` as well.  @bashbaug, do you know who designed/implemented that feature?

The documentation seems to suggest that the allow list needs all the fields, so my first test was a really complicated string:
```
SYCL_DEVICE_ALLOWLIST="BackendName:opencl,DeviceType:cpu,DeviceVendorId:0x10006,DriverVersion:{{version-number-including-a-git-hash}}"
```

It worked, but so does this:
```
SYCL_DEVICE_ALLOWLIST="DeviceVendorId:0x10006"
```

Surprisingly, even this works:
```
SYCL_DEVICE_ALLOWLIST=""
```

PoCL is only blocked if `SYCL_DEVICE_ALLOWLIST` isn't set at all, or if it's set to include a value that PoCL doesn't match.  So it is working, just not the way I would have expected.
created_at: 2025-03-14T12:14:31Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: It's fine with single line commandss, but with multiple lines it gets annoying as one cannot copy the lines directly to paste to the console due to the additional $s.
created_at: 2025-03-14T14:03:31Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: franz
body: > add a suffix to llvm-spirv to indicate the version of LLVM it is built

This is how Ubuntu/Debian ships their llvm-spirv binaries, and PoCL's CMake will search for `llvm-spirv-XYZ` preferably; but it also verifies that `<llvm-spirv-binary> --version` returns the same LLVM major as the libLLVM PoCL is built against.

> can POCL statically link with a library equivalent of llvm-spirv

Yes; unfortunately this doesn't work quite as well (on Ubuntu/Debian at least). The problem is that both headers & libLLVMSPIRV are in unversioned directories. This then causes bugs like #1824 because the both library & headers actually **are** LLVM-version dependent.
created_at: 2025-03-15T19:32:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Yep. Leaving it as is for consistency, since the PoCL documentation does not use it.
created_at: 2025-03-21T14:22:11Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Leaving as is for consistency.
created_at: 2025-03-21T14:24:25Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Yeah, good point!
created_at: 2025-03-21T14:31:57Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Good correction.
created_at: 2025-03-21T14:33:43Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: I agree.
created_at: 2025-03-21T14:37:04Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Yeah, I agree that general instructions on this would be beneficial. For now, I made a compromise and referred Ocl ICD loader instructions for the setup. Would it be ok to to open a new issue for this matter and handle it sometime soonish, or do you think it should be dealt with now @pjaaskel?
created_at: 2025-03-21T16:18:09Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
+
+
+Compiling with DPC++ using PoCL as the backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If using proprietary DPC++, there are a few additional steps. Proprietary DPC++
+expects the Intel OpenCL runtime, so we need to make PoCL pretend to be one::
+
+    unset OCL_ICD_FILENAMES
+    export POCL_DRIVER_VERSION_OVERRIDE=2023.16.7.0.21_160000
+    export POCL_CPU_VENDOR_ID_OVERRIDE=32902
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Yes, this is much more handier way to deal with the setup.
created_at: 2025-03-21T16:19:22Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Fixed.
created_at: 2025-03-21T16:19:39Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: tneval
body: Fixed.
created_at: 2025-03-21T16:19:47Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,202 @@
+.. _sycl_dpcpp:
+
+Using PoCL as the OpenCL backend for DPC++
+------------------------------------------
+
+SYCL is a programming model that enables single-source C++ development for
+heterogeneous computing. Compared to OpenCL, SYCL operates at a higher level
+of abstraction, and implementations can use varying backends
+for device offloading (e.g., OpenCL, Level Zero, and CUDA). It is worth noting
+that a SYCL implementation is not required to support OpenCL as a backend.
+
+DPC++ is Intel's implementation of SYCL that supports OpenCL. When the OpenCL backend
+is utilized, the DPC++ runtime translates SYCL API calls into corresponding OpenCL
+API calls and forwards them to the OpenCL runtime.
+
+The toolchain flow, when PoCL is used as the OpenCL backend for DPC++, is as follows:
+
+- The DPC++ Clang++ frontend compiles the SYCL kernel into LLVM IR.
+- ``llvm-spirv`` is used to translate LLVM IR to SPIR-V.
+- SPIR-V is ingested by PoCL, where it is translated back into LLVM IR.
+- PoCL applies additional transformations to the LLVM IR.
+- If using a CPU driver, PoCL leverages ``llc`` (LLVM backend) to lower the kernel to machine code.
+
+It should be pointed out that there are two versions of DPC++:
+
+- the **Intel(R) oneAPI DPC++/C++ Compiler**
+- the **oneAPI DPC++/C++ Compiler**.
+
+The former is proprietary and thus distributed in binary form, whereas the latter is
+open-source.
+
+This page covers the following steps:
+
+- How to obtain, install, and set up DPC++ (the proprietary or the open-source version)
+- How to build PoCL to support DPC++.
+- Verification with an example program.
+
+
+Intel(R) oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DPC++ is available in various bundles, but the oneAPI Base Toolkit is a safe bet.
+
+Choose a suitable installer from:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
+
+Run the installer. The page above provides corresponding instructions for the selected installer.
+Pay attention to the default installation path and choose a suitable one if necessary.
+
+The oneAPI Base Toolkit includes various components, some of which are not needed.
+
+For a minimal setup, pick:
+
+- Intel oneAPI DPC++ Library
+- Intel oneAPI DPC++/C++ compiler
+- Intel Distribution for GDB (Required by the compiler)
+- Intel oneAPI Threading Building Blocks (Required by the compiler)
+- Intel oneAPI Math Kernel Library (Useful, but not required)
+
+After installation, run the initialization script to set environment variables (This must be done in every new shell session unless added to ``.bashrc``)::
+
+    source <path-to-oneapi-installation>/setvars.sh
+
+Now, DPC++ should be set up. This can be verified by checking the available SYCL backends (In this example, Intel OpenCL was detected). ::
+
+    sycl-ls
+    [opencl:cpu][opencl:0] Intel(R) OpenCL, AMD Ryzen Threadripper 2990WX 32-Core Processor OpenCL 3.0 (Build 0) [2024.18.12.0.05_160000]
+    [opencl:gpu][opencl:1] Intel(R) OpenCL Graphics, Intel(R) Arc(TM) A770 Graphics OpenCL 3.0 NEO  [23.43.027642]
+
+
+The initialization script also adds the compiler to the ``PATH``::
+
+    icpx --version
+    Intel(R) oneAPI DPC++/C++ Compiler 2025.0.4 (2025.0.4.20241205)
+
+
+oneAPI DPC++/C++ Compiler installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The sources for the open-source DPC++ compiler can be obtained from `DPC++ repository <https://github.com/intel/llvm>`__.
+
+Official detailed instructions can be found `here <https://intel.github.io/llvm-docs/GetStartedGuide.html#build-dpc-toolchain>`__.
+The build process is managed using two Python scripts: ``configure.py`` and ``compile.py``, which handle most of the heavy lifting.
+The ``configure.py`` is essentially a wrapper for **CMake**, so checking its contents can provide further details.
+
+For a basic setup, run::
+
+    git clone git@github.com:intel/llvm
+    cd llvm
+    python3 ./buildbot/configure.py -o <path-to-dpcpp-installation>
+    python3 ./buildbot/compile.py -o <path-to-dpcpp-installation> -j <number-of-threads>
+
+After building, export the compiler and SYCL runtime library paths::
+
+    export PATH=<path-to-dpcpp-installation>/bin:$PATH
+    export LD_LIBRARY_PATH=<path-to-dpcpp-installation>/lib:$LD_LIBRARY_PATH
+
+**Note:** The open-source DPC++ compiler driver is ``clang++``, not ``icpx``.
+
+::
+
+    which clang++
+    <path-to-dpcpp-installation>/bin/clang++
+
+
+Building PoCL for DPC++
+~~~~~~~~~~~~~~~~~~~~~~~
+PoCL doesn't normally require ``llvm-spirv``, but in this case, it is a strict
+dependency because PoCL needs to convert the SPIR-V produced by DPC++ back to LLVM IR.
+
+Pay attention to LLVM and ``llvm-spirv`` versions:
+
+- DPC++ includes its own ``llvm-spirv`` which is typically the latest version. However, it cannot be used with PoCL, as it is meant for internal use by DPC++.
+- You need a separate build of ``llvm-spirv`` checked out from the branch that corresponds to the LLVM version PoCL uses as its kernel compiler.
+- These two versions of ``llvm-spirv`` should be reasonably close to each other, but they do not have to be an exact match.
+
+For example, if DPC++ ``llvm-spirv`` is based on **LLVM 21**, and the PoCL kernel
+compiler uses **LLVM 18**, then ``llvm-spirv`` should be checked out from the 'llvm_release_180' branch.
+
+
+Example PoCL build::
+
+    git clone git@github.com:pocl/pocl.git
+    cd pocl
+    mkdir build && cd build
+    cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation-directory> -DLLVM_SPIRV=<path-to-llvm-spirv> -DWITH_LLVM_CONFIG=<path-to-llvm-config>
+
+The final step is to make PoCL visible to ICD loader::
+
+    export OCL_ICD_VENDORS=<path-to-pocl-installation>/etc/OpenCL/vendors
path: doc/sphinx/source/sycl_dpcpp.rst
user: login: pjaaskel
body: We can improve later.
created_at: 2025-03-24T07:48:39Z
author_association: MEMBER

PR comments:
user: login: pjaaskel
created_at: 2025-03-13T11:35:15Z
body: Looks good. Some feedback attached.

author_association: MEMBER
user: login: pjaaskel
created_at: 2025-03-24T07:52:26Z
body: > Looks good overall. Was just wondering if we should merge this somehow with the ARM SYCL document, but that can be done in a separate PR

@tneval can you check if the ARM SYCL document is now relevant as yours is more general and ARM should be just another CPU target?
author_association: MEMBER
user: login: tneval
created_at: 2025-03-24T08:37:47Z
body: > 
> @tneval can you check if the ARM SYCL document is now relevant as yours is more general and ARM should be just another CPU target?

The new documentation should work for ARM as well, so the old one is more or less redundant now.
Maybe the 'troubleshooting' section could be moved to the new document, and the 'known issues' part - if still relevant (I need to check this) - could be included as well.
author_association: COLLABORATOR