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 <sstream> // for operator<<, basic_ostream, string...
24 #include <stddef.h> // for size_t
25 #include <string> // for char_traits, string
26 #include <type_traits> // for false_type, true_type
27 #include <vector> // for vector
28 
29 #ifdef XPTI_ENABLE_INSTRUMENTATION
30 // Forward declarations
31 namespace xpti {
32 struct trace_event_data_t;
33 }
34 #endif
35 
36 namespace sycl {
37 inline namespace _V1 {
38 
39 class context;
40 
41 namespace detail {
42 
43 enum class PiApiKind {
44 #define _PI_API(api) api,
45 #include <sycl/detail/pi.def>
46 };
47 class plugin;
48 using PluginPtr = std::shared_ptr<plugin>;
49 
50 template <sycl::backend BE>
51 __SYCL_EXPORT void *getPluginOpaqueData(void *opaquedata_arg);
52 
53 namespace pi {
54 
55 // The SYCL_PI_TRACE sets what we will trace.
56 // This is a bit-mask of various things we'd want to trace.
57 enum TraceLevel {
61 };
62 
63 // Return true if we want to trace PI related activities.
64 bool trace(TraceLevel level);
65 
66 #ifdef __SYCL_RT_OS_WINDOWS
67 // these same constants are used by pi_win_proxy_loader.dll
68 // if a plugin is added here, add it there as well.
69 #ifdef _MSC_VER
70 #define __SYCL_OPENCL_PLUGIN_NAME "pi_opencl.dll"
71 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "pi_level_zero.dll"
72 #define __SYCL_CUDA_PLUGIN_NAME "pi_cuda.dll"
73 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "pi_esimd_emulator.dll"
74 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dll"
75 #define __SYCL_UR_PLUGIN_NAME "pi_unified_runtime.dll"
76 #define __SYCL_NATIVE_CPU_PLUGIN_NAME "pi_native_cpu.dll"
77 #else
78 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.dll"
79 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.dll"
80 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.dll"
81 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.dll"
82 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dll"
83 #define __SYCL_UR_PLUGIN_NAME "libpi_unified_runtime.dll"
84 #define __SYCL_NATIVE_CPU_PLUGIN_NAME "libpi_native_cpu.dll"
85 #endif
86 #elif defined(__SYCL_RT_OS_LINUX)
87 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.so"
88 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.so"
89 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.so"
90 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.so"
91 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.so"
92 #define __SYCL_UR_PLUGIN_NAME "libpi_unified_runtime.so"
93 #define __SYCL_NATIVE_CPU_PLUGIN_NAME "libpi_native_cpu.so"
94 #elif defined(__SYCL_RT_OS_DARWIN)
95 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.dylib"
96 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.dylib"
97 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.dylib"
98 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.dylib"
99 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dylib"
100 #define __SYCL_UR_PLUGIN_NAME "libpi_unified_runtime.dylib"
101 #define __SYCL_NATIVE_CPU_PLUGIN_NAME "libpi_native_cpu.dylib"
102 #else
103 #error "Unsupported OS"
104 #endif
105 
106 // Report error and no return (keeps compiler happy about no return statements).
107 [[noreturn]] __SYCL_EXPORT void die(const char *Message);
108 
109 __SYCL_EXPORT void assertion(bool Condition, const char *Message = nullptr);
110 
111 template <typename T>
112 void handleUnknownParamName(const char *functionName, T parameter) {
113  std::stringstream stream;
114  stream << "Unknown parameter " << parameter << " passed to " << functionName
115  << "\n";
116  auto str = stream.str();
117  auto msg = str.c_str();
118  die(msg);
119 }
120 
121 // This macro is used to report invalid enumerators being passed to PI API
122 // GetInfo functions. It will print the name of the function that invoked it
123 // and the value of the unknown enumerator.
124 #define __SYCL_PI_HANDLE_UNKNOWN_PARAM_NAME(parameter) \
125  { sycl::detail::pi::handleUnknownParamName(__func__, parameter); }
126 
141 using PiMem = ::pi_mem;
167 
168 __SYCL_EXPORT void contextSetExtendedDeleter(const sycl::context &constext,
170  void *user_data);
171 
172 // Function to load a shared library
173 // Implementation is OS dependent
174 void *loadOsLibrary(const std::string &Library);
175 
176 // Function to unload a shared library
177 // Implementation is OS dependent (see posix-pi.cpp and windows-pi.cpp)
178 int unloadOsLibrary(void *Library);
179 
180 // Function to load the shared plugin library
181 // On Windows, this will have been pre-loaded by proxy loader.
182 // Implementation is OS dependent.
183 void *loadOsPluginLibrary(const std::string &Library);
184 
185 // Function to unload the shared plugin library
186 // Implementation is OS dependent (see posix-pi.cpp and windows-pi.cpp)
187 int unloadOsPluginLibrary(void *Library);
188 
189 // OS agnostic function to unload the shared library
190 int unloadPlugin(void *Library);
191 
192 // Function to get Address of a symbol defined in the shared
193 // library, implementation is OS dependent.
194 void *getOsLibraryFuncAddress(void *Library, const std::string &FunctionName);
195 
196 // Get a string representing a _pi_platform_info enum
197 std::string platformInfoToString(pi_platform_info info);
198 
199 // Want all the needed casts be explicit, do not define conversion operators.
200 template <class To, class From> To cast(From value);
201 
202 // Holds the PluginInformation for the plugin that is bound.
203 // Currently a global variable is used to store OpenCL plugin information to be
204 // used with SYCL Interoperability Constructors.
205 // TODO: GlobalPlugin does not seem to be needed anymore. Consider removing it!
206 extern std::shared_ptr<plugin> GlobalPlugin;
207 
208 // Performs PI one-time initialization.
209 std::vector<PluginPtr> &initialize();
210 
211 // Get the plugin serving given backend.
212 template <backend BE> __SYCL_EXPORT const PluginPtr &getPlugin();
213 
214 // Utility Functions to get Function Name for a PI Api.
215 template <PiApiKind PiApiOffset> struct PiFuncInfo {};
216 
217 #define _PI_API(api) \
218  template <> struct PiFuncInfo<PiApiKind::api> { \
219  using FuncPtrT = decltype(&::api); \
220  inline const char *getFuncName() { return #api; } \
221  inline FuncPtrT getFuncPtr(PiPlugin MPlugin) { \
222  return MPlugin.PiFunctionTable.api; \
223  } \
224  };
225 #include <sycl/detail/pi.def>
226 
231 uint64_t emitFunctionBeginTrace(const char *FName);
232 
237 void emitFunctionEndTrace(uint64_t CorrelationID, const char *FName);
238 
245 uint64_t emitFunctionWithArgsBeginTrace(uint32_t FuncID, const char *FName,
246  unsigned char *ArgsData,
247  pi_plugin Plugin);
248 
258 void emitFunctionWithArgsEndTrace(uint64_t CorrelationID, uint32_t FuncID,
259  const char *FName, unsigned char *ArgsData,
260  pi_result Result, pi_plugin Plugin);
261 
264 PiDeviceBinaryType getBinaryImageFormat(const unsigned char *ImgData,
265  size_t ImgSize);
266 
267 } // namespace pi
268 
269 // Workaround for build with GCC 5.x
270 // An explicit specialization shall be declared in the namespace block.
271 // Having namespace as part of template name is not supported by GCC
272 // older than 7.x.
273 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56480
274 namespace pi {
275 // Want all the needed casts be explicit, do not define conversion
276 // operators.
277 template <class To, class From> inline To cast(From value) {
278  // TODO: see if more sanity checks are possible.
279  sycl::detail::pi::assertion((sizeof(From) == sizeof(To)),
280  "assert: cast failed size check");
281  return (To)(value);
282 }
283 
284 // Helper traits for identifying std::vector with arbitrary element type.
285 template <typename T> struct IsStdVector : std::false_type {};
286 template <typename T> struct IsStdVector<std::vector<T>> : std::true_type {};
287 
288 // Overload for vectors that applies the cast to all elements. This
289 // creates a new vector.
290 template <class To, class FromE> To cast(std::vector<FromE> Values) {
291  static_assert(IsStdVector<To>::value, "Return type must be a vector.");
292  To ResultVec;
293  ResultVec.reserve(Values.size());
294  for (FromE &Val : Values)
295  ResultVec.push_back(cast<typename To::value_type>(Val));
296  return ResultVec;
297 }
298 
299 } // namespace pi
300 } // namespace detail
301 
302 } // namespace _V1
303 } // namespace sycl
304 
305 #undef _PI_API
pi_plugin
_pi_plugin pi_plugin
Definition: pi.h:1145
_pi_mem
Definition: pi_cuda.hpp:56
sycl::_V1::detail::pi::PiSamplerProperties
::pi_sampler_properties PiSamplerProperties
Definition: pi.hpp:146
sycl::_V1::detail::pi::PiQueueProperties
::pi_queue_properties PiQueueProperties
Definition: pi.hpp:140
sycl::_V1::detail::PiApiKind
PiApiKind
Definition: pi.hpp:43
_pi_mem_type
_pi_mem_type
Definition: pi.h:557
sycl::_V1::detail::pi::contextSetExtendedDeleter
void contextSetExtendedDeleter(const sycl::context &constext, pi_context_extended_deleter func, void *user_data)
Definition: pi.cpp:193
sycl::_V1::detail::pi::PiDeviceBinaryType
::pi_device_binary_type PiDeviceBinaryType
Definition: pi.hpp:134
_pi_context_info
_pi_context_info
Definition: pi.h:448
pi_device_info
_pi_device_info pi_device_info
Definition: pi.h:759
pi.h
sycl::_V1::detail::pi::IsStdVector
Definition: pi.hpp:285
_pi_platform_backend
_pi_platform_backend
Definition: pi.h:264
sycl::_V1::detail::pi::getPlugin
const PluginPtr & getPlugin()
Definition: pi.cpp:546
pi_image_desc
_pi_image_desc pi_image_desc
Definition: pi.h:1115
sycl::_V1::detail::pi::loadOsLibrary
void * loadOsLibrary(const std::string &Library)
Definition: posix_pi.cpp:20
pi_program
_pi_program * pi_program
Definition: pi.h:1087
sycl::_V1::detail::pi::initialize
std::vector< PluginPtr > & initialize()
Definition: pi.cpp:429
sycl::_V1::detail::pi::PiFuncInfo
Definition: pi.hpp:215
_pi_plugin
Definition: pi.h:2694
_pi_image_copy_flags
_pi_image_copy_flags
Definition: pi.h:619
sycl::_V1::detail::pi::handleUnknownParamName
void handleUnknownParamName(const char *functionName, T parameter)
Definition: pi.hpp:112
sycl::_V1::detail::pi::PiImageHandle
::pi_image_handle PiImageHandle
Definition: pi.hpp:160
pi_image_info
_pi_image_info pi_image_info
Definition: pi.h:763
sycl::_V1::detail::pi::PiInteropSemaphoreHandle
::pi_interop_semaphore_handle PiInteropSemaphoreHandle
Definition: pi.hpp:164
_pi_result
_pi_result
Definition: pi.h:205
pi_image_copy_flags
_pi_image_copy_flags pi_image_copy_flags
Definition: pi.h:785
pi_kernel_cache_config
_pi_kernel_cache_config pi_kernel_cache_config
Definition: pi.h:783
_pi_device_type
_pi_device_type
Definition: pi.h:253
os_util.hpp
detail
---— Error handling, matching OpenCL plugin semantics.
Definition: common.hpp:44
sycl::_V1::detail::pi::unloadOsPluginLibrary
int unloadOsPluginLibrary(void *Library)
Definition: posix_pi.cpp:39
sycl
Definition: access.hpp:18
sycl::_V1::detail::pi::emitFunctionWithArgsBeginTrace
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
pi_context_info
_pi_context_info pi_context_info
Definition: pi.h:761
_pi_platform
Definition: pi_cuda.hpp:44
pi_ext_command_buffer_desc
Definition: pi.h:2266
_pi_sampler_addressing_mode
_pi_sampler_addressing_mode
Definition: pi.h:641
_pi_device_info
_pi_device_info
Definition: pi.h:285
_pi_image_info
_pi_image_info
Definition: pi.h:497
_pi_kernel
Definition: pi_cuda.hpp:72
sycl::_V1::detail::pi::unloadPlugin
int unloadPlugin(void *Library)
Definition: pi.cpp:395
pi_kernel
_pi_kernel * pi_kernel
Definition: pi.h:1088
pi_sampler
_pi_sampler * pi_sampler
Definition: pi.h:1090
pi_peer_attr
_pi_peer_attr pi_peer_attr
Definition: pi.h:1129
_pi_ext_command_buffer
Definition: pi_cuda.hpp:80
_pi_sampler_filter_mode
_pi_sampler_filter_mode
Definition: pi.h:649
pi_image_channel_order
_pi_image_channel_order pi_image_channel_order
Definition: pi.h:771
sycl::_V1::detail::pi::unloadOsLibrary
int unloadOsLibrary(void *Library)
Definition: posix_pi.cpp:37
sycl::_V1::detail::pi::emitFunctionBeginTrace
uint64_t emitFunctionBeginTrace(const char *FName)
Emits an XPTI trace before a PI API call is made.
Definition: pi.cpp:82
export.hpp
pi_device_binary_type
uint8_t pi_device_binary_type
Types of device binary.
Definition: pi.h:874
_pi_queue
Definition: pi_cuda.hpp:60
pi_image_format
_pi_image_format pi_image_format
Definition: pi.h:1114
pi_interop_mem_handle
pi_uint64 pi_interop_mem_handle
Definition: pi.h:1093
pi_platform_backend
_pi_platform_backend pi_platform_backend
Definition: pi.h:755
pi_platform
_pi_platform * pi_platform
Definition: pi.h:1082
pi_mem_flags
pi_bitfield pi_mem_flags
Definition: pi.h:694
_pi_image_channel_order
_pi_image_channel_order
Definition: pi.h:583
pi_queue
_pi_queue * pi_queue
Definition: pi.h:1085
pi_context_extended_deleter
void(* pi_context_extended_deleter)(void *user_data)
Definition: pi.h:1271
sycl::_V1::detail::pi::PI_TRACE_CALLS
@ PI_TRACE_CALLS
Definition: pi.hpp:59
sycl::_V1::detail::pi::platformInfoToString
std::string platformInfoToString(pi_platform_info info)
Definition: pi.cpp:203
sycl::_V1::detail::pi::PiExtSyncPoint
::pi_ext_sync_point PiExtSyncPoint
Definition: pi.hpp:156
sycl::_V1::detail::pi::PiMemFlags
::pi_mem_flags PiMemFlags
Definition: pi.hpp:142
pi_ext_sync_point
pi_uint32 pi_ext_sync_point
Definition: pi.h:2260
pi_sampler_info
_pi_sampler_info pi_sampler_info
Definition: pi.h:776
pi_mem_type
_pi_mem_type pi_mem_type
Definition: pi.h:769
pi_mem
_pi_mem * pi_mem
Definition: pi.h:1086
_pi_sampler_info
_pi_sampler_info
Definition: pi.h:630
_pi_program
Definition: pi_cuda.hpp:68
_pi_sampler
Definition: pi_cuda.hpp:76
sycl::_V1::detail::pi::cast
PiProgram cast(cl_program)=delete
sycl::_V1::detail::pi::PI_TRACE_BASIC
@ PI_TRACE_BASIC
Definition: pi.hpp:58
pi_sampler_properties
pi_bitfield pi_sampler_properties
Definition: pi.h:662
_pi_image_format
Definition: pi.h:1096
sycl::_V1::detail::pi::die
void die(const char *Message)
Definition: pi.cpp:574
pi_image_mem_handle
void * pi_image_mem_handle
Definition: pi.h:1092
pi_image_handle
pi_uint64 pi_image_handle
Definition: pi.h:1091
sycl::_V1::detail::pi::loadOsPluginLibrary
void * loadOsPluginLibrary(const std::string &Library)
Definition: posix_pi.cpp:33
_pi_image_channel_type
_pi_image_channel_type
Definition: pi.h:601
sycl::_V1::detail::pi::getBinaryImageFormat
PiDeviceBinaryType getBinaryImageFormat(const unsigned char *ImgData, size_t ImgSize)
Tries to determine the device binary image foramat.
Definition: pi.cpp:674
backend_types.hpp
pi_event
_pi_event * pi_event
Definition: pi.h:1089
pi_queue_properties
pi_bitfield pi_queue_properties
Definition: pi.h:729
_pi_platform_info
_pi_platform_info
Definition: pi.h:220
sycl::_V1::detail::pi::TraceLevel
TraceLevel
Definition: pi.hpp:57
_pi_image_desc
Definition: pi.h:1101
sycl::_V1::detail::pi::getOsLibraryFuncAddress
void * getOsLibraryFuncAddress(void *Library, const std::string &FunctionName)
Definition: posix_pi.cpp:47
std
Definition: accessor.hpp:4139
_pi_event
Definition: pi_cuda.hpp:64
sycl::_V1::detail::pi::GlobalPlugin
std::shared_ptr< plugin > GlobalPlugin
Definition: pi.cpp:283
pi_result
_pi_result pi_result
Definition: pi.h:753
pi_sampler_addressing_mode
_pi_sampler_addressing_mode pi_sampler_addressing_mode
Definition: pi.h:774
pi_image_offset_struct
Definition: pi.h:1034
sycl::_V1::detail::pi::PiInteropMemHandle
::pi_interop_mem_handle PiInteropMemHandle
Definition: pi.hpp:163
sycl::_V1::detail::pi::PI_TRACE_ALL
@ PI_TRACE_ALL
Definition: pi.hpp:60
sycl::_V1::detail::pi::assertion
void assertion(bool Condition, const char *Message=nullptr)
Definition: pi.cpp:579
pi_image_region_struct
Definition: pi.h:1043
pi_device_type
_pi_device_type pi_device_type
Definition: pi.h:756
sycl::_V1::detail::pi::PiImageMemHandle
::pi_image_mem_handle PiImageMemHandle
Definition: pi.hpp:161
pi_sampler_filter_mode
_pi_sampler_filter_mode pi_sampler_filter_mode
Definition: pi.h:775
sycl::_V1::detail::pi::emitFunctionEndTrace
void emitFunctionEndTrace(uint64_t CorrelationID, const char *FName)
Emits an XPTI trace after the PI API call has been made.
Definition: pi.cpp:127
pi_interop_semaphore_handle
pi_uint64 pi_interop_semaphore_handle
Definition: pi.h:1094
sycl::_V1::detail::getPluginOpaqueData
void * getPluginOpaqueData(void *opaquedata_arg)
Definition: pi.cpp:61
_pi_peer_attr
_pi_peer_attr
Definition: pi.h:1119
sycl::_V1::detail::pi::trace
bool trace(TraceLevel level)
Definition: pi.cpp:423
pi_image_channel_type
_pi_image_channel_type pi_image_channel_type
Definition: pi.h:772
pi_ext_command_buffer
_pi_ext_command_buffer * pi_ext_command_buffer
Definition: pi.h:2259
_pi_kernel_cache_config
_pi_kernel_cache_config
Definition: pi.h:744
sycl::_V1::detail::pi::emitFunctionWithArgsEndTrace
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_device
_pi_device * pi_device
Definition: pi.h:1083
_pi_context
Definition: pi_cuda.hpp:52
pi_context
_pi_context * pi_context
Definition: pi.h:1084
_pi_device
Definition: pi_cuda.hpp:48
sycl::_V1::context
The context class represents a SYCL context on which kernel functions may be executed.
Definition: context.hpp:51
sycl::_V1::detail::PluginPtr
std::shared_ptr< plugin > PluginPtr
Definition: pi.hpp:48