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>
17 #include <sycl/detail/export.hpp>
18 #include <sycl/detail/os_util.hpp>
19 #include <sycl/detail/pi.h>
20 
21 #include <cassert>
22 #include <cstdint>
23 #include <memory>
24 #include <sstream>
25 #include <string>
26 #include <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 {
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 
48 template <sycl::backend BE>
49 __SYCL_EXPORT void *getPluginOpaqueData(void *opaquedata_arg);
50 
51 namespace pi {
52 
53 // The SYCL_PI_TRACE sets what we will trace.
54 // This is a bit-mask of various things we'd want to trace.
55 enum TraceLevel {
59 };
60 
61 // Return true if we want to trace PI related activities.
62 bool trace(TraceLevel level);
63 
64 #ifdef __SYCL_RT_OS_WINDOWS
65 // these same constants are used by win_proxy_loader.dll
66 // if a plugin is added here, add it there as well.
67 #ifdef _MSC_VER
68 #define __SYCL_OPENCL_PLUGIN_NAME "pi_opencl.dll"
69 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "pi_level_zero.dll"
70 #define __SYCL_CUDA_PLUGIN_NAME "pi_cuda.dll"
71 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "pi_esimd_emulator.dll"
72 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dll"
73 #define __SYCL_UNIFIED_RUNTIME_PLUGIN_NAME "pi_unified_runtime.dll"
74 #else
75 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.dll"
76 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.dll"
77 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.dll"
78 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.dll"
79 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dll"
80 #define __SYCL_UNIFIED_RUNTIME_PLUGIN_NAME "libpi_unified_runtime.dll"
81 #endif
82 #elif defined(__SYCL_RT_OS_LINUX)
83 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.so"
84 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.so"
85 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.so"
86 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.so"
87 #define __SYCL_UNIFIED_RUNTIME_PLUGIN_NAME "libpi_unified_runtime.so"
88 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.so"
89 #elif defined(__SYCL_RT_OS_DARWIN)
90 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.dylib"
91 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.dylib"
92 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.dylib"
93 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.dylib"
94 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dylib"
95 #define __SYCL_UNIFIED_RUNTIME_PLUGIN_NAME "libpi_unified_runtime.dylib"
96 #else
97 #error "Unsupported OS"
98 #endif
99 
100 // Report error and no return (keeps compiler happy about no return statements).
101 [[noreturn]] __SYCL_EXPORT void die(const char *Message);
102 
103 __SYCL_EXPORT void assertion(bool Condition, const char *Message = nullptr);
104 
105 template <typename T>
106 void handleUnknownParamName(const char *functionName, T parameter) {
107  std::stringstream stream;
108  stream << "Unknown parameter " << parameter << " passed to " << functionName
109  << "\n";
110  auto str = stream.str();
111  auto msg = str.c_str();
112  die(msg);
113 }
114 
115 // This macro is used to report invalid enumerators being passed to PI API
116 // GetInfo functions. It will print the name of the function that invoked it
117 // and the value of the unknown enumerator.
118 #define __SYCL_PI_HANDLE_UNKNOWN_PARAM_NAME(parameter) \
119  { sycl::detail::pi::handleUnknownParamName(__func__, parameter); }
120 
134 using PiMem = ::pi_mem;
149 
150 __SYCL_EXPORT void contextSetExtendedDeleter(const sycl::context &constext,
152  void *user_data);
153 
154 // Function to load the shared library
155 // Implementation is OS dependent.
156 void *loadOsPluginLibrary(const std::string &Library);
157 
158 // Function to unload the shared library
159 // Implementation is OS dependent (see posix-pi.cpp and windows-pi.cpp)
160 int unloadOsPluginLibrary(void *Library);
161 
162 // OS agnostic function to unload the shared library
163 int unloadPlugin(void *Library);
164 
165 // Function to get Address of a symbol defined in the shared
166 // library, implementation is OS dependent.
167 void *getOsLibraryFuncAddress(void *Library, const std::string &FunctionName);
168 
169 // Get a string representing a _pi_platform_info enum
170 std::string platformInfoToString(pi_platform_info info);
171 
172 // Want all the needed casts be explicit, do not define conversion operators.
173 template <class To, class From> To cast(From value);
174 
175 // Holds the PluginInformation for the plugin that is bound.
176 // Currently a global variable is used to store OpenCL plugin information to be
177 // used with SYCL Interoperability Constructors.
178 // TODO: GlobalPlugin does not seem to be needed anymore. Consider removing it!
179 extern std::shared_ptr<plugin> GlobalPlugin;
180 
181 // Performs PI one-time initialization.
182 std::vector<plugin> &initialize();
183 
184 // Get the plugin serving given backend.
185 template <backend BE> __SYCL_EXPORT const plugin &getPlugin();
186 
187 // Utility Functions to get Function Name for a PI Api.
188 template <PiApiKind PiApiOffset> struct PiFuncInfo {};
189 
190 #define _PI_API(api) \
191  template <> struct PiFuncInfo<PiApiKind::api> { \
192  using FuncPtrT = decltype(&::api); \
193  inline const char *getFuncName() { return #api; } \
194  inline FuncPtrT getFuncPtr(PiPlugin MPlugin) { \
195  return MPlugin.PiFunctionTable.api; \
196  } \
197  };
198 #include <sycl/detail/pi.def>
199 
204 uint64_t emitFunctionBeginTrace(const char *FName);
205 
210 void emitFunctionEndTrace(uint64_t CorrelationID, const char *FName);
211 
218 uint64_t emitFunctionWithArgsBeginTrace(uint32_t FuncID, const char *FName,
219  unsigned char *ArgsData,
220  pi_plugin Plugin);
221 
231 void emitFunctionWithArgsEndTrace(uint64_t CorrelationID, uint32_t FuncID,
232  const char *FName, unsigned char *ArgsData,
233  pi_result Result, pi_plugin Plugin);
234 
237 PiDeviceBinaryType getBinaryImageFormat(const unsigned char *ImgData,
238  size_t ImgSize);
239 
240 } // namespace pi
241 
242 namespace RT = sycl::detail::pi;
243 
244 // Workaround for build with GCC 5.x
245 // An explicit specialization shall be declared in the namespace block.
246 // Having namespace as part of template name is not supported by GCC
247 // older than 7.x.
248 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56480
249 namespace pi {
250 // Want all the needed casts be explicit, do not define conversion
251 // operators.
252 template <class To, class From> inline To cast(From value) {
253  // TODO: see if more sanity checks are possible.
254  RT::assertion((sizeof(From) == sizeof(To)), "assert: cast failed size check");
255  return (To)(value);
256 }
257 
258 // Helper traits for identifying std::vector with arbitrary element type.
259 template <typename T> struct IsStdVector : std::false_type {};
260 template <typename T> struct IsStdVector<std::vector<T>> : std::true_type {};
261 
262 // Overload for vectors that applies the cast to all elements. This
263 // creates a new vector.
264 template <class To, class FromE> To cast(std::vector<FromE> Values) {
265  static_assert(IsStdVector<To>::value, "Return type must be a vector.");
266  To ResultVec;
267  ResultVec.reserve(Values.size());
268  for (FromE &Val : Values)
269  ResultVec.push_back(cast<typename To::value_type>(Val));
270  return ResultVec;
271 }
272 
273 } // namespace pi
274 } // namespace detail
275 
276 // For shortness of using PI from the top-level sycl files.
277 namespace RT = sycl::detail::pi;
278 
279 } // __SYCL_INLINE_VER_NAMESPACE(_V1)
280 } // namespace sycl
281 
282 #undef _PI_API
pi_plugin
_pi_plugin pi_plugin
Definition: pi.h:1014
_pi_mem
PI Mem mapping to CUDA memory allocations, both data and texture/surface.
Definition: pi_cuda.hpp:224
sycl::_V1::detail::pi::PiSamplerProperties
::pi_sampler_properties PiSamplerProperties
Definition: pi.hpp:139
sycl::_V1::detail::pi::PiQueueProperties
::pi_queue_properties PiQueueProperties
Definition: pi.hpp:133
sycl::_V1::detail::PiApiKind
PiApiKind
Definition: pi.hpp:42
_pi_mem_type
_pi_mem_type
Definition: pi.h:455
sycl::_V1::detail::pi::contextSetExtendedDeleter
void contextSetExtendedDeleter(const sycl::context &constext, pi_context_extended_deleter func, void *user_data)
Definition: pi.cpp:172
sycl::_V1::detail::pi::PiDeviceBinaryType
::pi_device_binary_type PiDeviceBinaryType
Definition: pi.hpp:127
_pi_context_info
_pi_context_info
Definition: pi.h:347
pi_device_info
_pi_device_info pi_device_info
Definition: pi.h:647
pi.h
sycl::_V1::detail::pi::IsStdVector
Definition: pi.hpp:259
pi_image_desc
_pi_image_desc pi_image_desc
Definition: pi.h:994
pi_program
_pi_program * pi_program
Definition: pi.h:970
sycl::_V1::detail::pi::PiFuncInfo
Definition: pi.hpp:188
__SYCL_INLINE_VER_NAMESPACE
#define __SYCL_INLINE_VER_NAMESPACE(X)
Definition: defines_elementary.hpp:11
_pi_plugin
Definition: pi.h:1992
sycl::_V1::detail::pi::handleUnknownParamName
void handleUnknownParamName(const char *functionName, T parameter)
Definition: pi.hpp:106
pi_image_info
_pi_image_info pi_image_info
Definition: pi.h:651
_pi_result
_pi_result
Definition: pi.h:140
pi_kernel_cache_config
_pi_kernel_cache_config pi_kernel_cache_config
Definition: pi.h:671
_pi_device_type
_pi_device_type
Definition: pi.h:187
os_util.hpp
sycl::_V1::detail::pi::unloadOsPluginLibrary
int unloadOsPluginLibrary(void *Library)
Definition: posix_pi.cpp:31
sycl
---— Error handling, matching OpenCL plugin semantics.
Definition: access.hpp:14
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:135
pi_context_info
_pi_context_info pi_context_info
Definition: pi.h:649
_pi_platform
A PI platform stores all known PI devices, in the CUDA plugin this is just a vector of available devi...
Definition: pi_cuda.hpp:74
_pi_sampler_addressing_mode
_pi_sampler_addressing_mode
Definition: pi.h:533
cast
To cast(From value)
Definition: pi_opencl.cpp:42
_pi_device_info
_pi_device_info
Definition: pi.h:209
_pi_image_info
_pi_image_info
Definition: pi.h:396
_pi_kernel
Implementation of a PI Kernel for CUDA.
Definition: pi_cuda.hpp:816
sycl::_V1::detail::pi::unloadPlugin
int unloadPlugin(void *Library)
Definition: pi.cpp:363
pi_kernel
_pi_kernel * pi_kernel
Definition: pi.h:971
sycl::_V1::detail::pi::getPlugin
const plugin & getPlugin()
Definition: pi.cpp:506
pi_sampler
_pi_sampler * pi_sampler
Definition: pi.h:973
_pi_sampler_filter_mode
_pi_sampler_filter_mode
Definition: pi.h:541
pi_image_channel_order
_pi_image_channel_order pi_image_channel_order
Definition: pi.h:659
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:76
export.hpp
pi_device_binary_type
uint8_t pi_device_binary_type
Types of device binary.
Definition: pi.h:760
_pi_queue
PI queue mapping on to CUstream objects.
Definition: pi_cuda.hpp:395
sycl::_V1::detail::plugin
The plugin class provides a unified interface to the underlying low-level runtimes for the device-agn...
Definition: plugin.hpp:90
pi_image_format
_pi_image_format pi_image_format
Definition: pi.h:993
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:632
pi_platform
_pi_platform * pi_platform
Definition: pi.h:965
pi_mem_flags
pi_bitfield pi_mem_flags
Definition: pi.h:585
_pi_image_channel_order
_pi_image_channel_order
Definition: pi.h:481
pi_queue
_pi_queue * pi_queue
Definition: pi.h:968
pi_context_extended_deleter
void(* pi_context_extended_deleter)(void *user_data)
Definition: pi.h:1132
sycl::_V1::detail::pi::PI_TRACE_CALLS
@ PI_TRACE_CALLS
Definition: pi.hpp:57
sycl::_V1::detail::pi::platformInfoToString
std::string platformInfoToString(pi_platform_info info)
Definition: pi.cpp:182
sycl::_V1::detail::pi::PiMemFlags
::pi_mem_flags PiMemFlags
Definition: pi.hpp:135
pi_sampler_info
_pi_sampler_info pi_sampler_info
Definition: pi.h:664
pi_mem_type
_pi_mem_type pi_mem_type
Definition: pi.h:657
pi_mem
_pi_mem * pi_mem
Definition: pi.h:969
_pi_sampler_info
_pi_sampler_info
Definition: pi.h:522
_pi_program
Implementation of PI Program on CUDA Module object.
Definition: pi_cuda.hpp:760
_pi_sampler
Implementation of samplers for CUDA.
Definition: pi_cuda.hpp:987
sycl::_V1::detail::pi::PI_TRACE_BASIC
@ PI_TRACE_BASIC
Definition: pi.hpp:56
pi_sampler_properties
pi_bitfield pi_sampler_properties
Definition: pi.h:554
_pi_image_format
Definition: pi.h:975
sycl::_V1::detail::pi::initialize
std::vector< plugin > & initialize()
Definition: pi.cpp:397
sycl::_V1::detail::pi::die
void die(const char *Message)
Definition: pi.cpp:533
sycl::_V1::detail::pi::loadOsPluginLibrary
void * loadOsPluginLibrary(const std::string &Library)
Definition: posix_pi.cpp:19
_pi_image_channel_type
_pi_image_channel_type
Definition: pi.h:499
backend_types.hpp
pi_event
_pi_event * pi_event
Definition: pi.h:972
pi_queue_properties
pi_bitfield pi_queue_properties
Definition: pi.h:620
_pi_platform_info
_pi_platform_info
Definition: pi.h:155
sycl::_V1::detail::pi::TraceLevel
TraceLevel
Definition: pi.hpp:55
_pi_image_desc
Definition: pi.h:980
sycl::_V1::detail::pi::getOsLibraryFuncAddress
void * getOsLibraryFuncAddress(void *Library, const std::string &FunctionName)
Definition: posix_pi.cpp:39
std
Definition: accessor.hpp:3230
_pi_event
PI Event mapping to CUevent.
Definition: pi_cuda.hpp:632
sycl::_V1::detail::pi::GlobalPlugin
std::shared_ptr< plugin > GlobalPlugin
Definition: pi.cpp:260
pi_result
_pi_result pi_result
Definition: pi.h:642
pi_sampler_addressing_mode
_pi_sampler_addressing_mode pi_sampler_addressing_mode
Definition: pi.h:662
sycl::_V1::detail::pi::PI_TRACE_ALL
@ PI_TRACE_ALL
Definition: pi.hpp:58
sycl::_V1::detail::pi::assertion
void assertion(bool Condition, const char *Message=nullptr)
Definition: pi.cpp:538
pi_device_type
_pi_device_type pi_device_type
Definition: pi.h:644
pi_sampler_filter_mode
_pi_sampler_filter_mode pi_sampler_filter_mode
Definition: pi.h:663
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:120
sycl::_V1::detail::getPluginOpaqueData
void * getPluginOpaqueData(void *opaquedata_arg)
Definition: pi.cpp:55
sycl::_V1::detail::pi::trace
bool trace(TraceLevel level)
Definition: pi.cpp:391
pi_image_channel_type
_pi_image_channel_type pi_image_channel_type
Definition: pi.h:660
_pi_kernel_cache_config
_pi_kernel_cache_config
Definition: pi.h:633
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:155
pi_device
_pi_device * pi_device
Definition: pi.h:966
_pi_context
PI context mapping to a CUDA context object.
Definition: pi_cuda.hpp:170
pi_context
_pi_context * pi_context
Definition: pi.h:967
_pi_device
PI device mapping to a CUdevice.
Definition: pi_cuda.hpp:83