DPC++ Runtime
Runtime libraries for oneAPI DPC++
level_zero.hpp
Go to the documentation of this file.
1 //==--------- level_zero.hpp - SYCL Level-Zero backend ---------------------==//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #pragma once
10 
11 #include <sycl/async_handler.hpp> // for async_han...
12 #include <sycl/backend.hpp> // for backend_i...
13 #include <sycl/backend_types.hpp> // for backend
14 #include <sycl/buffer.hpp> // for buffer_al...
15 #include <sycl/context.hpp> // for context
16 #include <sycl/detail/backend_traits.hpp> // for interop
17 #include <sycl/detail/backend_traits_level_zero.hpp> // for ze_comman...
18 #include <sycl/detail/defines_elementary.hpp> // for __SYCL_DE...
19 #include <sycl/detail/export.hpp> // for __SYCL_EX...
20 #include <sycl/detail/impl_utils.hpp> // for createSyc...
21 #include <sycl/detail/pi.h> // for pi_native...
22 #include <sycl/detail/pi.hpp> // for cast
23 #include <sycl/device.hpp> // for device
24 #include <sycl/event.hpp> // for event
26 #include <sycl/ext/oneapi/backend/level_zero_ownership.hpp> // for ownership
27 #include <sycl/image.hpp> // for image
28 #include <sycl/kernel.hpp> // for kernel
29 #include <sycl/kernel_bundle.hpp> // for kernel_bu...
30 #include <sycl/kernel_bundle_enums.hpp> // for bundle_state
31 #include <sycl/platform.hpp> // for platform
32 #include <sycl/properties/image_properties.hpp> // for image
33 #include <sycl/property_list.hpp> // for property_...
34 #include <sycl/queue.hpp> // for queue
35 
36 #include <memory> // for shared_ptr
37 #include <stdint.h> // for int32_t
38 #include <type_traits> // for enable_if_t
39 #include <variant> // for get_if
40 #include <vector> // for vector
41 
42 namespace sycl {
43 inline namespace _V1 {
44 namespace ext::oneapi::level_zero {
45 // Implementation of various "make" functions resides in libsycl.so and thus
46 // their interface needs to be backend agnostic.
47 // TODO: remove/merge with similar functions in sycl::detail
48 __SYCL_EXPORT platform make_platform(pi_native_handle NativeHandle);
49 __SYCL_EXPORT device make_device(const platform &Platform,
50  pi_native_handle NativeHandle);
51 __SYCL_EXPORT context make_context(const std::vector<device> &DeviceList,
52  pi_native_handle NativeHandle,
53  bool keep_ownership = false);
54 __SYCL_EXPORT queue make_queue(const context &Context, const device &Device,
55  pi_native_handle InteropHandle,
56  bool IsImmCmdList, bool keep_ownership,
57  const property_list &Properties);
58 __SYCL_EXPORT event make_event(const context &Context,
59  pi_native_handle InteropHandle,
60  bool keep_ownership = false);
61 
62 // Construction of SYCL platform.
63 template <typename T,
64  typename std::enable_if_t<std::is_same_v<T, platform>> * = nullptr>
65 __SYCL_DEPRECATED("Use SYCL 2020 sycl::make_platform free function")
66 T make(typename sycl::detail::interop<backend::ext_oneapi_level_zero, T>::type
67  Interop) {
68  return make_platform(reinterpret_cast<pi_native_handle>(Interop));
69 }
70 
71 // Construction of SYCL device.
72 template <typename T,
73  typename std::enable_if_t<std::is_same_v<T, device>> * = nullptr>
74 __SYCL_DEPRECATED("Use SYCL 2020 sycl::make_device free function")
75 T make(const platform &Platform,
76  typename sycl::detail::interop<backend::ext_oneapi_level_zero, T>::type
77  Interop) {
78  return make_device(Platform, reinterpret_cast<pi_native_handle>(Interop));
79 }
80 
90 template <typename T, std::enable_if_t<std::is_same_v<T, context>> * = nullptr>
91 __SYCL_DEPRECATED("Use SYCL 2020 sycl::make_context free function")
92 T make(const std::vector<device> &DeviceList,
93  typename sycl::detail::interop<backend::ext_oneapi_level_zero, T>::type
94  Interop,
95  ownership Ownership = ownership::transfer) {
96  return make_context(DeviceList,
97  sycl::detail::pi::cast<pi_native_handle>(Interop),
98  Ownership == ownership::keep);
99 }
100 
101 // Construction of SYCL event.
102 template <typename T,
103  typename std::enable_if_t<std::is_same_v<T, event>> * = nullptr>
104 __SYCL_DEPRECATED("Use SYCL 2020 sycl::make_event free function")
105 T make(const context &Context,
106  typename sycl::detail::interop<backend::ext_oneapi_level_zero, T>::type
107  Interop,
108  ownership Ownership = ownership::transfer) {
109  return make_event(Context, reinterpret_cast<pi_native_handle>(Interop),
110  Ownership == ownership::keep);
111 }
112 
113 } // namespace ext::oneapi::level_zero
114 
115 // Specialization of sycl::make_context for Level-Zero backend.
116 template <>
117 inline context make_context<backend::ext_oneapi_level_zero>(
119  &BackendObject,
120  const async_handler &Handler) {
121  (void)Handler;
123  BackendObject.DeviceList,
124  detail::pi::cast<pi_native_handle>(BackendObject.NativeHandle),
125  BackendObject.Ownership == ext::oneapi::level_zero::ownership::keep);
126 }
127 
128 // Specialization of sycl::make_queue for Level-Zero backend.
129 template <>
130 inline queue make_queue<backend::ext_oneapi_level_zero>(
132  const context &TargetContext, const async_handler Handler) {
133  (void)Handler;
134  const device Device = device{BackendObject.Device};
135  bool IsImmCmdList = std::holds_alternative<ze_command_list_handle_t>(
136  BackendObject.NativeHandle);
137  pi_native_handle Handle = IsImmCmdList
138  ? reinterpret_cast<pi_native_handle>(
139  *(std::get_if<ze_command_list_handle_t>(
140  &BackendObject.NativeHandle)))
141  : reinterpret_cast<pi_native_handle>(
142  *(std::get_if<ze_command_queue_handle_t>(
143  &BackendObject.NativeHandle)));
145  TargetContext, Device, Handle, IsImmCmdList,
146  BackendObject.Ownership == ext::oneapi::level_zero::ownership::keep,
147  BackendObject.Properties);
148 }
149 
150 // Specialization of sycl::get_native for Level-Zero backend.
151 template <>
152 inline auto get_native<backend::ext_oneapi_level_zero, queue>(const queue &Obj)
154  int32_t IsImmCmdList;
155  pi_native_handle Handle = Obj.getNative(IsImmCmdList);
156  return IsImmCmdList
159  queue>{reinterpret_cast<ze_command_list_handle_t>(Handle)}
161  reinterpret_cast<ze_command_queue_handle_t>(Handle)};
162 }
163 
164 // Specialization of sycl::make_event for Level-Zero backend.
165 template <>
166 inline event make_event<backend::ext_oneapi_level_zero>(
168  const context &TargetContext) {
170  TargetContext,
171  detail::pi::cast<pi_native_handle>(BackendObject.NativeHandle),
172  BackendObject.Ownership == ext::oneapi::level_zero::ownership::keep);
173 }
174 
175 // Specialization of sycl::make_kernel_bundle for Level-Zero backend.
176 template <>
177 inline kernel_bundle<bundle_state::executable>
178 make_kernel_bundle<backend::ext_oneapi_level_zero, bundle_state::executable>(
180  kernel_bundle<bundle_state::executable>>
181  &BackendObject,
182  const context &TargetContext) {
183  std::shared_ptr<detail::kernel_bundle_impl> KBImpl =
185  detail::pi::cast<pi_native_handle>(BackendObject.NativeHandle),
186  TargetContext,
187  BackendObject.Ownership == ext::oneapi::level_zero::ownership::keep,
189  return detail::createSyclObjFromImpl<kernel_bundle<bundle_state::executable>>(
190  KBImpl);
191 }
192 
193 // Specialization of sycl::make_kernel for Level-Zero backend.
194 template <>
195 inline kernel make_kernel<backend::ext_oneapi_level_zero>(
197  &BackendObject,
198  const context &TargetContext) {
199  return detail::make_kernel(
200  TargetContext, BackendObject.KernelBundle,
201  detail::pi::cast<pi_native_handle>(BackendObject.NativeHandle),
202  BackendObject.Ownership == ext::oneapi::level_zero::ownership::keep,
204 }
205 
206 // Specialization of sycl::make_buffer with event for Level-Zero backend.
207 template <backend Backend, typename T, int Dimensions = 1,
208  typename AllocatorT = buffer_allocator<std::remove_const_t<T>>>
209 std::enable_if_t<Backend == backend::ext_oneapi_level_zero,
210  buffer<T, Dimensions, AllocatorT>>
213  buffer<T, Dimensions, AllocatorT>> &BackendObject,
214  const context &TargetContext, event AvailableEvent) {
215  return detail::make_buffer_helper<T, Dimensions, AllocatorT>(
216  detail::pi::cast<pi_native_handle>(BackendObject.NativeHandle),
217  TargetContext, AvailableEvent,
218  !(BackendObject.Ownership == ext::oneapi::level_zero::ownership::keep));
219 }
220 
221 // Specialization of sycl::make_buffer for Level-Zero backend.
222 template <backend Backend, typename T, int Dimensions = 1,
223  typename AllocatorT = buffer_allocator<std::remove_const_t<T>>>
224 std::enable_if_t<Backend == backend::ext_oneapi_level_zero,
225  buffer<T, Dimensions, AllocatorT>>
228  buffer<T, Dimensions, AllocatorT>> &BackendObject,
229  const context &TargetContext) {
230  return detail::make_buffer_helper<T, Dimensions, AllocatorT>(
231  detail::pi::cast<pi_native_handle>(BackendObject.NativeHandle),
232  TargetContext, event{},
233  !(BackendObject.Ownership == ext::oneapi::level_zero::ownership::keep));
234 }
235 
236 // Specialization of sycl::make_image for Level-Zero backend.
237 template <backend Backend, int Dimensions = 1,
238  typename AllocatorT = image_allocator>
239 std::enable_if_t<Backend == backend::ext_oneapi_level_zero,
240  image<Dimensions, AllocatorT>>
242  &BackendObject,
243  const context &TargetContext, event AvailableEvent) {
244 
245  bool OwnNativeHandle =
246  (BackendObject.Ownership == ext::oneapi::level_zero::ownership::transfer);
247 
249  detail::pi::cast<pi_native_handle>(BackendObject.ZeImageHandle),
250  TargetContext, AvailableEvent, BackendObject.ChanOrder,
251  BackendObject.ChanType, OwnNativeHandle, BackendObject.Range);
252 }
253 
254 namespace __SYCL2020_DEPRECATED("use 'ext::oneapi::level_zero' instead")
255  level_zero {
256 using namespace ext::oneapi::level_zero;
257 }
258 
259 } // namespace _V1
260 } // namespace sycl
struct _ze_command_queue_handle_t * ze_command_queue_handle_t
struct _ze_command_list_handle_t * ze_command_list_handle_t
Defines a shared array that can be used by kernels in queues.
Definition: buffer.hpp:169
The context class represents a SYCL context on which kernel functions may be executed.
Definition: context.hpp:51
The SYCL device class encapsulates a single SYCL device on which kernels may be executed.
Definition: device.hpp:66
An event object can be used to synchronize memory transfers, enqueues of kernels and signaling barrie...
Definition: event.hpp:44
Defines a shared image data.
Definition: image.hpp:443
Provides an abstraction of a SYCL kernel.
Definition: kernel.hpp:79
Encapsulates a SYCL platform on which kernels may be executed.
Definition: platform.hpp:109
Objects of the property_list class are containers for the SYCL properties.
Encapsulates a single SYCL queue which schedules kernels on a SYCL device.
Definition: queue.hpp:119
#define __SYCL_DEPRECATED(message)
kernel make_kernel(pi_native_handle NativeHandle, const context &TargetContext, backend Backend)
Definition: backend.cpp:295
std::shared_ptr< detail::kernel_bundle_impl > make_kernel_bundle(pi_native_handle NativeHandle, const context &TargetContext, bundle_state State, backend Backend)
Definition: backend.cpp:247
platform make_platform(pi_native_handle NativeHandle)
Definition: level_zero.cpp:23
context make_context(const std::vector< device > &DeviceList, pi_native_handle NativeHandle, bool keep_ownership=false)
Definition: level_zero.cpp:44
T make(typename sycl::detail::interop< backend::ext_oneapi_level_zero, T >::type Interop)
Definition: level_zero.hpp:66
event make_event(const context &Context, pi_native_handle InteropHandle, bool keep_ownership=false)
Definition: level_zero.cpp:77
device make_device(const platform &Platform, pi_native_handle NativeHandle)
Definition: level_zero.cpp:29
queue make_queue(const context &Context, const device &Device, pi_native_handle InteropHandle, bool IsImmCmdList, bool keep_ownership, const property_list &Properties)
Definition: level_zero.cpp:65
std::uint8_t instead
Definition: aliases.hpp:93
class __SYCL_EBO __SYCL_SPECIAL_CLASS __SYCL_TYPE(local_accessor) local_accessor class __SYCL_EBO __SYCL_SPECIAL_CLASS Dimensions
Definition: accessor.hpp:3233
signed char __SYCL2020_DEPRECATED
Definition: aliases.hpp:94
typename backend_traits< Backend >::template return_type< SyclType > backend_return_t
Definition: backend.hpp:87
std::enable_if_t< detail::InteropFeatureSupportMap< Backend >::MakeImage==true &&Backend !=backend::ext_oneapi_level_zero, image< Dimensions, AllocatorT > > make_image(const typename backend_traits< Backend >::template input_type< image< Dimensions, AllocatorT >> &BackendObject, const context &TargetContext, event AvailableEvent={})
Definition: backend.hpp:384
std::function< void(sycl::exception_list)> async_handler
detail::aligned_allocator< byte > image_allocator
Definition: image.hpp:109
std::enable_if_t< detail::InteropFeatureSupportMap< Backend >::MakeBuffer==true &&Backend !=backend::ext_oneapi_level_zero, buffer< T, Dimensions, AllocatorT > > make_buffer(const typename backend_traits< Backend >::template input_type< buffer< T, Dimensions, AllocatorT >> &BackendObject, const context &TargetContext, event AvailableEvent={})
Definition: backend.hpp:371
typename backend_traits< Backend >::template input_type< SyclType > backend_input_t
Definition: backend.hpp:83
Definition: access.hpp:18
uintptr_t pi_native_handle
Definition: pi.h:209
C++ wrapper of extern "C" PI interfaces.