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 {
60  PI_TRACE_ALL = -1
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 "pi_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
The context class represents a SYCL context on which kernel functions may be executed.
Definition: context.hpp:51
const PluginPtr & getPlugin()
Definition: pi.cpp:558
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:436
::pi_image_mem_handle PiImageMemHandle
Definition: pi.hpp:161
void die(const char *Message)
Definition: pi.cpp:586
::pi_mem_flags PiMemFlags
Definition: pi.hpp:142
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:163
void assertion(bool Condition, const char *Message=nullptr)
Definition: pi.cpp:591
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:686
void handleUnknownParamName(const char *functionName, T parameter)
Definition: pi.hpp:112
bool trace(TraceLevel level)
Definition: pi.cpp:430
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:146
::pi_image_handle PiImageHandle
Definition: pi.hpp:160
::pi_ext_sync_point PiExtSyncPoint
Definition: pi.hpp:156
::pi_queue_properties PiQueueProperties
Definition: pi.hpp:140
::pi_device_binary_type PiDeviceBinaryType
Definition: pi.hpp:134
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:164
int unloadPlugin(void *Library)
Definition: pi.cpp:402
void * getPluginOpaqueData(void *opaquedata_arg)
Definition: pi.cpp:61
std::shared_ptr< plugin > PluginPtr
Definition: pi.hpp:48
Definition: access.hpp:18
_pi_platform_backend pi_platform_backend
Definition: pi.h:790
_pi_kernel_cache_config
Definition: pi.h:779
_pi_context_info pi_context_info
Definition: pi.h:796
_pi_image_info pi_image_info
Definition: pi.h:798
_pi_device_info pi_device_info
Definition: pi.h:794
_pi_result
Definition: pi.h:211
_pi_device_info
Definition: pi.h:291
_pi_image_channel_type
Definition: pi.h:636
_pi_sampler_info pi_sampler_info
Definition: pi.h:811
_pi_program * pi_program
Definition: pi.h:1124
_pi_image_format pi_image_format
Definition: pi.h:1151
_pi_mem * pi_mem
Definition: pi.h:1123
pi_uint64 pi_image_handle
Definition: pi.h:1128
_pi_kernel * pi_kernel
Definition: pi.h:1125
_pi_sampler * pi_sampler
Definition: pi.h:1127
_pi_platform_info
Definition: pi.h:226
_pi_plugin pi_plugin
Definition: pi.h:1182
_pi_image_info
Definition: pi.h:507
_pi_mem_type pi_mem_type
Definition: pi.h:804
pi_uint32 pi_ext_sync_point
Definition: pi.h:2298
_pi_image_channel_order
Definition: pi.h:618
_pi_device_type
Definition: pi.h:259
_pi_image_channel_type pi_image_channel_type
Definition: pi.h:807
pi_bitfield pi_queue_properties
Definition: pi.h:764
_pi_image_desc pi_image_desc
Definition: pi.h:1152
uint8_t pi_device_binary_type
Types of device binary.
Definition: pi.h:909
_pi_image_copy_flags
Definition: pi.h:654
_pi_sampler_filter_mode pi_sampler_filter_mode
Definition: pi.h:810
_pi_result pi_result
Definition: pi.h:788
_pi_event * pi_event
Definition: pi.h:1126
pi_bitfield pi_sampler_properties
Definition: pi.h:697
pi_bitfield pi_mem_flags
Definition: pi.h:729
_pi_device * pi_device
Definition: pi.h:1120
_pi_queue * pi_queue
Definition: pi.h:1122
void(* pi_context_extended_deleter)(void *user_data)
Definition: pi.h:1308
_pi_mem_type
Definition: pi.h:567
_pi_peer_attr pi_peer_attr
Definition: pi.h:1166
_pi_sampler_addressing_mode pi_sampler_addressing_mode
Definition: pi.h:809
_pi_sampler_info
Definition: pi.h:665
_pi_ext_command_buffer * pi_ext_command_buffer
Definition: pi.h:2297
_pi_image_copy_flags pi_image_copy_flags
Definition: pi.h:820
_pi_platform * pi_platform
Definition: pi.h:1119
_pi_context_info
Definition: pi.h:458
_pi_sampler_filter_mode
Definition: pi.h:684
_pi_kernel_cache_config pi_kernel_cache_config
Definition: pi.h:818
void * pi_image_mem_handle
Definition: pi.h:1129
_pi_sampler_addressing_mode
Definition: pi.h:676
_pi_platform_backend
Definition: pi.h:270
_pi_device_type pi_device_type
Definition: pi.h:791
_pi_image_channel_order pi_image_channel_order
Definition: pi.h:806
pi_uint64 pi_interop_semaphore_handle
Definition: pi.h:1131
_pi_peer_attr
Definition: pi.h:1156
_pi_context * pi_context
Definition: pi.h:1121
pi_uint64 pi_interop_mem_handle
Definition: pi.h:1130