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