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 {
58  PI_TRACE_ALL = -1
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 #define __SYCL_OPENCL_PLUGIN_NAME "pi_opencl.dll"
66 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "pi_level_zero.dll"
67 #define __SYCL_CUDA_PLUGIN_NAME "pi_cuda.dll"
68 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "pi_esimd_emulator.dll"
69 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dll"
70 #elif defined(__SYCL_RT_OS_LINUX)
71 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.so"
72 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.so"
73 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.so"
74 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.so"
75 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.so"
76 #elif defined(__SYCL_RT_OS_DARWIN)
77 #define __SYCL_OPENCL_PLUGIN_NAME "libpi_opencl.dylib"
78 #define __SYCL_LEVEL_ZERO_PLUGIN_NAME "libpi_level_zero.dylib"
79 #define __SYCL_CUDA_PLUGIN_NAME "libpi_cuda.dylib"
80 #define __SYCL_ESIMD_EMULATOR_PLUGIN_NAME "libpi_esimd_emulator.dylib"
81 #define __SYCL_HIP_PLUGIN_NAME "libpi_hip.dylib"
82 #else
83 #error "Unsupported OS"
84 #endif
85 
86 // Report error and no return (keeps compiler happy about no return statements).
87 [[noreturn]] __SYCL_EXPORT void die(const char *Message);
88 
89 __SYCL_EXPORT void assertion(bool Condition, const char *Message = nullptr);
90 
91 template <typename T>
92 void handleUnknownParamName(const char *functionName, T parameter) {
93  std::stringstream stream;
94  stream << "Unknown parameter " << parameter << " passed to " << functionName
95  << "\n";
96  auto str = stream.str();
97  auto msg = str.c_str();
98  die(msg);
99 }
100 
101 // This macro is used to report invalid enumerators being passed to PI API
102 // GetInfo functions. It will print the name of the function that invoked it
103 // and the value of the unknown enumerator.
104 #define __SYCL_PI_HANDLE_UNKNOWN_PARAM_NAME(parameter) \
105  { sycl::detail::pi::handleUnknownParamName(__func__, parameter); }
106 
119 using PiMem = ::pi_mem;
133 
134 __SYCL_EXPORT void contextSetExtendedDeleter(const sycl::context &constext,
136  void *user_data);
137 
138 // Function to load the shared library
139 // Implementation is OS dependent.
140 void *loadOsLibrary(const std::string &Library);
141 
142 // Function to unload the shared library
143 // Implementation is OS dependent (see posix-pi.cpp and windows-pi.cpp)
144 int unloadOsLibrary(void *Library);
145 
146 // OS agnostic function to unload the shared library
147 int unloadPlugin(void *Library);
148 
149 // Function to get Address of a symbol defined in the shared
150 // library, implementation is OS dependent.
151 void *getOsLibraryFuncAddress(void *Library, const std::string &FunctionName);
152 
153 // Get a string representing a _pi_platform_info enum
154 std::string platformInfoToString(pi_platform_info info);
155 
156 // Want all the needed casts be explicit, do not define conversion operators.
157 template <class To, class From> To cast(From value);
158 
159 // Holds the PluginInformation for the plugin that is bound.
160 // Currently a global variable is used to store OpenCL plugin information to be
161 // used with SYCL Interoperability Constructors.
162 // TODO: GlobalPlugin does not seem to be needed anymore. Consider removing it!
163 extern std::shared_ptr<plugin> GlobalPlugin;
164 
165 // Performs PI one-time initialization.
166 std::vector<plugin> &initialize();
167 
168 // Get the plugin serving given backend.
169 template <backend BE> __SYCL_EXPORT const plugin &getPlugin();
170 
171 // Utility Functions to get Function Name for a PI Api.
172 template <PiApiKind PiApiOffset> struct PiFuncInfo {};
173 
174 #define _PI_API(api) \
175  template <> struct PiFuncInfo<PiApiKind::api> { \
176  using FuncPtrT = decltype(&::api); \
177  inline const char *getFuncName() { return #api; } \
178  inline FuncPtrT getFuncPtr(PiPlugin MPlugin) { \
179  return MPlugin.PiFunctionTable.api; \
180  } \
181  };
182 #include <sycl/detail/pi.def>
183 
188 uint64_t emitFunctionBeginTrace(const char *FName);
189 
194 void emitFunctionEndTrace(uint64_t CorrelationID, const char *FName);
195 
202 uint64_t emitFunctionWithArgsBeginTrace(uint32_t FuncID, const char *FName,
203  unsigned char *ArgsData,
204  pi_plugin Plugin);
205 
215 void emitFunctionWithArgsEndTrace(uint64_t CorrelationID, uint32_t FuncID,
216  const char *FName, unsigned char *ArgsData,
217  pi_result Result, pi_plugin Plugin);
218 
221 PiDeviceBinaryType getBinaryImageFormat(const unsigned char *ImgData,
222  size_t ImgSize);
223 
224 } // namespace pi
225 
226 namespace RT = sycl::detail::pi;
227 
228 // Workaround for build with GCC 5.x
229 // An explicit specialization shall be declared in the namespace block.
230 // Having namespace as part of template name is not supported by GCC
231 // older than 7.x.
232 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56480
233 namespace pi {
234 // Want all the needed casts be explicit, do not define conversion
235 // operators.
236 template <class To, class From> inline To cast(From value) {
237  // TODO: see if more sanity checks are possible.
238  RT::assertion((sizeof(From) == sizeof(To)), "assert: cast failed size check");
239  return (To)(value);
240 }
241 
242 // Helper traits for identifying std::vector with arbitrary element type.
243 template <typename T> struct IsStdVector : std::false_type {};
244 template <typename T> struct IsStdVector<std::vector<T>> : std::true_type {};
245 
246 // Overload for vectors that applies the cast to all elements. This
247 // creates a new vector.
248 template <class To, class FromE> To cast(std::vector<FromE> Values) {
249  static_assert(IsStdVector<To>::value, "Return type must be a vector.");
250  To ResultVec;
251  ResultVec.reserve(Values.size());
252  for (FromE &Val : Values)
253  ResultVec.push_back(cast<typename To::value_type>(Val));
254  return ResultVec;
255 }
256 
257 } // namespace pi
258 } // namespace detail
259 
260 // For shortness of using PI from the top-level sycl files.
261 namespace RT = sycl::detail::pi;
262 
263 } // __SYCL_INLINE_VER_NAMESPACE(_V1)
264 } // namespace sycl
265 
266 #undef _PI_API
The plugin class provides a unified interface to the underlying low-level runtimes for the device-agn...
Definition: plugin.hpp:90
#define __SYCL_INLINE_VER_NAMESPACE(X)
void contextSetExtendedDeleter(const sycl::context &constext, pi_context_extended_deleter func, void *user_data)
Definition: pi.cpp:181
void emitFunctionEndTrace(uint64_t CorrelationID, const char *FName)
Emits an XPTI trace after the PI API call has been made.
Definition: pi.cpp:129
int unloadOsLibrary(void *Library)
Definition: posix_pi.cpp:32
void die(const char *Message)
Definition: pi.cpp:536
::pi_mem_flags PiMemFlags
Definition: pi.hpp:120
uint64_t emitFunctionBeginTrace(const char *FName)
Emits an XPTI trace before a PI API call is made.
Definition: pi.cpp:85
void assertion(bool Condition, const char *Message=nullptr)
Definition: pi.cpp:541
PiDeviceBinaryType getBinaryImageFormat(const unsigned char *ImgData, size_t ImgSize)
Tries to determine the device binary image foramat.
Definition: pi.cpp:635
void handleUnknownParamName(const char *functionName, T parameter)
Definition: pi.hpp:92
bool trace(TraceLevel level)
Definition: pi.cpp:394
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:144
const plugin & getPlugin()
Definition: pi.cpp:509
void * loadOsLibrary(const std::string &Library)
Definition: posix_pi.cpp:20
std::string platformInfoToString(pi_platform_info info)
Definition: pi.cpp:191
std::shared_ptr< plugin > GlobalPlugin
Definition: pi.cpp:269
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:164
std::vector< plugin > & initialize()
Definition: pi.cpp:400
::pi_sampler_properties PiSamplerProperties
Definition: pi.hpp:124
::pi_queue_properties PiQueueProperties
Definition: pi.hpp:118
::pi_device_binary_type PiDeviceBinaryType
Definition: pi.hpp:113
void * getOsLibraryFuncAddress(void *Library, const std::string &FunctionName)
Definition: posix_pi.cpp:40
int unloadPlugin(void *Library)
Definition: pi.cpp:366
void * getPluginOpaqueData(void *opaquedata_arg)
Definition: pi.cpp:64
---— Error handling, matching OpenCL plugin semantics.
Definition: access.hpp:14
_pi_image_info pi_image_info
Definition: pi.h:602
_pi_device_info pi_device_info
Definition: pi.h:598
_pi_result
Definition: pi.h:118
_pi_device_info
Definition: pi.h:187
_pi_image_channel_type
Definition: pi.h:463
_pi_sampler_info pi_sampler_info
Definition: pi.h:615
_pi_program * pi_program
Definition: pi.h:917
_pi_image_format pi_image_format
Definition: pi.h:940
_pi_mem * pi_mem
Definition: pi.h:916
_pi_kernel * pi_kernel
Definition: pi.h:918
_pi_sampler * pi_sampler
Definition: pi.h:920
_pi_platform_info
Definition: pi.h:133
_pi_plugin pi_plugin
Definition: pi.h:961
_pi_image_info
Definition: pi.h:362
_pi_mem_type pi_mem_type
Definition: pi.h:608
_pi_image_channel_order
Definition: pi.h:445
_pi_device_type
Definition: pi.h:165
_pi_image_channel_type pi_image_channel_type
Definition: pi.h:611
pi_bitfield pi_queue_properties
Definition: pi.h:584
_pi_image_desc pi_image_desc
Definition: pi.h:941
uint8_t pi_device_binary_type
Types of device binary.
Definition: pi.h:708
_pi_sampler_filter_mode pi_sampler_filter_mode
Definition: pi.h:614
_pi_result pi_result
Definition: pi.h:593
_pi_event * pi_event
Definition: pi.h:919
pi_bitfield pi_sampler_properties
Definition: pi.h:518
pi_bitfield pi_mem_flags
Definition: pi.h:549
_pi_device * pi_device
Definition: pi.h:913
_pi_queue * pi_queue
Definition: pi.h:915
void(* pi_context_extended_deleter)(void *user_data)
Definition: pi.h:1079
_pi_mem_type
Definition: pi.h:419
_pi_sampler_addressing_mode pi_sampler_addressing_mode
Definition: pi.h:613
_pi_sampler_info
Definition: pi.h:486
_pi_platform * pi_platform
Definition: pi.h:912
_pi_sampler_filter_mode
Definition: pi.h:505
_pi_sampler_addressing_mode
Definition: pi.h:497
_pi_device_type pi_device_type
Definition: pi.h:595
_pi_image_channel_order pi_image_channel_order
Definition: pi.h:610
_pi_context * pi_context
Definition: pi.h:914
To cast(From value)
Definition: pi_opencl.cpp:42
PI context mapping to a CUDA context object.
Definition: pi_cuda.hpp:160
PI device mapping to a CUdevice.
Definition: pi_cuda.hpp:83
PI Event mapping to CUevent.
Definition: pi_cuda.hpp:630
Implementation of a PI Kernel for CUDA.
Definition: pi_cuda.hpp:813
PI Mem mapping to CUDA memory allocations, both data and texture/surface.
Definition: pi_cuda.hpp:222
A PI platform stores all known PI devices, in the CUDA plugin this is just a vector of available devi...
Definition: pi_cuda.hpp:73
Implementation of PI Program on CUDA Module object.
Definition: pi_cuda.hpp:758
PI queue mapping on to CUstream objects.
Definition: pi_cuda.hpp:393
Implementation of samplers for CUDA.
Definition: pi_cuda.hpp:984