gpu_context_api_ocl.hpp
Go to the documentation of this file.
1 // Copyright (C) 2018-2020 Intel Corporation
2 // SPDX-License-Identifier: Apache-2.0
3 //
4 
5 /**
6  * @brief a header that defines wrappers for internal GPU plugin-specific
7  * OpenCL context and OpenCL shared memory blobs
8  *
9  * @file gpu_context_api_ocl.hpp
10  */
11 #pragma once
12 
13 #include <memory>
14 #include <string>
15 #include "ie_compound_blob.h"
16 #include "ie_core.hpp"
17 #include "gpu_params.hpp"
19 #include "gpu_ocl_wrapper.hpp"
20 
21 namespace InferenceEngine {
22 
23 namespace gpu {
24 /**
25 * @brief This class represents an abstraction for GPU plugin remote context
26 * which is shared with OpenCL context object.
27 * The plugin object derived from this class can be obtained either with
28 * GetContext() method of Executable network or using CreateContext() Core call.
29 */
31 public:
32  /**
33  * @brief A smart pointer to the ClContext object
34  */
35  using Ptr = std::shared_ptr<ClContext>;
36 
37  /**
38  * @brief Returns the underlying OpenCL context handle.
39  */
40  cl_context get() {
41  return _ObjFromParams<cl_context, gpu_handle_param>(getParams(), GPU_PARAM_KEY(OCL_CONTEXT),
42  GPU_PARAM_KEY(CONTEXT_TYPE), GPU_PARAM_VALUE(OCL), GPU_PARAM_VALUE(VA_SHARED));
43  }
44 
45  /**
46  * @brief OpenCL context handle conversion operator for the ClContext object.
47  * @return Underlying OpenCL context handle
48  */
49  operator cl_context() {
50  return get();
51  }
52 
53  /**
54  * @brief Standard Khronos cl::Context wrapper conversion operator for the ClContext object.
55  * @return cl::Context object
56  */
57  operator cl::Context() {
58  return cl::Context(get(), true);
59  }
60 };
61 
62 /**
63 * @brief The basic class for all GPU plugin remote blob objects.
64 * The OpenCL memory object handle (cl_mem) can be obtained from this class object.
65 */
66 class ClBlob : public RemoteBlob {
67 public:
68  /**
69  * @brief A smart pointer to the ClBlob object
70  */
71  using Ptr = std::shared_ptr<ClBlob>;
72 
73  /**
74  * @brief Creates a ClBlob object with the specified dimensions and layout.
75  * @param tensorDesc Tensor description
76  */
77  explicit ClBlob(const TensorDesc& tensorDesc) : RemoteBlob(tensorDesc) {}
78 };
79 
80 /**
81 * @brief This class represents an abstraction for GPU plugin remote blob
82 * which can be shared with user-supplied OpenCL buffer.
83 * The plugin object derived from this class can be obtained with CreateBlob() call.
84 * @note User can obtain OpenCL buffer handle from this class.
85 */
87 public:
88  /**
89  * @brief A smart pointer to the ClBufferBlob object
90  */
91  using Ptr = std::shared_ptr<ClBufferBlob>;
92 
93  /**
94  * @brief Creates a ClBufferBlob object with the specified dimensions and layout.
95  * @param tensorDesc Tensor description
96  */
97  explicit ClBufferBlob(const TensorDesc& tensorDesc) : ClBlob(tensorDesc) {}
98 
99  /**
100  * @brief Returns the underlying OpenCL memory object handle.
101  */
102  cl_mem get() {
103  return _ObjFromParams<cl_mem, gpu_handle_param>(getParams(), GPU_PARAM_KEY(MEM_HANDLE),
104  GPU_PARAM_KEY(SHARED_MEM_TYPE), GPU_PARAM_VALUE(OCL_BUFFER), GPU_PARAM_VALUE(DX_BUFFER));
105  }
106 
107  /**
108  * @brief OpenCL memory handle conversion operator.
109  */
110  operator cl_mem() {
111  return get();
112  }
113 
114  /**
115  * @brief Standard Khronos cl::Buffer wrapper conversion operator.
116  * @return cl::Buffer object
117  */
118  operator cl::Buffer() {
119  return cl::Buffer(get(), true);
120  }
121 };
122 
123 /**
124 * @brief This class represents an abstraction for GPU plugin remote blob
125 * which can be shared with user-supplied OpenCL 2D Image.
126 * The plugin object derived from this class can be obtained with CreateBlob() call.
127 * @note User can obtain OpenCL image handle from this class.
128 */
130 public:
131  /**
132  * @brief A smart pointer to the ClImage2DBlob object
133  */
134  using Ptr = std::shared_ptr<ClImage2DBlob>;
135 
136  /**
137  * @brief Creates a ClImage2DBlob object with the specified dimensions and layout.
138  * @param tensorDesc Tensor description
139  */
140  explicit ClImage2DBlob(const TensorDesc& tensorDesc) : ClBlob(tensorDesc) {}
141 
142  /**
143  * @brief Returns the underlying OpenCL memory object handle.
144  */
145  cl_mem get() {
146  return _ObjFromParams<cl_mem, gpu_handle_param>(getParams(), GPU_PARAM_KEY(MEM_HANDLE),
147  GPU_PARAM_KEY(SHARED_MEM_TYPE), GPU_PARAM_VALUE(OCL_IMAGE2D), GPU_PARAM_VALUE(VA_SURFACE));
148  }
149 
150  /**
151  * @brief OpenCL memory handle conversion operator.
152  */
153  operator cl_mem() {
154  return get();
155  }
156 
157  /**
158  * @brief Standard Khronos cl::Image2D wrapper conversion operator for the ClContext object.
159  * @return cl::Image2D object
160  */
161  operator cl::Image2D() {
162  return cl::Image2D(get(), true);
163  }
164 };
165 
166 /**
167 * @brief This function is used to construct a NV12 compound blob object from two cl::Image2D wrapper objects.
168 * The resulting compound contains two remote blobs for Y and UV planes of the surface.
169 * @param ctx RemoteContext plugin object derived from ClContext class.
170 * @param nv12_image_plane_y cl::Image2D object containing Y plane data.
171 * @param nv12_image_plane_uv cl::Image2D object containing UV plane data.
172 * @return Pointer to plugin-specific context class object, which is derived from RemoteContext.
173 */
174 static inline Blob::Ptr make_shared_blob_nv12(RemoteContext::Ptr ctx, cl::Image2D& nv12_image_plane_y, cl::Image2D& nv12_image_plane_uv) {
175  auto casted = std::dynamic_pointer_cast<ClContext>(ctx);
176  if (nullptr == casted) {
177  THROW_IE_EXCEPTION << "Invalid remote context passed";
178  }
179 
180  size_t width = nv12_image_plane_y.getImageInfo<CL_IMAGE_WIDTH>();
181  size_t height = nv12_image_plane_y.getImageInfo<CL_IMAGE_HEIGHT>();
182 
183  // despite of layout, blob dimensions always follow in N,C,H,W order
184  TensorDesc ydesc(Precision::U8, { 1, 1, height, width }, Layout::NHWC);
185 
186  ParamMap blobParams = {
187  { GPU_PARAM_KEY(SHARED_MEM_TYPE), GPU_PARAM_VALUE(OCL_IMAGE2D) },
188  { GPU_PARAM_KEY(MEM_HANDLE), static_cast<gpu_handle_param>(nv12_image_plane_y.get()) }
189  };
190  Blob::Ptr y_blob = std::dynamic_pointer_cast<Blob>(casted->CreateBlob(ydesc, blobParams));
191 
192  TensorDesc uvdesc(Precision::U8, { 1, 2, height / 2, width / 2 }, Layout::NHWC);
193  blobParams[GPU_PARAM_KEY(MEM_HANDLE)] = static_cast<gpu_handle_param>(nv12_image_plane_uv.get());
194  Blob::Ptr uv_blob = std::dynamic_pointer_cast<Blob>(casted->CreateBlob(uvdesc, blobParams));
195 
196  Blob::Ptr res = make_shared_blob<NV12Blob>(y_blob, uv_blob);
197  return res;
198 }
199 
200 /**
201 * @brief This function is used to obtain remote context object from user-supplied OpenCL context handle
202 */
203 static inline RemoteContext::Ptr make_shared_context(Core& core, std::string deviceName, cl_context ctx) {
204  ParamMap contextParams = {
205  { GPU_PARAM_KEY(CONTEXT_TYPE), GPU_PARAM_VALUE(OCL) },
206  { GPU_PARAM_KEY(OCL_CONTEXT), static_cast<gpu_handle_param>(ctx) }
207  };
208  return core.CreateContext(deviceName, contextParams);
209 }
210 
211 /**
212 * @brief This function is used to create remote blob object within default GPU plugin OpenCL context
213 */
214 static inline Blob::Ptr make_shared_blob(const TensorDesc& desc, ClContext::Ptr ctx) {
215  return std::dynamic_pointer_cast<Blob>(ctx->CreateBlob(desc));
216 }
217 
218 /**
219 * @brief This function is used to obtain remote blob object from user-supplied cl::Buffer wrapper object
220 */
221 static inline Blob::Ptr make_shared_blob(const TensorDesc& desc, RemoteContext::Ptr ctx, cl::Buffer& buffer) {
222  auto casted = std::dynamic_pointer_cast<ClContext>(ctx);
223  if (nullptr == casted) {
224  THROW_IE_EXCEPTION << "Invalid remote context passed";
225  }
226 
227  ParamMap params = {
228  { GPU_PARAM_KEY(SHARED_MEM_TYPE), GPU_PARAM_VALUE(OCL_BUFFER) },
229  { GPU_PARAM_KEY(MEM_HANDLE), static_cast<gpu_handle_param>(buffer.get()) }
230  };
231  return std::dynamic_pointer_cast<Blob>(casted->CreateBlob(desc, params));
232 }
233 
234 /**
235 * @brief This function is used to obtain remote blob object from user-supplied OpenCL buffer handle
236 */
237 static inline Blob::Ptr make_shared_blob(const TensorDesc& desc, RemoteContext::Ptr ctx, cl_mem buffer) {
238  auto casted = std::dynamic_pointer_cast<ClContext>(ctx);
239  if (nullptr == casted) {
240  THROW_IE_EXCEPTION << "Invalid remote context passed";
241  }
242 
243  ParamMap params = {
244  { GPU_PARAM_KEY(SHARED_MEM_TYPE), GPU_PARAM_VALUE(OCL_BUFFER) },
245  { GPU_PARAM_KEY(MEM_HANDLE), static_cast<gpu_handle_param>(buffer) }
246  };
247  return std::dynamic_pointer_cast<Blob>(casted->CreateBlob(desc, params));
248 }
249 
250 /**
251 * @brief This function is used to obtain remote blob object from user-supplied cl::Image2D wrapper object
252 */
253 static inline Blob::Ptr make_shared_blob(const TensorDesc& desc, RemoteContext::Ptr ctx, cl::Image2D& image) {
254  auto casted = std::dynamic_pointer_cast<ClContext>(ctx);
255  if (nullptr == casted) {
256  THROW_IE_EXCEPTION << "Invalid remote context passed";
257  }
258 
259  ParamMap params = {
260  { GPU_PARAM_KEY(SHARED_MEM_TYPE), GPU_PARAM_VALUE(OCL_IMAGE2D) },
261  { GPU_PARAM_KEY(MEM_HANDLE), static_cast<gpu_handle_param>(image.get()) }
262  };
263  return std::dynamic_pointer_cast<Blob>(casted->CreateBlob(desc, params));
264 }
265 
266 }; // namespace gpu
267 
268 }; // namespace InferenceEngine
#define THROW_IE_EXCEPTION
A macro used to throw the exception with a notable description.
Definition: ie_exception.hpp:25
RemoteContext::Ptr CreateContext(const std::string &deviceName, const ParamMap &params)
Create a new shared context object on specified accelerator device using specified plugin-specific lo...
This class represents Inference Engine Core entity.
Definition: ie_core.hpp:51
A header file for CompoundBlob.
Definition: cldnn_config.hpp:16
ClImage2DBlob(const TensorDesc &tensorDesc)
Creates a ClImage2DBlob object with the specified dimensions and layout.
Definition: gpu_context_api_ocl.hpp:140
static Blob::Ptr make_shared_blob_nv12(RemoteContext::Ptr ctx, cl::Image2D &nv12_image_plane_y, cl::Image2D &nv12_image_plane_uv)
This function is used to construct a NV12 compound blob object from two cl::Image2D wrapper objects...
Definition: gpu_context_api_ocl.hpp:174
std::shared_ptr< ClBlob > Ptr
A smart pointer to the ClBlob object.
Definition: gpu_context_api_ocl.hpp:71
ClBlob(const TensorDesc &tensorDesc)
Creates a ClBlob object with the specified dimensions and layout.
Definition: gpu_context_api_ocl.hpp:77
a header for properties of shared device contexts and shared device memory blobs for clDNN plugin ...
This class represents an abstraction for GPU plugin remote blob which can be shared with user-supplie...
Definition: gpu_context_api_ocl.hpp:129
The basic class for all GPU plugin remote blob objects. The OpenCL memory object handle (cl_mem) can ...
Definition: gpu_context_api_ocl.hpp:66
This is a header file for the Inference Engine Core class C++ API.
This class defines Tensor description.
Definition: ie_layouts.h:153
#define GPU_PARAM_VALUE(name)
Shortcut for defining configuration values.
Definition: gpu_params.hpp:32
This class represents an abstraction for GPU plugin remote context which is shared with OpenCL contex...
Definition: gpu_context_api_ocl.hpp:30
static RemoteContext::Ptr make_shared_context(Core &core, std::string deviceName, cl_context ctx)
This function is used to obtain remote context object from user-supplied OpenCL context handle...
Definition: gpu_context_api_ocl.hpp:203
std::map< std::string, Parameter > ParamMap
An std::map object containing low-level object parameters of classes that are derived from RemoteBlob...
Definition: ie_remote_context.hpp:26
std::shared_ptr< Blob > Ptr
A smart pointer containing Blob object.
Definition: ie_blob.h:42
static Blob::Ptr make_shared_blob(const TensorDesc &desc, ClContext::Ptr ctx)
This function is used to create remote blob object within default GPU plugin OpenCL context...
Definition: gpu_context_api_ocl.hpp:214
virtual ParamMap getParams() const =0
Returns a map of device-specific parameters required for low-level operations with underlying object...
This wrapper class is used to obtain low-level handles from remote blob or context object parameters...
Definition: gpu_context_helpers.hpp:23
Definition: ie_precision.hpp:33
std::shared_ptr< ClContext > Ptr
A smart pointer to the ClContext object.
Definition: gpu_context_api_ocl.hpp:35
This class represents an Inference Engine abstraction for remote (non-CPU) accelerator device-specifi...
Definition: ie_remote_context.hpp:94
This class represents a universal container in the Inference Engine.
Definition: ie_blob.h:37
ClBufferBlob(const TensorDesc &tensorDesc)
Creates a ClBufferBlob object with the specified dimensions and layout.
Definition: gpu_context_api_ocl.hpp:97
a header that defines helpers for GPU plugin-specific wrappers
#define GPU_PARAM_KEY(name)
Shortcut for defining configuration keys.
Definition: gpu_params.hpp:27
std::map< std::string, std::string > params
Map of pairs: (parameter name, parameter value)
Definition: ie_layers.h:367
std::shared_ptr< RemoteContext > Ptr
A smart pointer to the RemoteContext object.
Definition: ie_remote_context.hpp:99
This class represents an abstraction for GPU plugin remote blob which can be shared with user-supplie...
Definition: gpu_context_api_ocl.hpp:86
This class represents an Inference Engine abstraction to the memory allocated on the remote (non-CPU)...
Definition: ie_remote_context.hpp:31
void * gpu_handle_param
Shortcut for defining a handle parameter.
Definition: gpu_params.hpp:20