DPC++ Runtime
Runtime libraries for oneAPI DPC++
pi.hpp
Go to the documentation of this file.
1 //==---------- pi.hpp - Plugin Interface for SYCL RT -----------------------==//
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 
13 
14 #pragma once
15 
16 #include <sycl/backend_types.hpp> // for backend
17 #include <sycl/detail/export.hpp> // for __SYCL_EXPORT
18 #include <sycl/detail/os_util.hpp> // for __SYCL_RT_OS_LINUX
19 #include <sycl/detail/pi.h> // for piContextCreate, piContextGetInfo
20 
21 #include <cstdint> // for uint64_t, uint32_t
22 #include <memory> // for shared_ptr
23 #include <stddef.h> // for size_t
24 #include <string> // for char_traits, string
25 #include <type_traits> // for false_type, true_type
26 #include <vector> // for vector
27 
28 #ifdef XPTI_ENABLE_INSTRUMENTATION
29 // Forward declarations
30 namespace xpti {
31 struct trace_event_data_t;
32 }
33 #endif
34 
35 namespace sycl {
36 inline namespace _V1 {
37 
38 class context;
39 
40 namespace detail {
41 
42 enum class PiApiKind {
43 #define _PI_API(api) api,
44 #include <sycl/detail/pi.def>
45 };
46 class plugin;
47 using PluginPtr = std::shared_ptr<plugin>;
48 
49 template <sycl::backend BE>
50 __SYCL_EXPORT void *getPluginOpaqueData(void *opaquedata_arg);
51 
52 namespace pi {
53 
54 // The SYCL_PI_TRACE sets what we will trace.
55 // This is a bit-mask of various things we'd want to trace.
56 enum TraceLevel {
59  PI_TRACE_ALL = -1
60 };
61 
62 // Return true if we want to trace PI related activities.
63 bool trace(TraceLevel level);
64 
65 #ifdef __SYCL_RT_OS_WINDOWS
66 // these same constants are used by pi_win_proxy_loader.dll
67 // if a plugin is added here, add it there as well.
68 #ifdef _MSC_VER
69 #define __SYCL_OPENCL_PLUGIN_NAME "pi_opencl.dll"
70 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "pi_level_zero.dll"
71 #define __SYCL_CUDA_PLUGIN_NAME "pi_cuda.dll"
72 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "pi_esimd_emulator.dll"
73 #define __SYCL_HIP_PLUGIN_NAME "pi_hip.dll"
74 #define __SYCL_UR_PLUGIN_NAME "pi_unified_runtime.dll"
75 #define __SYCL_NATIVE_CPU_PLUGIN_NAME "pi_native_cpu.dll"
76 #else
77 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.dll"
78 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.dll"
79 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.dll"
80 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.dll"
81 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dll"
82 #define __SYCL_UR_PLUGIN_NAME "libpi_unified_runtime.dll"
83 #define __SYCL_NATIVE_CPU_PLUGIN_NAME "libpi_native_cpu.dll"
84 #endif
85 #elif defined(__SYCL_RT_OS_LINUX)
86 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.so"
87 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.so"
88 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.so"
89 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.so"
90 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.so"
91 #define __SYCL_UR_PLUGIN_NAME "libpi_unified_runtime.so"
92 #define __SYCL_NATIVE_CPU_PLUGIN_NAME "libpi_native_cpu.so"
93 #elif defined(__SYCL_RT_OS_DARWIN)
94 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.dylib"
95 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.dylib"
96 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.dylib"
97 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.dylib"
98 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dylib"
99 #define __SYCL_UR_PLUGIN_NAME "libpi_unified_runtime.dylib"
100 #define __SYCL_NATIVE_CPU_PLUGIN_NAME "libpi_native_cpu.dylib"
101 #else
102 #error "Unsupported OS"
103 #endif
104 
105 // Report error and no return (keeps compiler happy about no return statements).
106 [[noreturn]] __SYCL_EXPORT void die(const char *Message);
107 
108 __SYCL_EXPORT void assertion(bool Condition, const char *Message = nullptr);
109 
124 using PiMem = ::pi_mem;
153 
154 __SYCL_EXPORT void contextSetExtendedDeleter(const sycl::context &constext,
156  void *user_data);
157 
158 // Function to load a shared library
159 // Implementation is OS dependent
160 void *loadOsLibrary(const std::string &Library);
161 
162 // Function to unload a shared library
163 // Implementation is OS dependent (see posix-pi.cpp and windows-pi.cpp)
164 int unloadOsLibrary(void *Library);
165 
166 // Function to load the shared plugin library
167 // On Windows, this will have been pre-loaded by proxy loader.
168 // Implementation is OS dependent.
169 void *loadOsPluginLibrary(const std::string &Library);
170 
171 // Function to unload the shared plugin library
172 // Implementation is OS dependent (see posix-pi.cpp and windows-pi.cpp)
173 int unloadOsPluginLibrary(void *Library);
174 
175 // OS agnostic function to unload the shared library
176 int unloadPlugin(void *Library);
177 
178 // Function to get Address of a symbol defined in the shared
179 // library, implementation is OS dependent.
180 void *getOsLibraryFuncAddress(void *Library, const std::string &FunctionName);
181 
182 // Get a string representing a _pi_platform_info enum
183 std::string platformInfoToString(pi_platform_info info);
184 
185 // Want all the needed casts be explicit, do not define conversion operators.
186 template <class To, class From> To cast(From value);
187 
188 // Holds the PluginInformation for the plugin that is bound.
189 // Currently a global variable is used to store OpenCL plugin information to be
190 // used with SYCL Interoperability Constructors.
191 // TODO: GlobalPlugin does not seem to be needed anymore. Consider removing it!
192 extern std::shared_ptr<plugin> GlobalPlugin;
193 
194 // Performs PI one-time initialization.
195 std::vector<PluginPtr> &initialize();
196 
197 // Get the plugin serving given backend.
198 template <backend BE> __SYCL_EXPORT const PluginPtr &getPlugin();
199 
200 // Utility Functions to get Function Name for a PI Api.
201 template <PiApiKind PiApiOffset> struct PiFuncInfo {};
202 
203 #define _PI_API(api) \
204  template <> struct PiFuncInfo<PiApiKind::api> { \
205  using FuncPtrT = decltype(&::api); \
206  inline const char *getFuncName() { return #api; } \
207  inline FuncPtrT getFuncPtr(PiPlugin MPlugin) { \
208  return MPlugin.PiFunctionTable.api; \
209  } \
210  };
211 #include <sycl/detail/pi.def>
212 
217 uint64_t emitFunctionBeginTrace(const char *FName);
218 
223 void emitFunctionEndTrace(uint64_t CorrelationID, const char *FName);
224 
231 uint64_t emitFunctionWithArgsBeginTrace(uint32_t FuncID, const char *FName,
232  unsigned char *ArgsData,
233  pi_plugin Plugin);
234 
244 void emitFunctionWithArgsEndTrace(uint64_t CorrelationID, uint32_t FuncID,
245  const char *FName, unsigned char *ArgsData,
246  pi_result Result, pi_plugin Plugin);
247 
250 PiDeviceBinaryType getBinaryImageFormat(const unsigned char *ImgData,
251  size_t ImgSize);
252 
253 } // namespace pi
254 
255 // Workaround for build with GCC 5.x
256 // An explicit specialization shall be declared in the namespace block.
257 // Having namespace as part of template name is not supported by GCC
258 // older than 7.x.
259 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56480
260 namespace pi {
261 // Want all the needed casts be explicit, do not define conversion
262 // operators.
263 template <class To, class From> inline To cast(From value) {
264  // TODO: see if more sanity checks are possible.
265  sycl::detail::pi::assertion((sizeof(From) == sizeof(To)),
266  "assert: cast failed size check");
267  return (To)(value);
268 }
269 
270 // Helper traits for identifying std::vector with arbitrary element type.
271 template <typename T> struct IsStdVector : std::false_type {};
272 template <typename T> struct IsStdVector<std::vector<T>> : std::true_type {};
273 
274 // Overload for vectors that applies the cast to all elements. This
275 // creates a new vector.
276 template <class To, class FromE> To cast(std::vector<FromE> Values) {
277  static_assert(IsStdVector<To>::value, "Return type must be a vector.");
278  To ResultVec;
279  ResultVec.reserve(Values.size());
280  for (FromE &Val : Values)
281  ResultVec.push_back(cast<typename To::value_type>(Val));
282  return ResultVec;
283 }
284 
285 } // namespace pi
286 } // namespace detail
287 
288 } // namespace _V1
289 } // namespace sycl
290 
291 #undef _PI_API
The context class represents a SYCL context on which kernel functions may be executed.
Definition: context.hpp:50
const PluginPtr & getPlugin()
Definition: pi.cpp:498
void contextSetExtendedDeleter(const sycl::context &constext, pi_context_extended_deleter func, void *user_data)
Definition: pi.cpp:193
void emitFunctionEndTrace(uint64_t CorrelationID, const char *FName)
Emits an XPTI trace after the PI API call has been made.
Definition: pi.cpp:127
int unloadOsLibrary(void *Library)
Definition: posix_pi.cpp:37
void * loadOsPluginLibrary(const std::string &Library)
Definition: posix_pi.cpp:33
std::vector< PluginPtr > & initialize()
Definition: pi.cpp:372
::pi_image_mem_handle PiImageMemHandle
Definition: pi.hpp:145
void die(const char *Message)
Definition: pi.cpp:526
::pi_mem_flags PiMemFlags
Definition: pi.hpp:125
uint64_t emitFunctionBeginTrace(const char *FName)
Emits an XPTI trace before a PI API call is made.
Definition: pi.cpp:82
::pi_interop_mem_handle PiInteropMemHandle
Definition: pi.hpp:147
void assertion(bool Condition, const char *Message=nullptr)
Definition: pi.cpp:531
PiProgram cast(cl_program)=delete
PiDeviceBinaryType getBinaryImageFormat(const unsigned char *ImgData, size_t ImgSize)
Tries to determine the device binary image foramat.
Definition: pi.cpp:626
bool trace(TraceLevel level)
Definition: pi.cpp:366
uint64_t emitFunctionWithArgsBeginTrace(uint32_t FuncID, const char *FName, unsigned char *ArgsData, pi_plugin Plugin)
Notifies XPTI subscribers about PI function calls and packs call arguments.
Definition: pi.cpp:143
void * loadOsLibrary(const std::string &Library)
Definition: posix_pi.cpp:20
std::string platformInfoToString(pi_platform_info info)
Definition: pi.cpp:203
std::shared_ptr< plugin > GlobalPlugin
Definition: pi.cpp:283
void emitFunctionWithArgsEndTrace(uint64_t CorrelationID, uint32_t FuncID, const char *FName, unsigned char *ArgsData, pi_result Result, pi_plugin Plugin)
Notifies XPTI subscribers about PI function call result.
Definition: pi.cpp:175
::pi_sampler_properties PiSamplerProperties
Definition: pi.hpp:129
::pi_image_handle PiImageHandle
Definition: pi.hpp:144
::pi_ext_sync_point PiExtSyncPoint
Definition: pi.hpp:139
::pi_queue_properties PiQueueProperties
Definition: pi.hpp:123
::pi_device_binary_type PiDeviceBinaryType
Definition: pi.hpp:117
void * getOsLibraryFuncAddress(void *Library, const std::string &FunctionName)
Definition: posix_pi.cpp:47
int unloadOsPluginLibrary(void *Library)
Definition: posix_pi.cpp:39
::pi_interop_semaphore_handle PiInteropSemaphoreHandle
Definition: pi.hpp:148
::pi_ext_command_buffer_command PiExtCommandBufferCommand
Definition: pi.hpp:142
int unloadPlugin(void *Library)
Definition: pi.cpp:338
void * getPluginOpaqueData(void *opaquedata_arg)
Definition: pi.cpp:61
std::shared_ptr< plugin > PluginPtr
Definition: pi.hpp:47
Definition: access.hpp:18
_pi_platform_backend pi_platform_backend
Definition: pi.h:861
_pi_kernel_cache_config
Definition: pi.h:850
_pi_context_info pi_context_info
Definition: pi.h:867
_pi_image_info pi_image_info
Definition: pi.h:869
_pi_device_info pi_device_info
Definition: pi.h:865
_pi_result
Definition: pi.h:250
_pi_device_info
Definition: pi.h:330
_pi_image_channel_type
Definition: pi.h:700
_pi_sampler_info pi_sampler_info
Definition: pi.h:883
_pi_program * pi_program
Definition: pi.h:1249
_pi_image_format pi_image_format
Definition: pi.h:1276
_pi_mem * pi_mem
Definition: pi.h:1248
pi_uint64 pi_image_handle
Definition: pi.h:1253
_pi_ext_command_buffer_command * pi_ext_command_buffer_command
Definition: pi.h:2451
_pi_kernel * pi_kernel
Definition: pi.h:1250
_pi_sampler * pi_sampler
Definition: pi.h:1252
_pi_platform_info
Definition: pi.h:265
_pi_plugin pi_plugin
Definition: pi.h:1307
_pi_image_info
Definition: pi.h:570
_pi_mem_type pi_mem_type
Definition: pi.h:875
pi_uint32 pi_ext_sync_point
Definition: pi.h:2452
_pi_image_channel_order
Definition: pi.h:682
_pi_device_type
Definition: pi.h:298
_pi_image_channel_type pi_image_channel_type
Definition: pi.h:878
pi_bitfield pi_queue_properties
Definition: pi.h:835
_pi_image_desc pi_image_desc
Definition: pi.h:1277
uint8_t pi_device_binary_type
Types of device binary.
Definition: pi.h:981
_pi_image_copy_flags
Definition: pi.h:718
_pi_sampler_filter_mode pi_sampler_filter_mode
Definition: pi.h:881
_pi_result pi_result
Definition: pi.h:859
_pi_event * pi_event
Definition: pi.h:1251
pi_bitfield pi_sampler_properties
Definition: pi.h:766
pi_bitfield pi_mem_flags
Definition: pi.h:800
_pi_device * pi_device
Definition: pi.h:1245
_pi_queue * pi_queue
Definition: pi.h:1247
void(* pi_context_extended_deleter)(void *user_data)
Definition: pi.h:1437
_pi_mem_type
Definition: pi.h:630
_pi_peer_attr pi_peer_attr
Definition: pi.h:1291
_pi_sampler_addressing_mode pi_sampler_addressing_mode
Definition: pi.h:880
_pi_sampler_info
Definition: pi.h:729
_pi_ext_command_buffer * pi_ext_command_buffer
Definition: pi.h:2450
_pi_image_copy_flags pi_image_copy_flags
Definition: pi.h:892
_pi_platform * pi_platform
Definition: pi.h:1244
_pi_context_info
Definition: pi.h:521
_pi_sampler_filter_mode
Definition: pi.h:748
_pi_kernel_cache_config pi_kernel_cache_config
Definition: pi.h:890
void * pi_image_mem_handle
Definition: pi.h:1254
_pi_sampler_addressing_mode
Definition: pi.h:740
_pi_platform_backend
Definition: pi.h:309
_pi_device_type pi_device_type
Definition: pi.h:862
_pi_image_channel_order pi_image_channel_order
Definition: pi.h:877
pi_uint64 pi_interop_semaphore_handle
Definition: pi.h:1256
_pi_peer_attr
Definition: pi.h:1281
_pi_context * pi_context
Definition: pi.h:1246
pi_uint64 pi_interop_mem_handle
Definition: pi.h:1255