1============================================= 2SYCL Compiler and Runtime architecture design 3============================================= 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11This document describes the architecture of the SYCL compiler and runtime 12library. More details are provided in 13`external document <https://github.com/intel/llvm/blob/sycl/sycl/doc/CompilerAndRuntimeDesign.md>`_\ , 14which are going to be added to clang documentation in the future. 15 16Address space handling 17====================== 18 19The SYCL specification represents pointers to disjoint memory regions using C++ 20wrapper classes on an accelerator to enable compilation with a standard C++ 21toolchain and a SYCL compiler toolchain. Section 3.8.2 of SYCL 2020 22specification defines 23`memory model <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_device_memory_model>`_\ , 24section 4.7.7 - `address space classes <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_address_space_classes>`_ 25and section 5.9 covers `address space deduction <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_address_space_deduction>`_. 26The SYCL specification allows two modes of address space deduction: "generic as 27default address space" (see section 5.9.3) and "inferred address space" (see 28section 5.9.4). Current implementation supports only "generic as default address 29space" mode. 30 31SYCL borrows its memory model from OpenCL however SYCL doesn't perform 32the address space qualifier inference as detailed in 33`OpenCL C v3.0 6.7.8 <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_C.html#addr-spaces-inference>`_. 34 35The default address space is "generic-memory", which is a virtual address space 36that overlaps the global, local, and private address spaces. SYCL mode enables 37following conversions: 38 39- explicit conversions to/from the default address space from/to the address 40 space-attributed type 41- implicit conversions from the address space-attributed type to the default 42 address space 43- explicit conversions to/from the global address space from/to the 44 ``__attribute__((opencl_global_device))`` or 45 ``__attribute__((opencl_global_host))`` address space-attributed type 46- implicit conversions from the ``__attribute__((opencl_global_device))`` or 47 ``__attribute__((opencl_global_host))`` address space-attributed type to the 48 global address space 49 50All named address spaces are disjoint and sub-sets of default address space. 51 52The SPIR target allocates SYCL namespace scope variables in the global address 53space. 54 55Pointers to default address space should get lowered into a pointer to a generic 56address space (or flat to reuse more general terminology). But depending on the 57allocation context, the default address space of a non-pointer type is assigned 58to a specific address space. This is described in 59`common address space deduction rules <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#subsec:commonAddressSpace>`_ 60section. 61 62This is also in line with the behaviour of CUDA (`small example 63<https://godbolt.org/z/veqTfo9PK>`_). 64 65``multi_ptr`` class implementation example: 66 67.. code-block:: C++ 68 69 // check that SYCL mode is ON and we can use non-standard decorations 70 #if defined(__SYCL_DEVICE_ONLY__) 71 // GPU/accelerator implementation 72 template <typename T, address_space AS> class multi_ptr { 73 // DecoratedType applies corresponding address space attribute to the type T 74 // DecoratedType<T, global_space>::type == "__attribute__((opencl_global)) T" 75 // See sycl/include/CL/sycl/access/access.hpp for more details 76 using pointer_t = typename DecoratedType<T, AS>::type *; 77 78 pointer_t m_Pointer; 79 public: 80 pointer_t get() { return m_Pointer; } 81 T& operator* () { return *reinterpret_cast<T*>(m_Pointer); } 82 } 83 #else 84 // CPU/host implementation 85 template <typename T, address_space AS> class multi_ptr { 86 T *m_Pointer; // regular undecorated pointer 87 public: 88 T *get() { return m_Pointer; } 89 T& operator* () { return *m_Pointer; } 90 } 91 #endif 92 93Depending on the compiler mode, ``multi_ptr`` will either decorate its internal 94data with the address space attribute or not. 95 96To utilize clang's existing functionality, we reuse the following OpenCL address 97space attributes for pointers: 98 99.. list-table:: 100 :header-rows: 1 101 102 * - Address space attribute 103 - SYCL address_space enumeration 104 * - ``__attribute__((opencl_global))`` 105 - global_space, constant_space 106 * - ``__attribute__((opencl_global_device))`` 107 - global_space 108 * - ``__attribute__((opencl_global_host))`` 109 - global_space 110 * - ``__attribute__((opencl_local))`` 111 - local_space 112 * - ``__attribute__((opencl_private))`` 113 - private_space 114 115 116.. code-block:: C++ 117 118 //TODO: add support for __attribute__((opencl_global_host)) and __attribute__((opencl_global_device)). 119 120