Debian Codegraph @

media_driver/linux/common/cm/hal/cm_device.h

raw
1 /*
2 * Copyright (c) 2007-2017, Intel Corporation
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included
12 * in all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
17 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
18 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20 * OTHER DEALINGS IN THE SOFTWARE.
21 */
22 //!
23 //! \file cm_device.h
24 //! \brief Contains CmDevice declarations.
25 //!
26
27 #ifndef MEDIADRIVER_LINUX_COMMON_CM_CMDEVICE_H_
28 #define MEDIADRIVER_LINUX_COMMON_CM_CMDEVICE_H_
29
30 #include "cm_def.h"
31 #include "mos_os.h"
32
33 namespace CMRT_UMD
34 {
35 class CmQueue;
36 class CmKernel;
37 class CmThreadSpace;
38 class CmThreadGroupSpace;
39 class CmVebox;
40 class CmSampler;
41 class CmEvent;
42 class CmTask;
43 class CmProgram;
44 class CmBuffer;
45 class CmBufferUP;
46 class CmBufferSVM;
47 class CmSurface2D;
48 class CmSurface2DUP;
49 class CmSurface2DUPRT;
50 class CmSurface3D;
51 class CmSampler8x8;
52 class CmBufferStateless;
53
54 //! \brief CmDevice class \@UMD for Linux
55 class CmDevice
56 {
57 public:
58 //!
59 //! \brief Creates a CmBuffer with specified size in bytes.
60 //! \details This function creates a buffer in video memory with linear
61 //! layout.
62 //! \param [in] size
63 //! Buffer size in bytes.
64 //! \param [out] surface
65 //! Reference to the pointer to the CmBuffer.
66 //! \retval CM_SUCCESS if the CmBuffer is successfully created.
67 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
68 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D
69 //! surface fails.
70 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
71 //! larger than CM_MAX_1D_SURF_WIDTH.
72 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces
73 //! is exceeded. The amount is the amount of the surfaces
74 //! that can co-exist. The amount can be obtained by querying
75 //! the cap CAP_BUFFER_COUNT.
76 //! \retval CM_FAILURE otherwise.
77 //!
78 CM_RT_API virtual int32_t CreateBuffer(uint32_t size,
79 CmBuffer* &surface) = 0;
80
81 //!
82 //! \brief Creates a CmBuffer from an existing MOS Resource.
83 //! \details CmBuffer is a wrapper of that MOS resource. This Mos resource is
84 //! owned by caller.
85 //! \param [in] mosResource
86 //! pointer to MOS resource.
87 //! \param [in,out] surface
88 //! reference to pointer of surface to be created.
89 //! \retval CM_SUCCESS if the CmBuffer is successfully created.
90 //! \retval CM_INVALID_MOS_RESOURCE_HANDLE if mosResource is nullptr.
91 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory
92 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces is exceeded.
93 //! \retval CM_FAILURE otherwise
94 //!
95 CM_RT_API virtual int32_t CreateBuffer(PMOS_RESOURCE mosResource,
96 CmBuffer* &surface) = 0;
97
98 //!
99 //! \brief Creates a CmSurface2D with given width, height, and format.
100 //! \details This function creates a surface in video memory with a 2D layout.
101 //! User needs to provide width, height and format.
102 //! \param [in] width
103 //! Surface width in pixel.
104 //! \param [in] height
105 //! Surface height in pixel.
106 //! \param [in] format
107 //! Surface format.
108 //! \param [out] surface
109 //! Reference to the pointer to the CmSurface2D.
110 //! \retval CM_SUCCESS if the CmSurface2D is successfully created.
111 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
112 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath
113 //! resource fails.
114 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
115 //! larger than CM_MAX_2D_SURF_WIDTH, or for YUY2, or NV12
116 //! format, the width is odd.
117 //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT
118 //! or larger than CM_MAX_2D_SURF_HEIGHT, or for NV12 format,
119 //! the height is odd.
120 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not
121 //! supported. The supported formats can be obtained by
122 //! querying cap CAP_SURFACE2D_FORMAT_COUNT and
123 //! CAP_SURFACE2D_FORMATS. For now, the following formats are
124 //! supported: \n
125 //! CM_SURFACE_FORMAT_A8R8G8B8, \n
126 //! CM_SURFACE_FORMAT_X8R8G8B8, \n
127 //! CM_SURFACE_FORMAT_A8B8G8R8, \n
128 //! CM_SURFACE_FORMAT_R32F, \n
129 //! CM_SURFACE_FORMAT_V8U8, \n
130 //! CM_SURFACE_FORMAT_P8, \n
131 //! CM_SURFACE_FORMAT_YUY2, \n
132 //! CM_SURFACE_FORMAT_A8, \n
133 //! CM_SURFACE_FORMAT_NV12, \n
134 //! CM_SURFACE_FORMAT_P010, \n
135 //! CM_SURFACE_FORMAT_UYVY, \n
136 //! CM_SURFACE_FORMAT_IMC3, \n
137 //! CM_SURFACE_FORMAT_411P, \n
138 //! CM_SURFACE_FORMAT_422H, \n
139 //! CM_SURFACE_FORMAT_422V, \n
140 //! CM_SURFACE_FORMAT_444P, \n
141 //! CM_SURFACE_FORMAT_YV12, \n
142 //! CM_SURFACE_FORMAT_R8_UINT, \n
143 //! CM_SURFACE_FORMAT_R16_UINT. \n
144 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces
145 //! is exceeded. The amount is the amount of the surfaces that
146 //! can co-exist. The amount can be obtained by querying the
147 //! cap CAP_SURFACE2D_COUNT.
148 //! \retval CM_FAILURE otherwise.
149 //! \note For planar surface, there is only one CmSurface2D instance,
150 //! no matter how many planes the surface may have.
151 //! The detail about how to access different planes in the kernel
152 //! code can be found in CM Language Spec, looking for read_plane
153 //! and write_plane.
154 //!
155 CM_RT_API virtual int32_t CreateSurface2D(uint32_t width,
156 uint32_t height,
157 CM_SURFACE_FORMAT format,
158 CmSurface2D* &surface) = 0;
159
160 //!
161 //! \brief Creates a CmSurface2D from an existing MOS Resource.
162 //! \details CmSurface2D is a wrapper of that MOS resource. This Mos resource is
163 //! owned by caller.
164 //! \param [in] mosResource
165 //! pointer to MOS resource.
166 //! \param [in,out] surface
167 //! reference to pointer of surface to be created.
168 //! \retval CM_SUCCESS if the CmSurface2D is successfully created.
169 //! \retval CM_INVALID_MOS_RESOURCE_HANDLE if pMosResrouce is nullptr.
170 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces
171 //! is exceeded.
172 //! \retval CM_FAILURE otherwise.
173 //!
174 CM_RT_API virtual int32_t CreateSurface2D(PMOS_RESOURCE mosResource,
175 CmSurface2D* &surface) = 0;
176
177 //!
178 //! \brief Creates a CmSurface2D from an existing VA surface.
179 //! \details The application must have created the VA surface using the
180 //! VADriverContext used to create CmDevice. The VA surface format
181 //! should be within the supported format set which can be obtained
182 //! by querying cap CAP_SURFACE2D_FORMAT_COUNT and CAP_SURFACE2D_FORMATS.
183 //! \param [in] vaSurface
184 //! indext to VA surface.
185 //! \param [in] vaDriverCtx
186 //! pointer to VA driver context.
187 //! \param [in,out] surface
188 //! reference to pointer of surface to be created.
189 //! \retval CM_SUCCESS if the CmSurface2D is successfully created.
190 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces
191 //! is exceeded.
192 //! \retval CM_FAILURE otherwise.
193 //!
194 CM_RT_API virtual int32_t CreateSurface2D(VASurfaceID vaSurface,
195 VADriverContext *vaDriverCtx,
196 CmSurface2D* &surface) = 0;
197
198 //!
199 //! \brief Creates a CmSurface3D with given width, height, depth and
200 //! pixel format.
201 //! \details This function creates a surface in memory with a 3D layout.
202 //! User needs to provide width, height, depth and format.
203 //! \param [in] width
204 //! Surface width.
205 //! \param [in] height
206 //! Surface height.
207 //! \param [in] depth
208 //! Surface depth.
209 //! \param [in] format
210 //! Surface format.
211 //! \param [out] surface
212 //! Reference to the pointer to the CmSurface3D.
213 //! \retval CM_SUCCESS if the CmSurface3D is successfully created.
214 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
215 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
216 //! larger than CM_MAX_3D_SURF_WIDTH.
217 //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT
218 //! or larger than CM_MAX_3D_SURF_HEIGHT.
219 //! \retval CM_INVALID_DEPTH if width is less than CM_MIN_SURF_DEPTH or
220 //! larger than CM_MAX_3D_SURF_DEPTH.
221 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not
222 //! supported. The supported formats can be obtained by
223 //! querying cap CAP_SURFACE3D_FORMAT_COUNT and
224 //! CAP_SURFACE3D_FORMATS, For now, only supports: \n
225 //! CM_SURFACE_FORMAT_X8R8G8B8, \n
226 //! CM_SURFACE_FORMAT_A8R8G8B8, \n
227 //! CM_SURFACE_FORMAT_A16B16G16R16. \n
228 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 3D
229 //! surface fails.
230 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 3D surfaces
231 //! is exceeded. The amount is the amount of the surfaces that
232 //! can co-exist. The amount can be obtained by querying the
233 //! cap CAP_SURFACE3D_COUNT.
234 //! \retval CM_FAILURE otherwise.
235 //!
236 CM_RT_API virtual int32_t CreateSurface3D(uint32_t width,
237 uint32_t height,
238 uint32_t depth,
239 CM_SURFACE_FORMAT format,
240 CmSurface3D* &surface) = 0;
241
242 //!
243 //! \brief Destroys CmBuffer object.
244 //! \details This function destroys CmBuffer object. After the function
245 //! is called, it will return immediately without waiting. If
246 //! there is any Enqueue is being executed when this function
247 //! is called, the actual destroy will be postponed internally
248 //! by the runtime, and user doens't need to worry about it.
249 //! \param [in,out] surface
250 //! Reference to the pointer pointing to CmBuffer, it will be
251 //! assigned to nullptr after destroy.
252 //! \retval CM_SUCCESS if CmBuffer is successfully destroyed.
253 //! \retval CM_FAILURE otherwise.
254 //!
255 CM_RT_API virtual int32_t DestroySurface(CmBuffer* &surface) = 0;
256
257 //!
258 //! \brief Destroys CmSurface2D type surface.
259 //! \details This function destroys CmSurface2D object. After the function
260 //! is called, it will return immediately without waiting. If
261 //! there is any Enqueue is being executed when this function is
262 //! called, the actual destroy will be postponed internally by
263 //! the runtime, and user doens't need to worry about it. One
264 //! exception is that if the CmSurface2D was created by a third
265 //! party VA surface, user has to keep the VA surface until the
266 //! kernel using it finishes execution.
267 //! \param [in,out] surface
268 //! Reference to the pointer pointing to CmSurface2D. It will
269 //! be assigned to nullptr after destroy.
270 //! \retval CM_SUCCESS if CmSurface2D is successfully destroyed.
271 //! \retval CM_FAILURE otherwise.
272 //!
273 CM_RT_API virtual int32_t DestroySurface(CmSurface2D* &surface) = 0;
274
275 //!
276 //! \brief Destroys CmSurface3D object.
277 //! \details This function destroys CmSurface3D object. After the
278 //! function is called, it will return immediately without
279 //! waiting. If there is any Enqueue is being executed when this
280 //! function is called, the actual destroy will be postponed
281 //! internally by the runtime, and user doens't need to worry
282 //! about it.
283 //! \param [in,out] surface
284 //! Reference to the pointer pointing to CmSurface3D. It will
285 //! be assigned to nullptr after destroy.
286 //! \retval CM_SUCCESS if CmSurface3D is successfully destroyed.
287 //! \retval CM_FAILURE otherwise.
288 //!
289 CM_RT_API virtual int32_t DestroySurface(CmSurface3D* &surface) = 0;
290
291 //!
292 //! \brief Creates a task queue.
293 //! \details CmQueue is an in-order queue of tasks. Each task is
294 //! essentially a CmTask object containing kernels that are to
295 //! be run concurrently. Each kernel can be executed with
296 //! multiple threads. Only one CmQueue is supported per CmDevice for now.
297 //! Trying to create a second CmQueue will return a previously
298 //! created CmQueue object.
299 //! \param [in,out] queue
300 //! Reference to the pointer to the CmQueue.
301 //! \retval CM_SUCCESS if the CmQueue is successfully created.
302 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
303 //! \retval CM_FAILURE otherwise.
304 //!
305 CM_RT_API virtual int32_t CreateQueue(CmQueue* &queue) = 0;
306
307 //!
308 //! \brief Creates a CmProgram object consisting of kernels loaded from
309 //! the commonIsaCode code.
310 //! \details Common ISA code is offline generated as a file with a .isa suffix
311 //! by the CM compiler when it is used to compile one or more
312 //! kernels. It contains ISA code common for all Intel platforms.
313 //! Just-In-Time (JIT) compilation of the common ISA code happens in
314 //! LoadProgram and generates platform specific ISA according to the
315 //! actaully platform where the application in running in hardware mode.
316 //! In the emulation mode JIT doesn't happen.
317 //! In the simulation mode JIT doesn't happen but paltform specfic
318 //! ISA need to be offline generated together with common ISA by
319 //! CM compiler and to be included in commonIsaCode.
320 //! How to generate common ISA and platform specific ISA can be
321 //! found in CM compiler manual.
322 //! \param [in] commonIsaCode
323 //! Pointer pointing to code in common ISA.
324 //! \param [in] size
325 //! Size in bytes of the common ISA code.
326 //! \param [in,out] program
327 //! Reference to the pointer to the CmProgram.
328 //! \param [in] options
329 //! JIT options for all kernels in the code. This argument
330 //! is optional. Size of options should be no more than 512
331 //! (CM_MAX_OPTION_SIZE_IN_BYTE) bytes including the null
332 //! terminator. There is one option available currently: \n
333 //! "nojitter" -- Use this option to completely disable jitter
334 //! from occurring. NOTE: "/Qxcm_jit_tartget=%GEN_ARCH%"
335 //! flag must be set during offline compilation if "nojitter"
336 //! is set in hardware mode.
337 //! In simulation and emulation mode, this option is ignored.
338 //! \retval CM_SUCCESS if the CmProgram is successfully created.
339 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
340 //! \retval CM_INVALID_ARG_VALUE if invalid input parameters.
341 //! \retval CM_INVALID_GENX_BINARY if the GEN binary is not matched with
342 //! actual running platform in "nojitter" mode.
343 //! \retval CM_JIT_COMPILE_FAILURE if JIT compile of the common ISA
344 //! code fails.
345 //! \retval CM_INVALID_KERNEL_SPILL_CODE if kernel has spill code and
346 //! devcie's scratch memory space is disabled in
347 //! CreateCmDeviceEx.
348 //! \retval CM_FAILURE otherwise.
349 //!
350 CM_RT_API virtual int32_t LoadProgram(void *commonIsaCode,
351 const uint32_t size,
352 CmProgram* &program,
353 const char *options = nullptr) = 0;
354
355 //!
356 //! \brief Creates a CmKernel object from the CmProgram object.
357 //! \details A Cmprogram can contains multiple kernels.
358 //! The size of all arguments of a kernel should be no more than
359 //! CAP_ARG_SIZE_PER_KERNEL byte. The number of all kernel
360 //! arguments should be no more than CAP_ARG_COUNT_PER_KERNEL.
361 //! The size of kernel binary should be no more than
362 //! CAP_KERNEL_BINARY_SIZE bytes. The kernelName should be no
363 //! more than 256 (CM_MAX_KERNEL_NAME_SIZE_IN_BYTE) bytes
364 //! including the null terminator.
365 //! \param [in] program
366 //! CmProgram object from which the kernel is created.
367 //! \param [in] kernelName
368 //! CM kernel function (genx_main) name. A CM_KERNEL_FUNCTION
369 //! macro MUST be used to specify this argument.
370 //! \param [in,out] kernel
371 //! Reference to the pointer to the CmKernel object.
372 //! \param [in] options
373 //! JIT options for this specific kernel, overwriting the JIT
374 //! options specified for all kernels in the CmProgram. This
375 //! argument is optional. Size of options should be no more
376 //! than 512 (CM_MAX_OPTION_SIZE_IN_BYTE) bytes including the
377 //! null terminator. No options available for now.
378 //! \retval CM_SUCCESS if the CmKernel is successfully created or
379 //! returned.
380 //! \retval CM_INVALID_ARG_VALUE if the program is an invalid pointer.
381 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
382 //! \retval CM_EXCEED_KERNEL_ARG_AMOUNT if the argument number of the
383 //! kernel fucntion is larger than CAP_ARG_COUNT_PER_KERNEL.
384 //! \retval CM_EXCEED_KERNEL_ARG_SIZE_IN_BYTE if the argument size of
385 //! the kernel fucntion is larger than CAP_ARG_SIZE_PER_KERNEL.
386 //! \retval CM_FAILURE otherwise.
387 //!
388 CM_RT_API virtual int32_t CreateKernel(CmProgram *program,
389 const char *kernelName,
390 CmKernel* &kernel,
391 const char *options = nullptr) = 0;
392
393 //!
394 //! \brief Creates a CmSampler object.
395 //! \details This function creates a 3D sampler state object used to sample
396 //! a 2D surface.
397 //! \param [in] sampleState
398 //! Const reference to a CM_SAMPLER_STATE specifying the
399 //! characteristics of the sampler to be created. The structure
400 //! is defined below.
401 //! \param [out] sampler
402 //! Reference to the pointer to the CmSampler object.
403 //! \retval CM_SUCCESS if the CmSampler is successfully created.
404 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
405 //! \retval CM_EXCEED_SAMPLER_AMOUNT if maximum amount of sampler is
406 //! exceeded. The amount is the amount of the sampler that can
407 //! co-exist. The amount can be obtained by querying the cap
408 //! CAP_SAMPLER_COUNT.
409 //! \retval CM_FAILURE otherwise.
410 //! \note typedef struct _CM_SAMPLER_STATE\n
411 //! {\n
412 //! CM_TEXTURE_FILTER_TYPE minFilterType;\n
413 //! CM_TEXTURE_FILTER_TYPE magFilterType;\n
414 //! CM_TEXTURE_ADDRESS_TYPE addressU;\n
415 //! CM_TEXTURE_ADDRESS_TYPE addressV;\n
416 //! CM_TEXTURE_ADDRESS_TYPE addressW;\n
417 //! } CM_SAMPLER_STATE;\n
418 //!
419 //! For now, only linear and anisotropic filter types are
420 //! supported for hardware and simulation modes. For emulation
421 //! mode, linear filter type is supported. Wrap, mirror, and
422 //! clamp address types are supported in hardware and simulation modes.
423 //! only clamp address type is supported in emulation mode.
424 //!
425 CM_RT_API virtual int32_t
426 CreateSampler(const CM_SAMPLER_STATE &sampleState,
427 CmSampler* &sampler) = 0;
428
429 //!
430 //! \brief Destroys a CmKernel.
431 //! \details A CmKernel that is not destroyed by calling this function
432 //! will be destroyed when the CmDevice is destroyed.
433 //! \param [in,out] kernel
434 //! CmKernel object to be destroyed. It will be assigned to
435 //! nullptr once the fuction is return.
436 //! \retval CM_SUCCESS if the CmKernel is successfully destroyed.
437 //! \retval CM_FAILURE otherwise.
438 //!
439 CM_RT_API virtual int32_t DestroyKernel(CmKernel* &kernel) = 0;
440
441 //!
442 //! \brief Destroys a CmSampler.
443 //! \details A CmSampler that is not destroyed by calling this function
444 //! will be destroyed when the CmDevice is destroyed.
445 //! \param [in,out] sampler
446 //! A reference to the CmSampler pointer.
447 //! \retval CM_SUCCESS if the CmSampler is successfully destroyed.
448 //! \retval CM_FAILURE otherwise.
449 //!
450 CM_RT_API virtual int32_t DestroySampler(CmSampler* &sampler) = 0;
451
452 //!
453 //! \brief Destroys a CmProgram.
454 //! \details A CmProgram that is not destroyed by calling this function
455 //! will be destroyed when the CmDevice is destroyed.
456 //! \param [in,out] program
457 //! Reference to the pointer to the CmProgram. It will be assigned to
458 //! nullptr once the fuction is return.
459 //! \retval CM_SUCCESS if the CmProgram is successfully destroyed.
460 //! \retval CM_FAILURE otherwise.
461 //!
462 CM_RT_API virtual int32_t DestroyProgram(CmProgram* &program) = 0;
463
464 //!
465 //! \brief Destroys a CmThreadSpace instance.
466 //! \details A CmThreadSpace that is not destroyed by calling this
467 //! function will be destroyed when the CmDevice is destroyed.
468 //! \param [in,out] threadSpace
469 //! Reference to the pointer to the CmThreadSpace. It will be
470 //! assigned to nullptr once the fuction is return.
471 //! \retval CM_SUCCESS if the CmThreadSpace is successfully destroyed.
472 //! \retval CM_FAILURE if the input is nullptr or not valid.
473 //!
474 CM_RT_API virtual int32_t DestroyThreadSpace(CmThreadSpace* &threadSpace) = 0;
475
476 //!
477 //! \brief Creates a CmTask object
478 //! \details This object is a container for one or multiple CmKernel objects, and used
479 //! to enqueue the kernels for concurrent execution.
480 //! \param [out] task Reference to the pointer to the CmTask
481 //! \retval CM_SUCCESS if the CmTask is successfully created
482 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory
483 //!
484 CM_RT_API virtual int32_t CreateTask(CmTask* &task) = 0;
485
486 //!
487 //! \brief Destroy a CmTask object
488 //! \details A CmTask that is not destroyed by calling this
489 //! function will be destroyed when the CmDevice is destroyed
490 //! \param [in, out] task Reference to the pointer to the CmTask.
491 //! \retval CM_SUCCESS if the CmTaskis successfully destroyed
492 //! \retval CM_FAILURE otherwise
493 //!
494 CM_RT_API virtual int32_t DestroyTask(CmTask* &task) = 0;
495
496 //!
497 //! \brief This function can be used to get HW capability.
498 //! \details Since Emulation mode is run during kernel
499 //! development the values returned in Emulation mode reflect the
500 //! capabilities at that time, and might not reflect
501 //! the latest HW capabilities using a later driver release
502 //! \param [in] capName Name of cap to query
503 //! \param [out] capValueSize Reference to the size in bytes of the Cap
504 //! value. On entry application should set this to the size
505 //! of memory allocated for the cap value. Application should
506 //! make sure this size is large enough to hold the Cap value
507 //! requested. On return from this function the actual size of
508 //! cap value is returned
509 //! \param [out] capValue Pointer pointing to memory where the
510 //! cap value should be returned
511 //! \retval CM_SUCCESS if the input capValueSize equals or
512 //! is larger than required Cap size and Cap Value
513 //! is successfully returned,
514 //! \retval CM_FAILURE otherwise
515 //! \details
516 //! <table>
517 //! <tr>
518 //! <th>Cap Name</th>
519 //! <th>Size in bytes </th>
520 //! <th>Type of Value</th>
521 //! <th>Description</th>
522 //! </tr>
523 //! <tr>
524 //! <td>CAP_KERNEL_COUNT_PER_TASK</td>
525 //! <td>4</td>
526 //! <td>uint32_t</td>
527 //! <td>Maximum number of kernels that can be enqueued in one task</td>
528 //! </tr>
529 //! <tr>
530 //! <td> CAP_KERNEL_BINARY_SIZE</td>
531 //! <td>4</td>
532 //! <td>uint32_t</td>
533 //! <td> Maximum kernel binary size in bytes</td>
534 //! </tr>
535 //! <tr>
536 //! <td> CAP_SAMPLER_COUNT</td>
537 //! <td>4</td>
538 //! <td>uint32_t</td>
539 //! <td> Maximum number of samplers that can co-exist at any time
540 //! in a CmDevice</td>
541 //! </tr>
542 //! <tr>
543 //! <td>CAP_SAMPLER_COUNT_PER_KERNEL </td>
544 //! <td>4</td>
545 //! <td>uint32_t</td>
546 //! <td>Maximum number of samplers that one kernel can use</td>
547 //! </tr>
548 //! <tr>
549 //! <td>CAP_BUFFER_COUNT </td>
550 //! <td>4</td>
551 //! <td>uint32_t</td>
552 //! <td>Maximum number of CmBuffer that can co - exist at any time </td>
553 //! </tr>
554 //! <tr>
555 //! <td> CAP_SURFACE2D_COUNT</td>
556 //! <td>4</td>
557 //! <td>uint32_t</td>
558 //! <td>Maximum number of CmSurface2D that can co-exist at
559 //! any time </td>
560 //! </tr>
561 //! <tr>
562 //! <td>CAP_SURFACE3D_COUNT </td>
563 //! <td>4</td>
564 //! <td>uint32_t</td>
565 //! <td>Maximum number of CmSurface3D that can co-exist at any
566 //! time in a CmDevice </td>
567 //! </tr>
568 //! <tr>
569 //! <td>CAP_SURFACE_COUNT_PER_KERNEL </td>
570 //! <td>4</td>
571 //! <td>uint32_t</td>
572 //! <td>Maximum number of surfaces (including 1D, 2D and 3D) that
573 //! one kernel can use </td>
574 //! </tr>
575 //! <tr>
576 //! <td>CAP_ARG_COUNT_PER_KERNEL </td>
577 //! <td>4</td>
578 //! <td>uint32_t</td>
579 //! <td>Maximum number of arguments that a kernel can have </td>
580 //! </tr>
581 //! <tr>
582 //! <td>CAP_ARG_SIZE_PER_KERNEL </td>
583 //! <td>4</td>
584 //! <td>uint32_t</td>
585 //! <td>Maximum size of all arguments that a kernel can have </td>
586 //! </tr>
587 //! <tr>
588 //! <td>CAP_USER_DEFINED_THREAD_COUNT_PER_TASK </td>
589 //! <td>4</td>
590 //! <td>uint32_t</td>
591 //! <td>Maximum number of threads that all kernels of a task can
592 //! run, it's only used for media object usage </td>
593 //! </tr>
594 //! <tr>
595 //! <td>CAP_HW_THREAD_COUNT </td>
596 //! <td>4</td>
597 //! <td>uint32_t</td>
598 //! <td>Maximum number of threads that HW can run in parallel.This
599 //! indicates hardware parallelism and is hence one
600 //! of the factors indicating performance of the target machine </td>
601 //! <tr>
602 //! <td>CAP_SURFACE2D_FORMAT_COUNT </td>
603 //! <td>4</td>
604 //! <td>uint32_t</td>
605 //! <td>Number of DDI formats supported for CmSurface2D creation </td>
606 //! <tr>
607 //! <td>CAP_SURFACE2D_FORMATS </td>
608 //! <td>sizeof(DDIFORMAT) * CAP_SURFACE2D_FORMAT_COUNT</td>
609 //! <td>Array of DDIFORMAT</td>
610 //! <td>All DDI format supported to create CmSurface2D </td>
611 //! <tr>
612 //! <td>CAP_SURFACE3D_FORMAT_COUNT </td>
613 //! <td>sizeof(DDIFORMAT) * CAP_SURFACE3D_FORMAT_COUNT</td>
614 //! <td>Array of DDIFORMAT</td>
615 //! <td>Number of DDI formats supported for CmSurface3D creation </td>
616 //! <tr>
617 //! <td>CAP_SURFACE3D_FORMATS </td>
618 //! <td>sizeof(DDIFORMAT) * CAP_SURFACE3D_FORMAT_COUNT</td>
619 //! <td>Array of DDIFORMAT</td>
620 //! <td>All DDI format supported to create CmSurface3D </td>
621 //! <tr>
622 //! <td>CAP_VME_STATE_COUNT </td>
623 //! <td>4</td>
624 //! <td>uint32_t</td>
625 //! <td>Maximum number of VME states that can co - exist
626 //! at any time in a CmDevice </td>
627 //! <tr>
628 //! <td>CAP_GPU_PLATFORM </td>
629 //! <td>4</td>
630 //! <td>uint32_t</td>
631 //! <td>Return GPU platform as an enum of type GPU_PLATFORM
632 //! (PLATFORM_INTEL_SNB, PLATFORM_INTEL_IVB, etc) </td>
633 //! <tr>
634 //! <td>CAP_GT_PLATFORM </td>
635 //! <td>4</td>
636 //! <td>uint32_t</td>
637 //! <td>Return GT platform (SKU) as an enum of type GPU_GT_PLATFORM
638 //! (PLATFORM_INTEL_GT1, PLATFORM_INTEL_GT2, etc) </td>
639 //! <tr>
640 //! <td>CAP_MIN_FREQUENCY </td>
641 //! <td>4</td>
642 //! <td>uint32_t</td>
643 //! <td>Returns the minimum frequency of the GPU as an integer in MHz
644 //! </td>
645 //! <tr>
646 //! <td>CAP_MAX_FREQUENCY </td>
647 //! <td>4</td>
648 //! <td>uint32_t</td>
649 //! <td>Returns the maximum frequency of the GPU as an integer in MHz
650 //! </td>
651 //! <tr>
652 //! <td>CAP_GPU_CURRENT_FREQUENCY </td>
653 //! <td>4</td>
654 //! <td>uint32_t</td>
655 //! <td>Return the current frequency of the GPU as an integer
656 //! in MHz </td>
657 //! </tr>
658 //! <tr>
659 //! <td>CAP_USER_DEFINED_THREAD_COUNT_PER_TASK_NO_THREAD_ARG </td>
660 //! <td>4</td>
661 //! <td>uint32_t</td>
662 //! <td>Returns the maximum thread count on media object without
663 //! per - thread argument </td>
664 //! </tr>
665 //! <tr>
666 //! <td>CAP_USER_DEFINED_THREAD_COUNT_PER_MEDIA_WALKER </td>
667 //! <td>4</td>
668 //! <td>uint32_t</td>
669 //! <td>Returns the maximum thread count in media walker usage </td>
670 //! </tr>
671 //! <tr>
672 //! <td>CAP_USER_DEFINED_THREAD_COUNT_PER_THREAD_GROUP </td>
673 //! <td>4</td>
674 //! <td>uint32_t</td>
675 //! <td>Returns the maximum thread count per thread group in
676 //! GPGPU walker usage </td>
677 //! </tr>
678 //! <tr>
679 //! <td>CAP_SURFACE2DUP_COUNT </td>
680 //! <td>4</td>
681 //! <td>uint32_t</td>
682 //! <td>Maximum number of CmSurface2DUP that can
683 //! co - exist at any time </td>
684 //! </tr>
685 //! </table>
686 //!
687 CM_RT_API virtual int32_t GetCaps(CM_DEVICE_CAP_NAME capName,
688 uint32_t &capValueSize,
689 void *capValue) = 0;
690
691 //!
692 //! \brief Creates a CmThreadSpace object.
693 //! \details CmThreadSpace is a 2D space.Each unit is notated as
694 //! a pair of X/Y coordinates, which is in the range of [0, width -1]
695 //! or [0, heigh-1]. A thread space can define a dependency or no
696 //! dependency. A thread space can be used as per-task thread space
697 //! by passing it in Enqueue(), or be used as per-kernel thread space
698 //! by calling CmKernel::AssociateThreadSpace() API. Please
699 //! refer to "Host programming guide" for detailed thread space usages.
700 //! \param [in] width
701 //! Thread space width.
702 //! \param [in] height
703 //! Thread space height.
704 //! \param [out] threadSpace
705 //! Reference to pointer to CmThreadSpace object to be created.
706 //! \retval CM_SUCCESS if the CmThreadSpace is successfully created.
707 //! \retval CM_INVALID_THREAD_SPACE if the width or(and) height are
708 //! \retval invalid values (0 or exceeds maximum size).
709 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
710 //! \retval CM_FAILURE otherwise.
711 //! \note The maximum width/height allowed when using media walker is
712 //! 511 for pre-SKL and 2047 for SKL+. For media object the
713 //! maximum width/height allowed is 512.
714 //!
715 CM_RT_API virtual int32_t CreateThreadSpace(uint32_t width,
716 uint32_t height,
717 CmThreadSpace* &threadSpace) = 0;
718
719 //!
720 //! \brief Creates a CmBufferUP object.
721 //! \details This API creates a CmBufferUP object on top of the UP
722 //! (User Provided) system memory with specificed size in bytes.
723 //! The UP memory starting address must be page (4K Bytes) aligned.
724 //! \param [in] size
725 //! BufferUP size in bytes, the valid range is:
726 //! > CM_MIN_SURF_WIDTH, and < CM_MAX_1D_SURF_WIDTH.
727 //! \param [in] pSystMem
728 //! Pointer to the system memory.
729 //! \param [out] surface
730 //! Reference to the pointer to the CmBufferUP.
731 //! \retval CM_SUCCESS if the CmBufferUP is successfully created.
732 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D
733 //! surface fails.
734 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
735 //! larger than CM_MAX_1D_SURF_WIDTH.
736 //! \retval CM_INVALID_ARG_VALUE if pSystMem is nullptr.
737 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces
738 //! is exceeded. The amount is the amount of the surfaces
739 //! that can co-exist. The amount can be obtained by
740 //! querying the cap CAP_BUFFER_COUNT.
741 //! \retval CM_FAILURE otherwise.
742 //! \note Application can access the memory though the memory
743 //! point from CPU; can also access the
744 //! buffer created upon the same memory from GPU. It is
745 //! application's responsibility to make
746 //! sure accesses from both sides are not overlapped.
747 //! \note Refer to "MDF Host Programming Guide" for detailed usages.
748 //!
749 CM_RT_API virtual int32_t CreateBufferUP(uint32_t size,
750 void *sysMem,
751 CmBufferUP* &surface) = 0;
752
753 //!
754 //! \brief Destroys CmBufferUP object.
755 //! \details The UP (User Provided) memory is still existing after the
756 //! CmBufferUP object is destroyed.
757 //! \param [in, out] surface
758 //! Reference to the pointer pointing to CmBufferUP. It will be
759 //! assigned to nullptr once the function is returned.
760 //! \retval CM_SUCCESS if CmBufferUP is successfully destroyed.
761 //! \retval CM_FAILURE otherwise.
762 //!
763 CM_RT_API virtual int32_t DestroyBufferUP(CmBufferUP* &surface) = 0;
764
765 //!
766 //! \brief Forces the BufferUP object to be destroyed.
767 //! \param [in, out] surface
768 //! Reference to the pointer pointing to CmBufferUP. It will be
769 //! assigned to nullptr once the function is returned.
770 //! \retval CM_SUCCESS if CmBufferUP is successfully destroyed.
771 //! \retval CM_FAILURE otherwise.
772 //!
773 CM_RT_API virtual int32_t ForceDestroyBufferUP(CmBufferUP* &surface) = 0;
774
775 //!
776 //! \brief Gets Surface2D allocation information by given width,
777 //! height, and format.
778 //! \details Gets necessary information in order to create and use
779 //! CmSurface2DUP.
780 //! To create CmSurface2DUP, user needs to allocated such
781 //! amount of system memory which equals to
782 //! or larger than physical size returned here. When
783 //! accessing the system memory, the user needs be
784 //! aware about pitch, which is equal to (pixel_width *
785 //! byte_per_pixel + necessary_padding).
786 //! \param [in] width
787 //! Width in pixel.
788 //! \param [in] height
789 //! height in pixel.
790 //! \param [in] format
791 //! pixel format.
792 //! \param [out] pitch
793 //! Reference to returned pitch.
794 //! \param [out] physicalSize
795 //! Reference to returned physical size.
796 //! \retval CM_SUCCESS always
797 //!
798 CM_RT_API virtual int32_t GetSurface2DInfo(uint32_t width,
799 uint32_t height,
800 CM_SURFACE_FORMAT format,
801 uint32_t &pitch,
802 uint32_t &physicalSize) = 0;
803
804 //!
805 //! \brief Creates a CmSurface2DUP object.
806 //! \details Creates a CmSurface2DUP in UP (User Provided) system memory
807 //! with given surface width, height in pixel, and format.
808 //! The UP system memory must be page (4K Bytes) aligned.
809 //! The size of the system memory must larger than or equal to
810 //! the size return by GetSurface2DInfo().
811 //! \param [in] width
812 //! Width in pixel.
813 //! \param [in] height
814 //! Height in pixel.
815 //! \param [in] format
816 //! Format.
817 //! \param [in] sysMem
818 //! Reference to the pointer to the system memory which is CPU
819 //! accessible.
820 //! \param [out] surface
821 //! Reference to the pointer to the CmSurface2DUP.
822 //! \retval CM_SUCCESS if the CmSurface2DUPis successfully created.
823 //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr.
824 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
825 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
826 //! larger than CM_MAX_2D_SURF_WIDTH, or for YUY2 or NV12
827 //! format, the width is odd.
828 //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT
829 //! or larger than CM_MAX_2D_SURF_HEIGHT, or for NV12 format,
830 //! the height is odd.
831 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not
832 //! supported. The supported formats can be obtained by
833 //! querying cap CAP_SURFACE2D_FORMAT_COUNT
834 //! and CAP_SURFACE2D_FORMATS.
835 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces
836 //! is exceeded. The amount is the amount of the surfaces that
837 //! can co-exist. The amount can be obtained by
838 //! querying the cap CAP_SURFACE2D_COUNT.
839 //! \retval CM_SURFACE_ALLOCATION_FAILURE if allocation is failed.
840 //! \retval CM_FAILURE otherwise.
841 //! \note Application can access the memory though the memory point
842 //! returned from CPU; can also access the surface created
843 //! upon the same memory from GPU. It is application's
844 //! responsibility to make sure accesses from both sides are
845 //! not overlapped. When accessing the system memory from CPU,
846 //! the user needs to be aware about pitch, which is equal to
847 //! (pixel_width * byte_per_pixel + necessary_padding).
848 //! \note Refer to the CmSurface2DUP class for member APIs, and
849 //! 'MDF runtime host programming guide' for usages.
850 //!
851 CM_RT_API virtual int32_t CreateSurface2DUP(uint32_t width,
852 uint32_t height,
853 CM_SURFACE_FORMAT format,
854 void *sysMem,
855 CmSurface2DUP* &surface) = 0;
856
857 //!
858 //! \brief Destroys CmSurface2DUP surface.
859 //! \details The UP (User Provided) memory is still existing after the
860 //! CmSurface2DUP object is destroyed.
861 //! \param [in] surface
862 //! Reference to the pointer pointing to CmSurface2DUP. It will
863 //! be assigned to nullptr once this function is returned.
864 //! \retval CM_SUCCESS if CmSurface2DUPis successfully destroyed.
865 //! \retval CM_FAILURE otherwise.
866 //!
867 CM_RT_API virtual int32_t
868 DestroySurface2DUP(CmSurface2DUP* &surface) = 0;
869
870 //!
871 //! \brief Creates a VME surface for AVC messages in kernel.
872 //! \details Creates a VME surface by using the given 2D surfaces:
873 //! the current frame, the forward frames and, the backward
874 //! frames. The last two can be nullptr if not used. The function
875 //! indicates these 2D surfaces are used for VME; no extra
876 //! surface is actually created. A SurfaceIndex object is created
877 //! instead, which is passed to CM kernel function (genx_main)
878 //! as argument to indicate the frame surface. Please see VME
879 //! examples in "MDF Host Programming Guide" document and CM
880 //! language specification for details.
881 //! \param [in] currentSurface
882 //! Pointer to current surface (can't be nullptr).
883 //! \param [in] forwardSurfaces
884 //! Array of forward surfaces (can be nullptr).
885 //! \param [in] backwardSurfaces
886 //! Array of backward surfaces (can be nullptr).
887 //! \param [in] forwardSurfaceCount
888 //! Count of forward surfaces, up to 16 forward surfaces can be
889 //! used.
890 //! \param [in] backwardSurfaceCount
891 //! Count of backward surfaces, up to 16 backward surfaces can
892 //! be used.
893 //! \param [out] vmeIndex
894 //! Reference to pointer to SurfaceIndex object to be created.
895 //! \retval CM_SUCCESS if the SurfaceIndex is successfully created.
896 //! \retval CM_NULL_POINTER if currentSurface is nullptr.
897 //! \retval CM_INVALID_ARG_VALUE if any parameter is not valid.
898 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
899 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of VME surfaces
900 //! is exceeded. The amount is the amount of VME surfaces that
901 //! can co-exist. The amount can be obtained by querying the
902 //! cap CAP_VME_SURFACE_COUNT.
903 //! \retval CM_FAILURE otherwise.
904 //! \note This can be used for all Gen7_5 and plus platforms.
905 //!
906 CM_RT_API virtual int32_t
907 CreateVmeSurfaceG7_5(CmSurface2D *currentSurface,
908 CmSurface2D **forwardSurfaces,
909 CmSurface2D **backwardSurfaces,
910 const uint32_t forwardSurfaceCount,
911 const uint32_t backwardSurfaceCount,
912 SurfaceIndex* &vmeIndex) = 0;
913
914 //!
915 //! \brief Destroys a VME surface object.
916 //! \details Any VME surface not destroyed by calling this function
917 //! explicitly will be destroyed when CmDevice is destroyed.
918 //! \param [in] vmeIndex
919 //! Pointer to the SurfaceIndex of the VME surface. It will be
920 //! assigned to nullptr once destroy is done.
921 //! \retval CM_SUCCESS if the VME surface is successfully destroyed.
922 //! \retval CM_FAILURE otherwise.
923 //! \note This can be used for all Gen7_5 and plus platforms.
924 //!
925 CM_RT_API virtual int32_t
926 DestroyVmeSurfaceG7_5(SurfaceIndex* &vmeIndex) = 0;
927
928 //!
929 //! \brief Creates a CmSampler8x8 object.
930 //! \param [in] sampler8x8Descriptor
931 //! Const reference to a CM_SAMPLER_8X8_DESCR specifying the
932 //! characteristics of the Sampler8x8 state to be created.
933 //! Currently, AVS, VA Convolve and VA Misc( including MinMax
934 //! Filter/Erode/Dilate ) states are supported.
935 //! \param [out] sampler8x8
936 //! Reference to the pointer to the CmSampler8x8 object.
937 //! \retval CM_SUCCESS if the CmSampler8x8is successfully created.
938 //! \retval CM_INVALID_ARG_VALUE wrong sampler8x8 type.
939 //! \retval CM_EXCEED_SAMPLER_AMOUNT if the co-existed sampler exceeds
940 //! maximum count which can be queried by CAP_SAMPLER_COUNT cap.
941 //!
942 CM_RT_API virtual int32_t
943 CreateSampler8x8(const CM_SAMPLER_8X8_DESCR &sampler8x8Descriptor,
944 CmSampler8x8* &sampler8x8) = 0;
945
946 //!
947 //! \brief Destroys a CmSampler8x8 object.
948 //! \details A CmSampler8x8 which is not destroyed by calling this
949 //! function will be destroyed when the CmDevice is destroyed.
950 //! \param [in, out] sampler8x8State
951 //! Reference to a sampler of CmSampler8x8. It will be assigned
952 //! to nullptr once destroy is done.
953 //! \retval CM_SUCCESS if the CmSampler8x8 is successfully destroyed.
954 //! \retval CM_FAILURE otherwise.
955 //!
956 CM_RT_API virtual int32_t DestroySampler8x8(CmSampler8x8* &sampler8x8State) = 0;
957
958 //!
959 //! \brief Creates a CmSampler8x8 surface.
960 //! \details Creates a CmSampler8x8 surface by using the given 2D surface.
961 //! The function indicates the 2D surface is used for sampler
962 //! 8x8; no extra surface is actually created. A SurfaceIndex
963 //! object is created instead, which is passed to CM kernel
964 //! function (genx_main) as argument to indicate the surface
965 //! for sampler 8x8.
966 //! \param [in] surface2d
967 //! Pointer to CmSurface2D.
968 //! \param [out] sampler8x8SurfIndex
969 //! Reference to pointer to SurfaceIndex.
970 //! \param [in] surfType
971 //! Enumeration data type of CM_SAMPLER8x8_SURFACE.
972 //! \param [in] mode
973 //! Enumeration data type of CM_SURFACE_ADDRESS_CONTROL_MODE.
974 //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully
975 //! created.
976 //! \retval CM_EXCEED_SURFACE_AMOUNT if there is too many co-existed
977 //! surfaces and exceed the maximum number. Destroying some
978 //! unused surfaces could solve this error.
979 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory
980 //! \retval CM_FAILURE otherwise.
981 //!
982 CM_RT_API virtual int32_t
983 CreateSampler8x8Surface(CmSurface2D *surface2d,
984 SurfaceIndex* &sampler8x8SurfIndex,
985 CM_SAMPLER8x8_SURFACE surfType,
986 CM_SURFACE_ADDRESS_CONTROL_MODE mode) = 0;
987
988 //!
989 //! \brief Destroys a CmSampler8x8 surface.
990 //! \details A CmSampler8x8 surface which is not destroyed by calling
991 //! this function will be destroyed when the CmDevice is
992 //! destroyed.
993 //! \param [in] sampler8x8SurfIndex
994 //! Reference to SurfaceIndex. It will be assigned to nullptr
995 //! once destroy is done.
996 //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully
997 //! destroyed.
998 //! \retval CM_FAILURE otherwise.
999 //!
1000 CM_RT_API virtual int32_t
1001 DestroySampler8x8Surface(SurfaceIndex* &sampler8x8SurfIndex) = 0;
1002
1003 //!
1004 //! \brief Creates a 2-dimensional thread group space object.
1005 //! \details This function creates a thread group space specified by the
1006 //! height and width dimensions of the group space, and the
1007 //! height and width dimensions of the thread space within a
1008 //! group. This information is used to execute a kernel in GPGPU pipe
1009 //! (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol07-3d_media_gpgpu.pdf).
1010 //! Relevant sample code is shown in "MDF Host Programming Guide"
1011 //! \param [in] threadSpaceWidth
1012 //! width in unit of threads of each thread group.
1013 //! \param [in] threadSpaceHeight
1014 //! height in unit of threads of each thread group.
1015 //! \param [in] groupSpaceWidth
1016 //! width in unit of groups of thread group space.
1017 //! \param [in] groupSpaceHeight
1018 //! height in unit of groups of thread group space.
1019 //! \param [out] threadGroupSpace
1020 //! Reference to the pointer to CmThreadGroupSpace object to be
1021 //! created.
1022 //! \retval CM_SUCCESS if the CmThreadGroupSpace is successfully
1023 //! created.
1024 //! \retval CM_INVALID_THREAD_GROUP_SPACE if any input is 0 or the
1025 //! thrdSpaceWidth is more than MAX_THREAD_SPACE_WIDTH_PERGROUP,
1026 //! or the thrdSpaceHeight is more than
1027 //! MAX_THREAD_SPACE_HEIGHT_PERGROUP.
1028 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1029 //! \retval CM_FAILURE otherwise.
1030 //! \note The total thread count is width*height*grpWidth*grpHeight.
1031 //! CmKernel::SetThreadCount() calling is not necessary in this
1032 //! GPGPU working mode. Currently, it's only used for SLM
1033 //! enabled kernels. See also CreateThreadGroupSpaceEx() API which
1034 //! specifies a 3-dimensional thread group space with width, height
1035 //! and depth.
1036 //!
1037 CM_RT_API virtual int32_t
1038 CreateThreadGroupSpace(uint32_t threadSpaceWidth,
1039 uint32_t threadSpaceHeight,
1040 uint32_t groupSpaceWidth,
1041 uint32_t groupSpaceHeight,
1042 CmThreadGroupSpace* &threadGroupSpace) = 0;
1043
1044 //!
1045 //! \brief Destroys the created thread group space object.
1046 //! \details Caller provides the reference of thread group space pointer
1047 //! \param [in] threadGroupSpace
1048 //! Pointer to a CmThreadGroupSpace. It will be assigned to
1049 //! nullptr once destroy is done.
1050 //! \retval CM_SUCCESS if the CmThreadGroupSpace pointer is
1051 //! successfully destroyed.
1052 //! \note User can call this API to explicitly destroy
1053 //! CmThreadGroupSpace instance, otherwise, DestroyCmDevice()
1054 //! takes care of all of such instances release.
1055 //!
1056 CM_RT_API virtual int32_t
1057 DestroyThreadGroupSpace(CmThreadGroupSpace* &threadGroupSpace) = 0;
1058
1059 //!
1060 //! \brief Sets the configuration for L3 cache.
1061 //! \details This API allows users to configure L3 cach by themselves.
1062 //! \param [in] l3Config
1063 //! L3ConfigRegisterValues contains the values of L3 control
1064 //! registers. The registers are different from platform to
1065 //! platform. \n
1066 //! struct L3ConfigRegisterValues \n
1067 //! { \n
1068 //! \t unsigned int config_register0; \n
1069 //! \t unsigned int config_register1; \n
1070 //! \t unsigned int config_register2; \n
1071 //! \t unsigned int config_register3; \n
1072 //! }; \n
1073 //! \retval CM_SUCCESS if the L3 configuration pointer is set correctly.
1074 //! \retval CM_FAILURE if the platform does not support L3 or L3
1075 //! configuration failed to be set.
1076 //! \note This function is implemented for both hardware mode and
1077 //! simulation mode.
1078 //!
1079 CM_RT_API virtual int32_t SetL3Config(const L3ConfigRegisterValues *l3Config) = 0;
1080
1081 //!
1082 //! \brief Sets the suggested configuration for L3 cache.
1083 //! \param [in] l3SuggestConfig
1084 //! The configuration plan which represents a suggested L3
1085 //! configuration. These configurations are defined in
1086 //! ::L3_SUGGEST_CONFIG which is a enumeration definition.
1087 //! \retval CM_SUCCESS if the L3 configuration pointer is set correctly.
1088 //! \retval CM_FAILURE if the platform does not support L3 or L3
1089 //! configuration failed to be set.
1090 //! \note This function is only implemented for hardware and
1091 //! simulation modes.
1092 //!
1093 CM_RT_API virtual int32_t
1094 SetSuggestedL3Config(L3_SUGGEST_CONFIG l3SuggestConfig) = 0;
1095
1096 //!
1097 //! \brief This function can be used to set/limit hardware
1098 //! capabilities- number of threads that HW can run in parallel
1099 //! \details Hardware thread number can be set from 1 to maximum.
1100 //! \param [in] capName
1101 //! Name of cap to set.
1102 //! \param [in] capValueSize
1103 //! The size of the cap value.
1104 //! \param [in] capValue
1105 //! Pointer to the cap value.
1106 //! \retval CM_SUCCESS if cap value is valid and is set correctly.
1107 //! \retval CM_INVALID_HARDWARE_THREAD_NUMBER specific SetCaps error
1108 //! message if cap value is not valid.
1109 //! \retval CM_NOT_IMPLEMENTED for emulation mode.
1110 //! \retval CM_FAILURE otherwise.
1111 //! \note The following is the specific behavior for the cap value
1112 //! that is being set.
1113 //! <table>
1114 //! <tr>
1115 //! <th>Cap name< / th>
1116 //! <th>Behavior< / th>
1117 //! < / tr>
1118 //! <tr>
1119 //! <td>CAP_HW_THREAD_COUNT< / td>
1120 //! <td>The number of hardware threads is per - task.A call
1121 //! to the SetCaps function to set the CAP_HW_THREAD_COUNT
1122 //! will limit the maximum number of hardware threads for
1123 //! the ensuing call to Enqueue.After the call to Enqueue,
1124 //! the maximum number of hardware threads will be restored
1125 //! to its default value, which is determined by the
1126 //! hardware's capability.
1127 //! < / td>
1128 //! < / tr>
1129 //! < / table>
1130 //!
1131 CM_RT_API virtual int32_t SetCaps(CM_DEVICE_CAP_NAME capName,
1132 size_t capValueSize,
1133 void *capValue) = 0;
1134
1135 //!
1136 //! \brief This function creates a sampler surface index by a given
1137 //! CmSurface2D.
1138 //! \details This sampler surface doesn't create any actual surface. It
1139 //! just binds the actual 2D surface with a virtual sampler
1140 //! surface index. User need pass this surface index as kernel
1141 //! argument if the surface is used for sampler, otherwise,
1142 //! the runtime will report error if user pass the 2D surface
1143 //! index. For the 2D surface format, for now supports
1144 //! following formats: \n
1145 //! CM_SURFACE_FORMAT_A16B16G16R16 \n
1146 //! CM_SURFACE_FORMAT_A16B16G16R16F \n
1147 //! CM_SURFACE_FORMAT_R32G32B32A32F \n
1148 //! CM_SURFACE_FORMAT_A8 \n
1149 //! CM_SURFACE_FORMAT_A8R8G8B8 \n
1150 //! CM_SURFACE_FORMAT_YUY2 \n
1151 //! CM_SURFACE_FORMAT_R32F \n
1152 //! CM_SURFACE_FORMAT_R32_UINT \n
1153 //! CM_SURFACE_FORMAT_L16 \n
1154 //! CM_SURFACE_FORMAT_R16G16_UNORM \n
1155 //! CM_SURFACE_FORMAT_R16_FLOAT \n
1156 //! CM_SURFACE_FORMAT_NV12 \n
1157 //! CM_SURFACE_FORMAT_L8 \n
1158 //! CM_SURFACE_FORMAT_AYUV \n
1159 //! CM_SURFACE_FORMAT_Y410 \n
1160 //! CM_SURFACE_FORMAT_Y416 \n
1161 //! CM_SURFACE_FORMAT_Y210 \n
1162 //! CM_SURFACE_FORMAT_Y216 \n
1163 //! CM_SURFACE_FORMAT_P010 \n
1164 //! CM_SURFACE_FORMAT_P016 \n
1165 //! CM_SURFACE_FORMAT_YV12 \n
1166 //! CM_SURFACE_FORMAT_411P \n
1167 //! CM_SURFACE_FORMAT_411R \n
1168 //! CM_SURFACE_FORMAT_IMC3 \n
1169 //! CM_SURFACE_FORMAT_I420 \n
1170 //! CM_SURFACE_FORMAT_422H \n
1171 //! CM_SURFACE_FORMAT_422V \n
1172 //! CM_SURFACE_FORMAT_444P \n
1173 //! CM_SURFACE_FORMAT_RGBP \n
1174 //! CM_SURFACE_FORMAT_BGRP \n
1175 //! \param [in] surface2d
1176 //! Pointer to CmSurface2D object.
1177 //! \param [out] samplerSurfaceIndex
1178 //! Reference to the pointer to SurfaceIndex object to be
1179 //! created.
1180 //! \retval CM_SUCCESS if the new sampler surface index is successfully
1181 //! created.
1182 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the input surface format
1183 //! is not list above.
1184 //! \retval CM_EXCEED_SURFACE_AMOUNT if the total number of
1185 //! co-existed surfaces are exceed maximum count.
1186 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1187 //! \retval CM_FAILURE otherwise.
1188 //!
1189 CM_RT_API virtual int32_t
1190 CreateSamplerSurface2D(CmSurface2D *surface2d,
1191 SurfaceIndex* &samplerSurfaceIndex) = 0;
1192
1193 //!
1194 //! \brief This function creates a sampler surface index by a given
1195 //! CmSurface3D.
1196 //! \details This function call doesn't create any actual surface. It
1197 //! just binds the actual 3D surface with a virtual sampler
1198 //! surface index. User need pass this surface index as kernel
1199 //! argument if the surface is used for sampler, otherwise, the
1200 //! runtime will report error if user pass the 3D surface
1201 //! index. For the 3D surface format, for now only supports the
1202 //! CM_SURFACE_FORMAT_A8R8G8B8 and CM_SURFACE_FORMAT_A16B16G16R16
1203 //! formats.
1204 //! \param [in] surface3d
1205 //! Pointer to CmSurface3D object.
1206 //! \param [out] samplerSurfaceIndex
1207 //! Reference to the pointer to SurfaceIndex object to be
1208 //! created.
1209 //! \retval CM_SUCCESS if the sampler surface index is successfully
1210 //! created.
1211 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the input surface format
1212 //! is not list above.
1213 //! \retval CM_EXCEED_SURFACE_AMOUNT if the total number of created
1214 //! co-existed surfaces are exceed maximum count.
1215 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1216 //! \retval CM_FAILURE otherwise.
1217 //!
1218 CM_RT_API virtual int32_t
1219 CreateSamplerSurface3D(CmSurface3D *surface3d,
1220 SurfaceIndex* &samplerSurfaceIndex) = 0;
1221
1222 //!
1223 //! \brief This function destroys a sampler surface index created by
1224 //! CreateSamplerSurface2D(), CreateSamplerSurface2DUP, or
1225 //! CreateSamplerSurface3D().
1226 //! \details Caller provides the reference of a pointer to the surface
1227 //! index needs t be destoryed.
1228 //! \param [in] samplerSurfaceIndex
1229 //! Reference to the pointer to SurfaceIndex object to be
1230 //! destroyed.
1231 //! \retval CM_SUCCESS if the sampler surface index is successfully
1232 //! destroyed.
1233 //! \retval CM_FAILURE otherwise.
1234 //!
1235 CM_RT_API virtual int32_t
1236 DestroySamplerSurface(SurfaceIndex* &samplerSurfaceIndex) = 0;
1237
1238 //!
1239 //! \brief This function creates a buffer to store the message printed
1240 //! by printf() in kernel side.
1241 //! \details The default size of print buffer is 1M bytes. User can set
1242 //! its size according to the length of message printed in
1243 //! kernel and the number of threads. printf() can be used for
1244 //! kernel debug purpose
1245 //! \param [in] size
1246 //! The size of print buffer in bytes.
1247 //! \retval CM_SUCCESS if the print buffer is created successfully.
1248 //! \retval CM_OUT_OF_HOST_MEMORY if print buffer allication is failed.
1249 //! \retval CM_FAILURE otherwise.
1250 //! \note Internally the print buffer occupies static buffer index 1,
1251 //! thus only other 3 static buffers can be used by host (0, 2, 3)
1252 //! if print functionality is enabled.
1253 //!
1254 CM_RT_API virtual int32_t
1255 InitPrintBuffer(size_t size = CM_DEFAULT_PRINT_BUFFER_SIZE) = 0;
1256
1257 //!
1258 //! \brief This function prints the message on the standard display
1259 //! device that are dumped by kernel.
1260 //! \details It should be called after the task being finished. The
1261 //! order of printf output is not deterministic due to thread
1262 //! scheduling and the fact that different threads may be
1263 //! interleaved. To distinguish which thread the printf string
1264 //! comes from, it is better to print the thread id as the
1265 //! first value. Alternatively you could always
1266 //! put the printf inside if statement that limits the printf to a
1267 //! given thread. If one task has more than one kernels call
1268 //! printf() , their outputs could mix together.
1269 //! \retval CM_SUCCESS if the buffer is flushed successfully.
1270 //! \retval CM_FAILURE otherwise.
1271 //!
1272 CM_RT_API virtual int32_t FlushPrintBuffer() = 0;
1273
1274 //!
1275 //! \brief This function creates a VEBOX object for VEBOX
1276 //! operations (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol09-media_vebox.pdf).
1277 //! \details Caller provides a reference of CmVebox pointer to get the
1278 //! CmVebox object created from this function.
1279 //! \param [in, out] vebox
1280 //! the created VEBOX object.
1281 //! \retval CM_SUCCESS if creation is successfully.
1282 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1283 //! \retval CM_FAILURE otherwise.
1284 //!
1285 CM_RT_API virtual int32_t CreateVebox(CmVebox* &vebox) = 0;
1286
1287 //!
1288 //! \brief This function destroys a VEBOX object.
1289 //! \details Caller provides a reference of CmVebox pointer to destroy.
1290 //! \param [in, out] vebox
1291 //! The VEBOX object to be destroyed. It will be assigned to
1292 //! nullptr once destroy is done.
1293 //! \retval CM_SUCCESS if creation is successfully.
1294 //! \retval CM_NULL_POINTER if the vebox pointer is nullptr.
1295 //! \retval CM_FAILURE otherwise.
1296 //!
1297 CM_RT_API virtual int32_t DestroyVebox(CmVebox* &vebox) = 0;
1298
1299 //!
1300 //! \brief It creates a CmBufferSVM of the specified size in bytes by
1301 //! using the SVM (shared virtual memory) system memory.
1302 //! (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol05-memory_views.pdf).
1303 //! \details The SVM memory can be accessed by both CPU and GPU. The SVM
1304 //! memory will be allocated in runtime internally(if user pass
1305 //! nullptr pointer) or user provided (if user pass a valid
1306 //! pointer). In both way, the memory should be page aligned
1307 //! (4K bytes). And the staring address is returned.
1308 //! \param [in] size
1309 //! SVM buffer size in bytes.
1310 //! \param [in,out] pSystMem
1311 //! Pointer to the SVM memory starting address.
1312 //! \param [in] accessFlag
1313 //! Buffer access flags.
1314 //! \param [out] bufferSVM
1315 //! Reference to the pointer to the CmBufferSVM.
1316 //! \retval CM_SUCCESS if the CmBufferSVM is successfully created.
1317 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D
1318 //! surface fails.
1319 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
1320 //! larger than CM_MAX_1D_SURF_WIDTH.
1321 //! \retval CM_OUT_OF_HOST_MEMORY if runtime can't allocate such size
1322 //! SVM memory.
1323 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces
1324 //! is exceeded. The amount is the amount of the surfaces that
1325 //! can co-exist. The amount can be obtained by querying the
1326 //! cap CAP_BUFFER_COUNT.
1327 //! \retval CM_FAILURE otherwise.
1328 //! \note This API is not implemented in Linux for now.
1329 //!
1330 CM_RT_API virtual int32_t CreateBufferSVM(uint32_t size,
1331 void* &sysMem,
1332 uint32_t accessFlag,
1333 CmBufferSVM* &bufferSVM) = 0;
1334
1335 //!
1336 //! \brief Destroys CmBufferSVM object and associated SVM memory.
1337 //! \param [in,out] bufferSVM
1338 //! Reference to the pointer pointing to CmBufferSVM, will be
1339 //! assigned to nullptr once it is destroyed successfully.
1340 //! \retval CM_SUCCESS if CmBufferSVM and associated SVM meory are
1341 //! successfully destroyed.
1342 //! \retval CM_FAILURE otherwise.
1343 //!
1344 CM_RT_API virtual int32_t DestroyBufferSVM(CmBufferSVM* &bufferSVM) = 0;
1345
1346 //!
1347 //! \brief This function creates a sampler surface index by a
1348 //! CmSurface2DUP.
1349 //! \details This sampler surface doesn't create any actual surface,
1350 //! and just bind the actual 2D UP (User Provided) surface
1351 //! with a virtual sampler surface index. User need pass this
1352 //! surface index as kernel argument if the surface is used
1353 //! for sampler, otherwise, the runtime will report error if
1354 //! user pass the 2D UP surface index. For the 2DUP surface
1355 //! formats, for now supports following formats: \n
1356 //! CM_SURFACE_FORMAT_A16B16G16R16 \n
1357 //! CM_SURFACE_FORMAT_A8 \n
1358 //! CM_SURFACE_FORMAT_A8R8G8B8 \n
1359 //! CM_SURFACE_FORMAT_YUY2 \n
1360 //! CM_SURFACE_FORMAT_R32F \n
1361 //! CM_SURFACE_FORMAT_R32_UINT \n
1362 //! CM_SURFACE_FORMAT_L16 \n
1363 //! CM_SURFACE_FORMAT_R16G16_UNORM \n
1364 //! CM_SURFACE_FORMAT_NV12 \n
1365 //! CM_SURFACE_FORMAT_L8 \n
1366 //! CM_SURFACE_FORMAT_AYUV \n
1367 //! CM_SURFACE_FORMAT_Y410 \n
1368 //! CM_SURFACE_FORMAT_Y416 \n
1369 //! CM_SURFACE_FORMAT_Y210 \n
1370 //! CM_SURFACE_FORMAT_Y216 \n
1371 //! CM_SURFACE_FORMAT_P010 \n
1372 //! CM_SURFACE_FORMAT_P016 \n
1373 //! CM_SURFACE_FORMAT_YV12 \n
1374 //! CM_SURFACE_FORMAT_411P \n
1375 //! CM_SURFACE_FORMAT_411R \n
1376 //! CM_SURFACE_FORMAT_IMC3 \n
1377 //! CM_SURFACE_FORMAT_I420 \n
1378 //! CM_SURFACE_FORMAT_422H \n
1379 //! CM_SURFACE_FORMAT_422V \n
1380 //! CM_SURFACE_FORMAT_444P \n
1381 //! CM_SURFACE_FORMAT_RGBP \n
1382 //! CM_SURFACE_FORMAT_BGRP \n
1383 //! \param [in] surface2dUP
1384 //! Pointer to CmSurface2DUP object.
1385 //! \param [out] samplerSurfaceIndex
1386 //! Reference to the pointer to SurfaceIndex object to be
1387 //! created.
1388 //! \retval CM_SUCCESS if the new sampler surface index is
1389 //! successfully created.
1390 //! \retval CM_NULL_POINTER if p2DUPSurface is nullptr.
1391 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not supported.
1392 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1393 //! \retval CM_FAILURE otherwise.
1394 //! \note This API is supported for HW mode only.
1395 //!
1396 CM_RT_API virtual int32_t
1397 CreateSamplerSurface2DUP(CmSurface2DUP *surface2dUP,
1398 SurfaceIndex* &samplerSurfaceIndex) = 0;
1399
1400 //!
1401 //! \brief Copies the content of source kernel to a new kernel.
1402 //! \param [out] kernelDst
1403 //! pointer to the destination kernel. The new pointer will be
1404 //! returned to kernelDst.
1405 //! \param [in] kernelSrc
1406 //! pointer to the source kernel.
1407 //! \retval CM_SUCCESS If the clone operation is successful.
1408 //! \retval CM_FAILURE If the clone operation is failed.
1409 //! \note This API is not supported in emulation mode.
1410 //!
1411 CM_RT_API virtual int32_t CloneKernel(CmKernel* &kernelDst,
1412 CmKernel *kernelSrc) = 0;
1413
1414 //!
1415 //! \brief Creates an alias to CmSurface2D.
1416 //! \details Returns a new surface index for this surface. This API is
1417 //! used with CmSurface2D::SetSurfaceStateParam in order
1418 //! to reinterpret surface for different surface states,
1419 //! i.e., the same memory is used but different width and
1420 //! height can be programmed through the surface state.
1421 //! \param [in] p2DSurface
1422 //! pointer to the surface used to create an alias.
1423 //! \param [out] aliasSurfaceIndex
1424 //! new surface index pointing to 2D surface.
1425 //! \retval CM_SUCCESS if alias is created successfully.
1426 //! \retval CM_INVALID_ARG_VALUE if p2DSurface is not a valid pointer.
1427 //! \retval CM_MAX_NUM_2D_ALIASES if try to create more than 10 aliases
1428 //! for same surface.
1429 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1430 //! \retval CM_FAILURE otherwise.
1431 //! \note This API is implemented for HW and SIM modes only.
1432 //!
1433 CM_RT_API virtual int32_t
1434 CreateSurface2DAlias(CmSurface2D *p2DSurface,
1435 SurfaceIndex* &aliasSurfaceIndex) = 0;
1436
1437 //!
1438 //! \brief Creates an HEVC VME surface by using the given 2D surfaces:
1439 //! the current frame, the forward frames and, the backward
1440 //! frames.
1441 //! \details No extra surface is actually created. A SurfaceIndex
1442 //! object is created instead, which is passed to CM kernel
1443 //! function (genx_main) as argument to indicate the frame
1444 //! surface. This can be used for Gen10 and plus platforms.
1445 //! \param [in] currentSurface
1446 //! Pointer to current surface (can't be nullptr).
1447 //! \param [in] forwardSurfaces
1448 //! Array of forward surfaces (can be nullptr if backward
1449 //! surfaces not a nullptr).
1450 //! \param [in] backwardSurfaces
1451 //! Array of backward surfaces (can be nullptr if forward
1452 //! surfaces not a nullptr).
1453 //! \param [in] forwardSurfaceCount
1454 //! Count of forward surfaces, up to 4 forward surfaces can
1455 //! be used.
1456 //! \param [in] backwardSurfaceCount
1457 //! Count of backward surfaces, up to 4 backward surfaces can
1458 //! be used.
1459 //! \param [out] vmeIndex
1460 //! Reference to pointer to SurfaceIndex object to be created.
1461 //! \retval CM_SUCCESS if the SurfaceIndex is successfully created.
1462 //! \retval CM_NULL_POINTER if currentSurface is nullptr.
1463 //! \retval CM_INVALID_ARG_VALUE if invalid surface pointers for forward
1464 //! and backward surfaces.
1465 //! \retval CM_EXCEED_SURFACE_AMOUNT if there is too much co-existed
1466 //! surfaces are created. Destroying unused surfaces to solve
1467 //! such error.
1468 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
1469 //! \retval CM_FAILURE otherwise.
1470 //! \note This API is only supported for Gen10 and plus platforms.
1471 //!
1472 CM_RT_API virtual int32_t
1473 CreateHevcVmeSurfaceG10(CmSurface2D *currentSurface,
1474 CmSurface2D **forwardSurfaces,
1475 CmSurface2D **backwardSurfaces,
1476 const uint32_t forwardSurfaceCount,
1477 const uint32_t backwardSurfaceCount,
1478 SurfaceIndex* &vmeIndex) = 0;
1479
1480 //!
1481 //! \brief Destroys an HEVC VME surface. This can be used for Gen10.
1482 //! \param [in] vmeIndex
1483 //! Pointer to the SurfaceIndex of the VME surface. It will be
1484 //! assigned to nullptr once destroy is done.
1485 //! \retval CM_SUCCESS if the HEVC VME surface is successfully destroyed
1486 //! \retval CM_FAILURE otherwise.
1487 //! \note This API is only supported for Gen10 and plus platforms. \n
1488 //! Any HEVC VME surface not destroyed by calling this function
1489 //! explicitly will be destroyed when CmDevice is destroyed.
1490 //!
1491 CM_RT_API virtual int32_t
1492 DestroyHevcVmeSurfaceG10(SurfaceIndex* &vmeIndex) = 0;
1493
1494 //!
1495 //! \brief Creates a CmSampler object with border color setting.
1496 //! \param [in] sampleState
1497 //! Const reference to a CM_SAMPLER_STATE_EX specifying the
1498 //! characteristics of the sampler to be created.
1499 //! \param [out] sampler
1500 //! Reference to the pointer to the CmSampler object.
1501 //! \retval CM_SUCCESS if the CmSampler is successfully created.
1502 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
1503 //! \retval CM_EXCEED_SAMPLER_AMOUNT if maximum amount of sampler is
1504 //! exceeded. The amount is the amount of the sampler that can
1505 //! co-exist. The amount can be obtained by querying the cap
1506 //! CAP_SAMPLER_COUNT.
1507 //! \retval CM_FAILURE otherwise.
1508 //! \note This API is not implemented for EMU mode. \n Point, linear,
1509 //! and anisotropic filter types are supported for hardware and
1510 //! simulation modes. \n Wrap, mirror, clamp and border are
1511 //! supported in hardware and simulation modes. Clamp is
1512 //! supported in emulation mode.
1513 //!
1514 CM_RT_API virtual int32_t
1515 CreateSamplerEx(const CM_SAMPLER_STATE_EX &sampleState,
1516 CmSampler* &sampler) = 0;
1517
1518 //!
1519 //! \brief This function prints the message dumped by kernel into file
1520 //! instead of stdout.
1521 //! \details This function's usage is the same as
1522 //! CmDevice::FlushPrintBuffer(). It is recommended to use this
1523 //! interface when there are tons of messages from kernel.
1524 //! \param [in] filename
1525 //! name of file the message printed into.
1526 //! \retval CM_SUCCESS if the buffer is flushed successfully into file.
1527 //! \retval CM_FAILURE otherwise.
1528 //!
1529 CM_RT_API virtual int32_t
1530 FlushPrintBufferIntoFile(const char *filename) = 0;
1531
1532 //!
1533 //! \brief Creates a 3-dimensional thread group space object.
1534 //! \details This function creates a thread group space specified by the
1535 //! depth, height and width dimensions of the group space, and the
1536 //! depth, height and width dimensions of the thread space within a
1537 //! group. This information is used to execute a kernel in GPGPU pipe
1538 //! (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol07-3d_media_gpgpu.pdf).
1539 //! Relevant sample code is shown in "MDF Host Programming Guide".
1540 //! \param [in] thrdSpaceWidth
1541 //! width in unit of threads of each thread group.
1542 //! \param [in] thrdSpaceHeight
1543 //! height in unit of threads of each thread group.
1544 //! \param [in] thrdSpaceDepth
1545 //! depth in unit of threads of each thread group.
1546 //! \param [in] grpSpaceWidth
1547 //! width in unit of groups of thread group space.
1548 //! \param [in] grpSpaceHeight
1549 //! height in unit of groups of thread group space.
1550 //! \param [in] grpSpaceDepth
1551 //! depth in unit of groups of thread group space.
1552 //! \param [out] threadGroupSpace
1553 //! Reference to the pointer to CmThreadGroupSpace object to be
1554 //! created.
1555 //! \retval CM_SUCCESS if the CmThreadGroupSpace is successfully
1556 //! created.
1557 //! \retval CM_INVALID_THREAD_GROUP_SPACE if any input is 0 or the
1558 //! thrdSpaceWidth is more than MAX_THREAD_SPACE_WIDTH_PERGROUP,
1559 //! or the thrdSpaceHeight is more than
1560 //! MAX_THREAD_SPACE_HEIGHT_PERGROUP, or the thrdSpaceDepth
1561 //! is more than MAX_THREAD_SPACE_DEPTH_PERGROUP.
1562 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1563 //! \retval CM_FAILURE otherwise.
1564 //! \note The total thread count is width*height*depth*grpWidth*grpHeight*grpDepth.
1565 //! CmKernel::SetThreadCount() calling is not necessary in this
1566 //! GPGPU working mode. Currently, it's only used for SLM
1567 //! enabled kernels.
1568 //!
1569 CM_RT_API virtual int32_t
1570 CreateThreadGroupSpaceEx(uint32_t thrdSpaceWidth,
1571 uint32_t thrdSpaceHeight,
1572 uint32_t thrdSpaceDepth,
1573 uint32_t grpSpaceWidth,
1574 uint32_t grpSpaceHeight,
1575 uint32_t grpSpaceDepth,
1576 CmThreadGroupSpace* &threadGroupSpace) = 0;
1577
1578 //!
1579 //! \brief Creates a CmSampler8x8 surface by using given 2D surface
1580 //! and given flags.
1581 //! \details The function indicates the 2D surface is used for sampler
1582 //! 8x8; no extra surface is actually created. A SurfaceIndex
1583 //! object is created instead, which is passed to CM kernel
1584 //! function(genx_main) as argument to indicate the surface for
1585 //! sampler 8x8. Compared to CmDeive::CreateSampler8x8Surface,
1586 //! this API is used to support rotation and chroma siting for
1587 //! MediaSampler.
1588 //! \param [in] surface2d
1589 //! Pointer to CmSurface2D.
1590 //! \param [out] sampler8x8SurfIndex
1591 //! Reference to pointer to SurfaceIndex.
1592 //! \param [in] surfType
1593 //! Enumeration data type of CM_SAMPLER8x8_SURFACE.
1594 //! \param [in] addressControl
1595 //! Enumeration data type of CM_SURFACE_ADDRESS_CONTROL_MODE.
1596 //! \param [in] flag
1597 //! Pointer to CM_FLAG.
1598 //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully
1599 //! created.
1600 //! \retval CM_EXCEED_SURFACE_AMOUNT if there is too many co-existed
1601 //! surfaces and exceed the maximum number. Destroying some
1602 //! unused surfaces could solve this error.
1603 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory
1604 //! \retval CM_FAILURE otherwise.
1605 //! \note This API is not supported in emulation mode.
1606 //!
1607 CM_RT_API virtual int32_t
1608 CreateSampler8x8SurfaceEx(CmSurface2D *surface2d,
1609 SurfaceIndex* &sampler8x8SurfIndex,
1610 CM_SAMPLER8x8_SURFACE surfType = CM_VA_SURFACE,
1611 CM_SURFACE_ADDRESS_CONTROL_MODE addressControl
1612 = CM_SURFACE_CLAMP,
1613 CM_FLAG *flag = nullptr) = 0;
1614
1615 //!
1616 //! \brief Creates sampler surface by using given 2D surface and flags.
1617 //! \details This sampler surface does't create any actual surface, and
1618 //! just bind the actual 2D surface with a virtual sampler
1619 //! surface index. User need pass this surface index as kernel
1620 //! argument if the surface is used for sampler, otherwise,
1621 //! the runtime will report error if user pass the 2D surface
1622 //! index. Compared to CmDevice::CreateSampler8x8Surface, this
1623 //! API is used to support rotation for 3D sampler. For given
1624 //! surface's formats, for now, we support following: \n
1625 //! CM_SURFACE_FORMAT_A16B16G16R16 \n
1626 //! CM_SURFACE_FORMAT_A16B16G16R16F \n
1627 //! CM_SURFACE_FORMAT_R32G32B32A32F \n
1628 //! CM_SURFACE_FORMAT_A8 \n
1629 //! CM_SURFACE_FORMAT_A8R8G8B8 \n
1630 //! CM_SURFACE_FORMAT_YUY2 \n
1631 //! CM_SURFACE_FORMAT_R32F \n
1632 //! CM_SURFACE_FORMAT_R32_UINT \n
1633 //! CM_SURFACE_FORMAT_L16 \n
1634 //! CM_SURFACE_FORMAT_R16G16_UNORM \n
1635 //! CM_SURFACE_FORMAT_R16_FLOAT \n
1636 //! CM_SURFACE_FORMAT_NV12 \n
1637 //! CM_SURFACE_FORMAT_L8 \n
1638 //! CM_SURFACE_FORMAT_AYUV \n
1639 //! CM_SURFACE_FORMAT_Y410 \n
1640 //! CM_SURFACE_FORMAT_Y416 \n
1641 //! CM_SURFACE_FORMAT_Y210 \n
1642 //! CM_SURFACE_FORMAT_Y216 \n
1643 //! CM_SURFACE_FORMAT_P010 \n
1644 //! CM_SURFACE_FORMAT_P016 \n
1645 //! CM_SURFACE_FORMAT_YV12 \n
1646 //! CM_SURFACE_FORMAT_411P \n
1647 //! CM_SURFACE_FORMAT_411R \n
1648 //! CM_SURFACE_FORMAT_IMC3 \n
1649 //! CM_SURFACE_FORMAT_I420 \n
1650 //! CM_SURFACE_FORMAT_422H \n
1651 //! CM_SURFACE_FORMAT_422V \n
1652 //! CM_SURFACE_FORMAT_444P \n
1653 //! CM_SURFACE_FORMAT_RGBP \n
1654 //! CM_SURFACE_FORMAT_BGRP \n
1655 //! \param [in] surface2d
1656 //! Pointer to CmSurface2D object.
1657 //! \param [out] samplerSurfaceIndex
1658 //! Reference to the pointer to SurfaceIndex object to be
1659 //! created.
1660 //! \param [in] flag
1661 //! Pointer to CM_FLAG.
1662 //! \retval CM_SUCCESS if the new sampler surface index is
1663 //! successfully created.
1664 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the input surface format
1665 //! is not list above.
1666 //! \retval CM_EXCEED_SURFACE_AMOUNT if the total number of created
1667 //! co-existed surfaces are exceed maximum count.
1668 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1669 //! \retval CM_FAILURE otherwise.
1670 //! \note This API is not supported in emulation mode.
1671 //!
1672 CM_RT_API virtual int32_t
1673 CreateSamplerSurface2DEx(CmSurface2D *surface2d,
1674 SurfaceIndex* &samplerSurfaceIndex,
1675 CM_FLAG *flag = nullptr) = 0;
1676
1677 //!
1678 //! \brief Creates an alias to CmBuffer.
1679 //! \details Returns a new surface index for this surface. This API is
1680 //! used with CmBuffer::SetSurfaceStateParam in order
1681 //! to reinterpret buffer for different surface states,
1682 //! i.e., the same memory is used but different size
1683 //! can be programmed through the surface state.
1684 //! \param [in] buffer
1685 //! pointer to CmBuffer object used to create an alias.
1686 //! \param [out] aliasIndex
1687 //! \retval CM_SUCCESS if alias is created successfully.
1688 //! new surface index pointing to CmBuffer.
1689 //! \retval CM_EXCEED_MAX_NUM_BUFFER_ALIASES if try to create more
1690 //! than 10 aliases for same surface.
1691 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1692 //! \retval CM_FAILURE if alias cannot be created.
1693 //! \note This API is not implemented for EMU mode.
1694 //!
1695 CM_RT_API virtual int32_t
1696 CreateBufferAlias(CmBuffer *buffer,
1697 SurfaceIndex* &aliasIndex) = 0;
1698
1699 //!
1700 //! \brief Sets the width and height values in the VME surface state.
1701 //! \param [in] vmeIndex
1702 //! Pointer to VME surface index.
1703 //! \param [in] surfStateParam
1704 //! Pointer to CM_VME_SURFACE_STATE_PARAM to set width and
1705 //! height of this surface
1706 //! \retval CM_SUCCESS if setting VME surface state values successfully.
1707 //! \retval CM_INVALID_ARG_VALUE if invalid input.
1708 //! \note This API will work on HW and SIM modes.
1709 //!
1710 CM_RT_API virtual int32_t
1711 SetVmeSurfaceStateParam(SurfaceIndex *vmeIndex,
1712 CM_VME_SURFACE_STATE_PARAM *surfStateParam) = 0;
1713
1714 //!
1715 //! \brief Gets the VISA version up-to which IGC supports.
1716 //! \param [out] majorVersion
1717 //! The major Version of VISA.
1718 //! \param [out] minorVersion
1719 //! The minor Version of VISA.
1720 //! \retval CM_SUCCESS if get the right VISA version.
1721 //! \retval CM_JITDLL_LOAD_FAILURE if loading igc library is failed.
1722 //! \retval CM_FAILURE otherwise.
1723 //! \note This API is implemented in hardware mode only.
1724 //!
1725 CM_RT_API virtual int32_t GetVISAVersion(uint32_t &majorVersion,
1726 uint32_t &minorVersion) = 0;
1727
1728 //!
1729 //! \brief Creates a CmQueue object with option.
1730 //! \param [out] queue
1731 //! Pointer to the CmQueue object created.
1732 //! \param [in] QueueCreateOption
1733 //! The option to create a queue. The sturcture of the
1734 //! <b>QueueCreateOption</b> is:\n
1735 //! \code
1736 //! struct CM_QUEUE_CREATE_OPTION
1737 //! {
1738 //! CM_QUEUE_TYPE QueueType : 3;
1739 //! bool RA : 1;
1740 //! unsigned int Reserved0 : 3;
1741 //! bool UserGPUContext : 1;
1742 //! unsigned int GPUContext : 8;
1743 //! unsigned int Reserved2 : 16;
1744 //! }
1745 //! \endcode
1746 //! \n
1747 //! <b>CM_QUEUE_TYPE</b> indicates which engine the queue will
1748 //! be created for:\n
1749 //! \code
1750 //! enum CM_QUEUE_TYPE
1751 //! {
1752 //! CM_QUEUE_TYPE_NONE = 0,
1753 //! CM_QUEUE_TYPE_RENDER = 1,
1754 //! CM_QUEUE_TYPE_COMPUTE = 2,
1755 //! CM_QUEUE_TYPE_VEBOX = 3
1756 //! };
1757 //! \endcode
1758 //! \n
1759 //! <b>RAMode</b> decides if the queue will occupy GPU
1760 //! exclusively during execution.\n
1761 //! <b>UserGPUContext</b> indicates if the user wants to
1762 //! provide an existing MOS GPU Context.\n
1763 //! <b>GPUContext</b> is the existing MOS GPU Context Enum
1764 //! value.
1765 //! \n
1766 //! <b>CM_QUEUE_SSEU_USAGE_HINT_TYPE</b> indicates SSEU setting, will
1767 //! be created for:\n
1768 //! \code
1769 //! enum CM_QUEUE_SSEU_USAGE_HINT_TYPE
1770 //! {
1771 //! CM_QUEUE_SSEU_USAGE_HINT_DEFAULT = 0,
1772 //! CM_QUEUE_SSEU_USAGE_HINT_VME = 1
1773 //! };
1774 //! \endcode
1775 //! \retval CM_SUCCESS if the CmQueue object is created.
1776 //! \note This API is implemented in hardware mode only. Only
1777 //! CM_QUEUE_TYPE_RENDER and CM_QUEUE_TYPE_COMPUTE are
1778 //! implemented at this moment.
1779 //!
1780 CM_RT_API virtual int32_t
1781 CreateQueueEx(CmQueue *&queue,
1782 CM_QUEUE_CREATE_OPTION QueueCreateOption
1783 = CM_DEFAULT_QUEUE_CREATE_OPTION) = 0;
1784
1785 //!
1786 //! \brief Update the MOS Resource in the CmBuffer. If surface is null,
1787 //! creates a new CmBuffer
1788 //! \details CmBuffer is a wrapper of that MOS resource. This Mos resource is
1789 //! owned by caller.
1790 //! \param [in] mosResource
1791 //! pointer to MOS resource.
1792 //! \param [in,out] surface
1793 //! reference to pointer of surface to be created.
1794 //! \param [in] mosUsage
1795 //! The selected pre-defined MOS usage of memory object control cache setting
1796 //! \retval CM_SUCCESS if the CmBuffer is successfully created.
1797 //! \retval CM_INVALID_MOS_RESOURCE_HANDLE if mosResource is nullptr.
1798 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory
1799 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces is exceeded.
1800 //! \retval CM_FAILURE otherwise
1801 //!
1802 CM_RT_API virtual int32_t UpdateBuffer(PMOS_RESOURCE mosResource, CmBuffer* &surface,
1803 MOS_HW_RESOURCE_DEF mosUsage = MOS_CM_RESOURCE_USAGE_SurfaceState) = 0;
1804
1805 //!
1806 //! \brief Update the MOS Resource in the CmSurface2D. If surface is null,
1807 //! creates a new CmSurface2D
1808 //! \details CmSurface2D is a wrapper of that MOS resource. This Mos resource is
1809 //! owned by caller.
1810 //! \param [in] mosResource
1811 //! pointer to MOS resource.
1812 //! \param [in,out] surface
1813 //! reference to pointer of surface to be created.
1814 //! \param [in] mosUsage
1815 //! The selected pre-defined MOS usage of memory object control cache setting
1816 //! \retval CM_SUCCESS if the CmSurface2D is successfully created.
1817 //! \retval CM_INVALID_MOS_RESOURCE_HANDLE if pMosResrouce is nullptr.
1818 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces
1819 //! is exceeded.
1820 //! \retval CM_FAILURE otherwise.
1821 //!
1822 CM_RT_API virtual int32_t UpdateSurface2D(PMOS_RESOURCE mosResource, CmSurface2D* &surface,
1823 MOS_HW_RESOURCE_DEF mosUsage = MOS_CM_RESOURCE_USAGE_SurfaceState) = 0;
1824
1825 //!
1826 //! \brief Creates a CmSampler8x8 surface from Surface2D alias.
1827 //! \details Creates a CmSampler8x8 surface by using the given 2D surface
1828 //! alias.
1829 //! No extra surface is actually created. A SurfaceIndex
1830 //! object is created instead, which is passed to CM kernel
1831 //! function (genx_main) as an argument to indicate the surface
1832 //! for AVS.
1833 //! \param [in] originalSurface
1834 //! Pointer to the original CmSurface2D object.
1835 //! \param [in] aliasIndex
1836 //! Surface alias upon which the output surface index is
1837 //! created.
1838 //! \param [in] addressControl
1839 //! Enumerator specifying address control mode used by AVS.
1840 //! \param [out] sampler8x8SurfaceIndex
1841 //! Sampler8x8 surface index created by this function.
1842 //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully
1843 //! created.
1844 //! \retval CM_EXCEED_SURFACE_AMOUNT if there are too many surfaces,
1845 //! exceeding the maximum limit,
1846 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory,
1847 //! \retval CM_FAILURE otherwise.
1848 //!
1849 CM_RT_API virtual int32_t
1850 CreateSampler8x8SurfaceFromAlias(
1851 CmSurface2D *originalSurface,
1852 SurfaceIndex *aliasIndex,
1853 CM_SURFACE_ADDRESS_CONTROL_MODE addressControl,
1854 SurfaceIndex* &sampler8x8SurfaceIndex) = 0;
1855
1856 //!
1857 //! \brief It creates a CmBufferStateless of the specified size in bytes by
1858 //! using the vedio memory or the system memory.
1859 //! \details The stateless buffer means it is stateless-accessed by GPU. There
1860 //! are two ways to create a stateless buffer. One is to create from
1861 //! vedio memory, then it can be only accessed by GPU. The other way is
1862 //! to create from system memory, then it can be accessed by both GPU
1863 //! and CPU. In this way, The system memory will be allocated in runtime
1864 //! internally(if user pass nullptr pointer) or user provided (if user
1865 //! pass a valid pointer). And the system memory should be page aligned
1866 //! (4K bytes).
1867 //! \param [in] size
1868 //! Stateless buffer size in bytes.
1869 //! \param [in] option
1870 //! Stateless buffer create option.
1871 //! \param [in] sysMem
1872 //! Pointer to user provided system memory if option is system memory.
1873 //! \param [out] pSurface
1874 //! Reference to the pointer to the CmBufferStateless.
1875 //! \retval CM_SUCCESS if the CmBufferStateless is successfully created.
1876 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D
1877 //! surface fails.
1878 //! \retval CM_OUT_OF_HOST_MEMORY if runtime can't allocate such size
1879 //! system memory.
1880 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces
1881 //! is exceeded. The amount is the amount of the surfaces that
1882 //! can co-exist. The amount can be obtained by querying the
1883 //! cap CAP_BUFFER_COUNT.
1884 //! \retval CM_INVALID_CREATE_OPTION_FOR_BUFFER_STATELESS if option is invalid.
1885 //! \retval CM_FAILURE otherwise.
1886 CM_RT_API virtual int32_t CreateBufferStateless(size_t size,
1887 uint32_t option,
1888 void *sysMem,
1889 CmBufferStateless *&bufferStateless) = 0;
1890
1891 //!
1892 //! \brief Destroy CmBufferStateless object and associated vedio/system memory.
1893 //! \param [in,out] pSurface
1894 //! Reference to the pointer pointing to CmBufferStateless, will be
1895 //! assigned to nullptr once it is destroyed successfully.
1896 //! \retval CM_SUCCESS if CmBufferStateless and associated vedio/system memory are
1897 //! successfully destroyed.
1898 //! \retval CM_FAILURE otherwise.
1899 //!
1900 CM_RT_API virtual int32_t DestroyBufferStateless(CmBufferStateless* &bufferStateless) = 0;
1901
1902 };
1903 }; //namespace
1904
1905 #endif // #ifndef MEDIADRIVER_LINUX_COMMON_CM_CMDEVICE_H_