/* * Copyright (c) 2017, Intel Corporation * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), * to deal in the Software without restriction, including without limitation * the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included * in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR * OTHER DEALINGS IN THE SOFTWARE. */ #ifndef CMRTLIB_LINUX_SHARE_CM_DEVICE_BASE_H_ #define CMRTLIB_LINUX_SHARE_CM_DEVICE_BASE_H_ #include "cm_def.h" #include "cm_device_def.h" class CmBuffer; class CmSurface2D; class CmProgram; class CmKernel; class CmTask; class CmQueue; class CmThreadSpace; class CmThreadGroupSpace; class CmBufferSVM; class CmBufferUP; class CmSurface2DUP; class CmSurface3D ; class CmSampler; class CmSampler8x8; class CmVebox; class CmBufferStateless; class SurfaceIndex; class CmSurface2DStateless; struct CM_SAMPLER_8X8_DESCR; struct VME_STATE_G6; //! \brief CmDevice class for Linux class CmDevice { public: //! \brief Creates a CmBuffer with specified size in bytes. //! \details This function creates a buffer in video memory with linear //! layout. //! \param [in] size //! Buffer size in bytes. //! \param [out] buffer //! Reference to the pointer to the CmBuffer. //! \retval CM_SUCCESS if the CmBuffer is successfully created. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D //! surface fails. //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or //! larger than CM_MAX_1D_SURF_WIDTH. //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces //! is exceeded. The amount is the amount of the surfaces //! that can co-exist. The amount can be obtained by querying //! the cap CAP_BUFFER_COUNT. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateBuffer(uint32_t size, CmBuffer* &buffer)=0; //! \brief Creates a CmSurface2D with given width, height, and format. //! \details This function creates a surface in video memory with a 2D layout. //! User needs to provide width, height and format. //! \param [in] width //! Surface width in pixel. //! \param [in] height //! Surface height in pixel. //! \param [in] format //! Surface format. //! \param [out] surface //! Reference to the pointer to the CmSurface2D. //! \retval CM_SUCCESS if the CmSurface2D is successfully created. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath //! resource fails. //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or //! larger than CM_MAX_2D_SURF_WIDTH, or for YUY2, or NV12 //! format, the width is odd. //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT //! or larger than CM_MAX_2D_SURF_HEIGHT, or for NV12 format, //! the height is odd. //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not //! supported. The supported formats can be obtained by //! querying cap CAP_SURFACE2D_FORMAT_COUNT and //! CAP_SURFACE2D_FORMATS. For now, the following formats are //! supported: \n //! CM_SURFACE_FORMAT_A8R8G8B8, \n //! CM_SURFACE_FORMAT_X8R8G8B8, \n //! CM_SURFACE_FORMAT_A8B8G8R8, \n //! CM_SURFACE_FORMAT_R32F, \n //! CM_SURFACE_FORMAT_V8U8, \n //! CM_SURFACE_FORMAT_P8, \n //! CM_SURFACE_FORMAT_YUY2, \n //! CM_SURFACE_FORMAT_A8, \n //! CM_SURFACE_FORMAT_NV12, \n //! CM_SURFACE_FORMAT_P010, \n //! CM_SURFACE_FORMAT_UYVY, \n //! CM_SURFACE_FORMAT_IMC3, \n //! CM_SURFACE_FORMAT_411P, \n //! CM_SURFACE_FORMAT_422H, \n //! CM_SURFACE_FORMAT_422V, \n //! CM_SURFACE_FORMAT_444P, \n //! CM_SURFACE_FORMAT_YV12, \n //! CM_SURFACE_FORMAT_R8_UINT, \n //! CM_SURFACE_FORMAT_R16_UINT, \n //! CM_SURFACE_FORMAT_P208 \n //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces //! is exceeded. The amount is the amount of the surfaces that //! can co-exist. The amount can be obtained by querying the //! cap CAP_SURFACE2D_COUNT. //! \retval CM_FAILURE otherwise. //! \note For planar surface, there is only one CmSurface2D instance, //! no matter how many planes the surface may have. //! The detail about how to access different planes in the kernel //! code can be found in CM Language Spec, looking for read_plane //! and write_plane. CM_RT_API virtual int32_t CreateSurface2D(uint32_t width, uint32_t height, CM_SURFACE_FORMAT format, CmSurface2D* &surface) = 0; //! \brief Creates a CmSurface3D with given width, height, depth and //! pixel format. //! \details This function creates a surface in memory with a 3D layout. //! User needs to provide width, height, depth and format. //! \param [in] width //! Surface width. //! \param [in] height //! Surface height. //! \param [in] depth //! Surface depth. //! \param [in] format //! Surface format. //! \param [out] surface //! Reference to the pointer to the CmSurface3D. //! \retval CM_SUCCESS if the CmSurface3D is successfully created. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or //! larger than CM_MAX_3D_SURF_WIDTH. //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT //! or larger than CM_MAX_3D_SURF_HEIGHT. //! \retval CM_INVALID_DEPTH if width is less than CM_MIN_SURF_DEPTH or //! larger than CM_MAX_3D_SURF_DEPTH. //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not //! supported. The supported formats can be obtained by //! querying cap CAP_SURFACE3D_FORMAT_COUNT and //! CAP_SURFACE3D_FORMATS, For now, only supports: \n //! CM_SURFACE_FORMAT_X8R8G8B8, \n //! CM_SURFACE_FORMAT_A8R8G8B8, \n //! CM_SURFACE_FORMAT_A16B16G16R16. \n //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 3D //! surface fails. //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 3D surfaces //! is exceeded. The amount is the amount of the surfaces that //! can co-exist. The amount can be obtained by querying the //! cap CAP_SURFACE3D_COUNT. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateSurface3D(uint32_t width, uint32_t height, uint32_t depth, CM_SURFACE_FORMAT format, CmSurface3D* &surface) = 0; //! \brief Creates a CmSurface2D from an existing VA surface. //! \details The application must have created the VA surface using the //! same VA device as the one used to create the CmDevice. //! The VA surface format should be within the supported //! format set which can be obtained by querying cap //! CAP_SURFACE2D_FORMAT_COUNT and CAP_SURFACE2D_FORMATS. The //! surface must be lockable is you want to use //! CmSurface2D::ReadSurface and CmSurface2D::WriteSurface. //! \param [in] vaSurfaceId //! Surface ID of the VA surface. //! \param [out] surface //! Reference to the pointer to the CmSurface2D. //! \retval CM_SUCCESS if the CmSurface2D are successfully created. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or //! larger than CM_MAX_2D_SURF_WIDTH, or for YUY2, or NV12 //! format, the width is odd. //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT //! or larger than CM_MAX_2D_SURF_HEIGHT, or for NV12 format, //! the height is odd. //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not //! supported. The supported formats can be obtained by //! querying cap CAP_SURFACE2D_FORMAT_COUNT and //! CAP_SURFACE2D_FORMATS. For now, the following formats are //! supported: \n //! CM_SURFACE_FORMAT_A8R8G8B8, \n //! CM_SURFACE_FORMAT_X8R8G8B8, \n //! CM_SURFACE_FORMAT_A8B8G8R8, \n //! CM_SURFACE_FORMAT_R32F, \n //! CM_SURFACE_FORMAT_V8U8, \n //! CM_SURFACE_FORMAT_P8, \n //! CM_SURFACE_FORMAT_YUY2, \n //! CM_SURFACE_FORMAT_A8, \n //! CM_SURFACE_FORMAT_NV12, \n //! CM_SURFACE_FORMAT_P010, \n //! CM_SURFACE_FORMAT_UYVY, \n //! CM_SURFACE_FORMAT_IMC3, \n //! CM_SURFACE_FORMAT_411P, \n //! CM_SURFACE_FORMAT_422H, \n //! CM_SURFACE_FORMAT_422V, \n //! CM_SURFACE_FORMAT_444P, \n //! CM_SURFACE_FORMAT_YV12, \n //! CM_SURFACE_FORMAT_R8_UINT, \n //! CM_SURFACE_FORMAT_R16_UINT, \n //! CM_SURFACE_FORMAT_P208 \n //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces //! is exceeded. The amount is the amount of the surfaces that //! can co-exist. The amount can be obtained by querying the //! cap CAP_SURFACE2D_COUNT. //! \retval CM_FAILURE otherwise. //! \note This API is in Linux only. CM_RT_API virtual int32_t CreateSurface2D(VASurfaceID vaSurfaceId, CmSurface2D* &surface) = 0; //! \brief Creates an array of CmSurface2D type surfaces from an //! existing array of VA surfaces. //! \details Surface in the VA surface array must be created by the //! same VA device as the one that created CmDevice. It is //! application's responsibility to allocate memory for the //! array of pointers to CmSurface2D. The VA surface format //! should be within the supported format set which can be //! obtained by querying cap CAP_SURFACE2D_FORMAT_COUNT and //! CAP_SURFACE2D_FORMATS. The surface must be lockable is you //! want to use CmSurface2D::ReadSurface and //! CmSurface2D::WriteSurface. //! \param [in] vaSurfaceId //! Pointer to the array of surface ID of VA surfaces. //! \param [in] surfaceCount //! Array size. //! \param [out] surfaceArray //! Pointer to the array of pointers pointing to CmSurface2D //! objects. //! \retval CM_SUCCESS if all CmSurface2D objects are successfully //! created. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_FAILURE otherwise. //! \note This API is in Linux only. CM_RT_API virtual int32_t CreateSurface2D(VASurfaceID* vaSurfaceId, const uint32_t surfaceCount, CmSurface2D **surfaceArray) = 0; //! \brief Destroys CmBuffer object. //! \details This function destroys CmBuffer object. After the function //! is called, it will return immediately without waiting. If //! there is any Enqueue is being executed when this function //! is called, the actual destroy will be postponed internally //! by the runtime, and user doens't need to worry about it. //! \param [in,out] buffer //! Reference to the pointer pointing to CmBuffer, it will be //! assigned to nullptr after destroy. //! \retval CM_SUCCESS if CmBuffer is successfully destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroySurface(CmBuffer* &buffer) = 0; //! \brief Destroys CmSurface2D type surface. //! \details This function destroys CmSurface2D object. After the function //! is called, it will return immediately without waiting. If //! there is any Enqueue is being executed when this function is //! called, the actual destroy will be postponed internally by //! the runtime, and user doens't need to worry about it. One //! exception is that if the CmSurface2D was created by a third //! party VA surface, user has to keep the VA surface until the //! kernel using it finishes execution. //! \param [in,out] surface2d //! Reference to the pointer pointing to CmSurface2D. It will //! be assigned to nullptr after destroy. //! \retval CM_SUCCESS if CmSurface2D is successfully destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroySurface( CmSurface2D* &surface2d) = 0; //! \brief Destroys CmSurface3D object. //! \details This function destroys CmSurface3D object. After the //! function is called, it will return immediately without //! waiting. If there is any Enqueue is being executed when this //! function is called, the actual destroy will be postponed //! internally by the runtime, and user doens't need to worry //! about it. //! \param [in,out] surface3d //! Reference to the pointer pointing to CmSurface3D. It will //! be assigned to nullptr after destroy. //! \retval CM_SUCCESS if CmSurface3D is successfully destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroySurface( CmSurface3D* &surface3d) = 0; //! \brief Creates a task queue corresponding to the render context. //! \details CmQueue is an in-order queue of tasks. Each task is //! essentially a CmTask object containing kernels that are to //! be run concurrently. Each kernel can be executed with //! multiple threads. Trying to create a second CmQueue will //! return an existing object. //! \param [in,out] queue //! Reference to the pointer to the CmQueue. //! \retval CM_SUCCESS if the CmQueue is successfully created. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateQueue(CmQueue* &queue) = 0; //! \brief Creates a CmProgram object consisting of kernels loaded from //! the commonISACode code. //! \details Common ISA code is offline generated as a file with a .isa suffix //! by the CM compiler when it is used to compile one or more //! kernels. It contains ISA code common for all Intel platforms. //! Just-In-Time (JIT) compilation of the common ISA code happens in //! LoadProgram and generates platform specific ISA according to the //! actaully platform where the application in running in hardware mode. //! In the emulation mode JIT doesn't happen. //! In the simulation mode JIT doesn't happen but paltform specfic //! ISA need to be offline generated together with common ISA by //! CM compiler and to be included in commonISACode. //! How to generate common ISA and platform specific ISA can be //! found in CM compiler manual. //! \param [in] commonISACode //! Pointer pointing to code in common ISA. //! \param [in] size //! Size in bytes of the common ISA code. //! \param [in,out] program //! Reference to the pointer to the CmProgram. //! \param [in] options //! JIT options for all kernels in the code. This argument //! is optional. Size of options should be no more than 512 //! (CM_MAX_OPTION_SIZE_IN_BYTE) bytes including the null //! terminator. There is one option available currently: \n //! "nojitter" -- Use this option to completely disable jitter //! from occurring. NOTE: "/Qxcm_jit_tartget=%GEN_ARCH%" //! flag must be set during offline compilation if "nojitter" //! is set in hardware mode. //! In simulation and emulation mode, this option is ignored. //! \retval CM_SUCCESS if the CmProgram is successfully created. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_INVALID_ARG_VALUE if invalid input parameters. //! \retval CM_INVALID_GENX_BINARY if the GEN binary is not matched with //! actual running platform in "nojitter" mode. //! \retval CM_JIT_COMPILE_FAILURE if JIT compile of the common ISA //! code fails. //! \retval CM_INVALID_KERNEL_SPILL_CODE if kernel has spill code and //! devcie's scratch memory space is disabled in //! CreateCmDeviceEx. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t LoadProgram(void* commonISACode, const uint32_t size, CmProgram*& program, const char* options = nullptr) = 0; //! \brief Creates a CmKernel object from the CmProgram object. //! \details A Cmprogram can contains multiple kernels. //! The size of all arguments of a kernel should be no more than //! CAP_ARG_SIZE_PER_KERNEL byte. The number of all kernel //! arguments should be no more than CAP_ARG_COUNT_PER_KERNEL. //! The size of kernel binary should be no more than //! CAP_KERNEL_BINARY_SIZE bytes. The kernelName should be no //! more than 256 (CM_MAX_KERNEL_NAME_SIZE_IN_BYTE) bytes //! including the null terminator. //! \param [in] program //! CmProgram object from which the kernel is created. //! \param [in] kernelName //! CM kernel function (genx_main) name. A CM_KERNEL_FUNCTION //! macro MUST be used to specify this argument. //! \param [in,out] kernel //! Reference to the pointer to the CmKernel object. //! \param [in] options //! JIT options for this specific kernel, overwriting the JIT //! options specified for all kernels in the CmProgram. This //! argument is optional. Size of options should be no more //! than 512 (CM_MAX_OPTION_SIZE_IN_BYTE) bytes including the //! null terminator. No options available for now. //! \retval CM_SUCCESS if the CmKernel is successfully created or //! returned. //! \retval CM_INVALID_ARG_VALUE if program is an invalid pointer. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_EXCEED_KERNEL_ARG_AMOUNT if the argument number of the //! kernel fucntion is larger than CAP_ARG_COUNT_PER_KERNEL. //! \retval CM_EXCEED_KERNEL_ARG_SIZE_IN_BYTE if the argument size of //! the kernel fucntion is larger than CAP_ARG_SIZE_PER_KERNEL. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateKernel( CmProgram* program, const char* kernelName, CmKernel* & kernel, const char* options = nullptr) = 0; //! \brief Creates a CmKernel object in emulation mode. //! \details The size of all kernel arguments should be no more than //! CAP_ARG_SIZE_PER_KERNEL byte. The number of all kernel //! arguments should be no more than CAP_ARG_COUNT_PER_KERNEL. //! The size of kernel binary should be no more than //! CAP_KERNEL_BINARY_SIZE bytes. The kernelName should be no //! more than 256 (CM_MAX_KERNEL_NAME_SIZE_IN_BYTE) bytes //! including the null terminator. //! \param [in] program //! CmProgram from which the kernel is created. //! \param [in] kernelName //! CM kernel function (genx_main) name emulation mode also //! needs a pointer to the kernel function. A //! CM_KERNEL_FUNCTION macro MUST be used to specify this //! argument to accommodate emulation modes. //! \param [in] fncPnt //! This API is for emulation mode only, and this parameter //! is not necessarily controlled by user because the macro //! CM_KERNEL_FUNCTION will be used to set this parameter. //! \param [in,out] kernel //! Reference to the pointer to the CmKernel object. //! \param [in] options //! JIT options for this specific kernel, overwriting the JIT //! options specified for all kernels in the CmProgram. This //! argument is optional. Size of options should be no more //! than 512 (CM_MAX_OPTION_SIZE_IN_BYTE) bytes including the //! null terminator. No options available for now. //! \retval CM_SUCCESS if the CmKernel is successfully created or //! returned. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_EXCEED_KERNEL_ARG_AMOUNT if the argument number of the //! kernel fucntion is larger than CAP_ARG_COUNT_PER_KERNEL. //! \retval CM_EXCEED_KERNEL_ARG_SIZE_IN_BYTE if the argument size of //! the kernel fucntion is larger than CAP_ARG_SIZE_PER_KERNEL. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateKernel(CmProgram* program, const char* kernelName, const void * fncPnt, CmKernel* & kernel, const char* options = nullptr) = 0; //! \brief Creates a CmSampler object. //! \details This function creates a 3D sampler state object used to sample //! a 2D surface. //! \param [in] sampleState //! Const reference to a CM_SAMPLER_STATE specifying the //! characteristics of the sampler to be created. The structure //! is defined below. //! \param [out] sampler //! Reference to the pointer to the CmSampler object. //! \retval CM_SUCCESS if the CmSampler is successfully created. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_EXCEED_SAMPLER_AMOUNT if maximum amount of sampler is //! exceeded. The amount is the amount of the sampler that can //! co-exist. The amount can be obtained by querying the cap //! CAP_SAMPLER_COUNT. //! \retval CM_FAILURE otherwise. //! \note typedef struct _CM_SAMPLER_STATE\n //! {\n //! CM_TEXTURE_FILTER_TYPE minFilterType;\n //! CM_TEXTURE_FILTER_TYPE magFilterType;\n //! CM_TEXTURE_ADDRESS_TYPE addressU;\n //! CM_TEXTURE_ADDRESS_TYPE addressV;\n //! CM_TEXTURE_ADDRESS_TYPE addressW;\n //! } CM_SAMPLER_STATE;\n //! //! For now, only linear and anisotropic filter types are //! supported for hardware and simulation modes. For emulation //! mode, linear filter type is supported. Wrap, mirror, and //! clamp address types are supported in hardware and simulation modes. //! only clamp address type is supported in emulation mode. CM_RT_API virtual int32_t CreateSampler(const CM_SAMPLER_STATE &sampleState, CmSampler* &sampler) = 0; //! \brief Destroy a CmKernel. //! \details A CmKernel that is not destroyed by calling this function //! will be destroyed when the CmDevice is destroyed. //! \param [in,out] kernel //! CmKernel object to be destroyed. It will be assigned to //! nullptr once the fuction is return. //! \retval CM_SUCCESS if the CmKernel is successfully destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroyKernel(CmKernel* &kernel) = 0; //! \brief Destroys a CmSampler. //! \details A CmSampler that is not destroyed by calling this function //! will be destroyed when the CmDevice is destroyed. //! \param [in,out] sampler //! A reference to the CmSampler pointer. //! \retval CM_SUCCESS if the CmSampler is successfully destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroySampler(CmSampler* &sampler) = 0; //! \brief Destroys a CmProgram. //! \details A CmProgram that is not destroyed by calling this function //! will be destroyed when the CmDevice is destroyed. //! \param [in,out] program //! Reference to the pointer to the CmProgram. It will be assigned to //! nullptr once the fuction is return. //! \retval CM_SUCCESS if the CmProgram is successfully destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroyProgram(CmProgram* &program) = 0; //! \brief Destroys a CmThreadSpace instance. //! \details A CmThreadSpace that is not destroyed by calling this //! function will be destroyed when the CmDevice is destroyed. //! \param [in,out] threadSpace //! Reference to the pointer to the CmThreadSpace. It will be //! assigned to nullptr once the fuction is return. //! \retval CM_SUCCESS if the CmThreadSpace is successfully destroyed. //! \retval CM_FAILURE if the input is nullptr or not valid. CM_RT_API virtual int32_t DestroyThreadSpace( CmThreadSpace* &threadSpace) = 0; //! //! \brief Creates a CmTask object //! \details This object is a container for one or multiple CmKernel objects, and used //! to enqueue the kernels for concurrent execution. //! \param [out] task Reference to the pointer to the CmTask //! \retval CM_SUCCESS if the CmTask is successfully created //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory //! CM_RT_API virtual int32_t CreateTask(CmTask* &task) = 0; //! //! \brief Destroy a CmTask object //! \details A CmTask that is not destroyed by calling this //! function will be destroyed when the CmDevice is destroyed //! \param [in, out] task Reference to the pointer to the CmTask. //! \retval CM_SUCCESS if the CmTaskis successfully destroyed //! \retval CM_FAILURE otherwise //! CM_RT_API virtual int32_t DestroyTask(CmTask* &task)=0; //! //! \brief This function can be used to get HW capability. //! \details By calling this function, user can get the hardware capabilites //! of running platform. //! \param [in] capName Name of cap to query //! \param [out] capValueSize Reference to the size in bytes of the Cap //! value. On entry application should set this to the size //! of memory allocated for the cap value. Application should //! make sure this size is large enough to hold the Cap value //! requested. On return from this function the actual size of //! cap value is returned. //! \param [out] capValue Pointer pointing to memory where the //! cap value should be returned //! \retval CM_SUCCESS if the input capValueSize equals or //! is larger than required Cap size and Cap Value //! is successfully returned //! \retval CM_FAILURE otherwise //! //! \details //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //! //!
Cap NameSize in bytes Type of ValueDescription
CAP_KERNEL_COUNT_PER_TASK4uint32_tMaximum number of kernels that can be enqueued in one task
CAP_KERNEL_BINARY_SIZE4uint32_t Maximum kernel binary size in bytes
CAP_SAMPLER_COUNT4uint32_t Maximum number of samplers that can co-exist at any time //! in a CmDevice
CAP_SAMPLER_COUNT_PER_KERNEL 4uint32_tMaximum number of samplers that one kernel can use
CAP_BUFFER_COUNT 4uint32_tMaximum number of CmBuffer/CmBufferUP that can co - exist at any time
CAP_SURFACE2D_COUNT4uint32_tMaximum number of CmSurface2D that can co-exist at //! any time
CAP_SURFACE3D_COUNT 4uint32_tMaximum number of CmSurface3D that can co-exist at any //! time in a CmDevice
CAP_SURFACE_COUNT_PER_KERNEL 4uint32_tMaximum number of surfaces (including 1D, 2D and 3D) that //! one kernel can use
CAP_ARG_COUNT_PER_KERNEL 4uint32_tMaximum number of arguments that a kernel can have
CAP_ARG_SIZE_PER_KERNEL 4uint32_tMaximum size of all arguments that a kernel can have
CAP_USER_DEFINED_THREAD_COUNT_PER_TASK 4uint32_tMaximum number of threads that all kernels of a task can //! run, it's only used for media object usage
CAP_HW_THREAD_COUNT 4uint32_tMaximum number of threads that HW can run in parallel.This //! indicates hardware parallelism and is hence one //! of the factors indicating performance of the target machine
CAP_SURFACE2D_FORMAT_COUNT 4uint32_tNumber of surface formats supported for CmSurface2D creation
CAP_SURFACE2D_FORMATS sizeof(VA_CM_FORMAT) * CAP_SURFACE2D_FORMAT_COUNTArray of VA_CM_FORMATAll Libva formats supported to create CmSurface2D
CAP_SURFACE3D_FORMAT_COUNT sizeof(VA_CM_FORMAT) * CAP_SURFACE3D_FORMAT_COUNTArray of VA_CM_FORMATNumber of Libva formats supported for CmSurface3D creation
CAP_SURFACE3D_FORMATS sizeof(VA_CM_FORMAT) * CAP_SURFACE3D_FORMAT_COUNTArray of VA_CM_FORMATAll Libva formats supported to create CmSurface3D
CAP_GPU_PLATFORM 4uint32_tReturn GPU platform as an enum of type GPU_PLATFORM //! (PLATFORM_INTEL_BDW, PLATFORM_INTEL_SKL, etc)
CAP_GT_PLATFORM 4uint32_tReturn GT platform (SKU) as an enum of type GPU_GT_PLATFORM //! (PLATFORM_INTEL_GT1, PLATFORM_INTEL_GT2, etc)
CAP_MIN_FREQUENCY 4uint32_tReturns the minimum frequency of the GPU as an integer in MHz //!
CAP_MAX_FREQUENCY 4uint32_tReturns the maximum frequency of the GPU as an integer in MHz //!
CAP_GPU_CURRENT_FREQUENCY 4uint32_tReturn the current frequency of the GPU as an integer //! in MHz
CAP_USER_DEFINED_THREAD_COUNT_PER_TASK_NO_THREAD_ARG 4uint32_tReturns the maximum thread count on media object without //! per - thread argument
CAP_USER_DEFINED_THREAD_COUNT_PER_MEDIA_WALKER 4uint32_tReturns the maximum thread count in media walker usage
CAP_USER_DEFINED_THREAD_COUNT_PER_THREAD_GROUP 4uint32_tReturns the maximum thread count per thread group in //! GPGPU walker usage
CAP_SURFACE2DUP_COUNT 4uint32_tMaximum number of CmSurface2DUP that can //! co - exist at any time
CAP_PLATFORM_INFO sizeof(CM_PLATFORM_INFO)CM_PLATFORM_INFOEU information, like number of slice, number of subslice, //! EU number per subslice, etc. See CM_PLATFORM_INFO.
CAP_MAX_BUFFER_SIZE 4uint32_tReturns maximum size in bytes for CmBuffer and CmBufferUP.
CM_RT_API virtual int32_t GetCaps(CM_DEVICE_CAP_NAME capName, size_t& capValueSize, void *capValue) = 0; //! \brief Creates a CmThreadSpace object. //! \details CmThreadSpace is a 2D space.Each unit is notated as //! a pair of X/Y coordinates, which is in the range of [0, width -1] //! or [0, heigh-1]. A thread space can define a dependency or no //! dependency. A thread space can be used as per-task thread space //! by passing it in Enqueue(), or be used as per-kernel thread space //! by calling CmKernel::AssociateThreadSpace() API. Please //! refer to "Host programming guide" for detailed thread space usages. //! \param [in] width //! Thread space width. //! \param [in] height //! Thread space height. //! \param [out] threadSpace //! Reference to pointer to CmThreadSpace object to be created. //! \retval CM_SUCCESS if the CmThreadSpace is successfully created. //! \retval CM_INVALID_THREAD_SPACE if the width or(and) height are //! \retval invalid values (0 or exceeds maximum size). //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_FAILURE otherwise. //! \note The maximum width/height allowed when using media walker is //! 511 for pre-SKL and 2047 for SKL+. For media object the //! maximum width/height allowed is 512. CM_RT_API virtual int32_t CreateThreadSpace( uint32_t width, uint32_t height, CmThreadSpace* &threadSpace) = 0; //! \brief Creates a CmBufferUP object. //! \details This API creates a CmBufferUP object on top of the UP //! (User Provided) system memory with specificed size in bytes. //! The UP memory starting address must be page (4K Bytes) aligned. //! \param [in] size //! BufferUP size in bytes, the valid range is: //! > CM_MIN_SURF_WIDTH, and < CM_MAX_1D_SURF_WIDTH. //! \param [in] sysMem //! Pointer to the system memory. //! \param [out] buffer //! Reference to the pointer to the CmBufferUP. //! \retval CM_SUCCESS if the CmBufferUP is successfully created. //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D //! surface fails. //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or //! larger than CM_MAX_1D_SURF_WIDTH. //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr. //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces //! is exceeded. The amount is the amount of the surfaces //! that can co-exist. The amount can be obtained by //! querying the cap CAP_BUFFER_COUNT. //! \retval CM_FAILURE otherwise. //! \note Application can access the memory though the memory //! point from CPU; can also access the //! buffer created upon the same memory from GPU. It is //! application's responsibility to make //! sure accesses from both sides are not overlapped. //! \note Refer to "MDF Host Programming Guide" for detailed usages. CM_RT_API virtual int32_t CreateBufferUP(uint32_t size, void *sysMem, CmBufferUP* &buffer)=0; //! \brief Destroys CmBufferUP object. //! \details The UP (User Provided) memory is still existing after the //! CmBufferUP object is destroyed. //! \param [in, out] buffer //! Reference to the pointer pointing to CmBufferUP. It will be //! assigned to nullptr once the function is returned. //! \retval CM_SUCCESS if CmBufferUP is successfully destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroyBufferUP(CmBufferUP* &buffer) = 0; //! \brief Gets Surface2D allocation information by given width, //! height, and format. //! \details Gets necessary information in order to create and use //! CmSurface2DUP. //! To create CmSurface2DUP, user needs to allocated such //! amount of system memory which equals to //! or larger than physical size returned here. When //! accessing the system memory, the user needs be //! aware about pitch, which is equal to (pixel_width * //! byte_per_pixel + necessary_padding). //! \param [in] width //! Width in pixel. //! \param [in] height //! height in pixel. //! \param [in] format //! pixel format. //! \param [out] pitch //! Reference to returned pitch. //! \param [out] physicalSize //! Reference to returned physical size. //! \retval CM_SUCCESS always CM_RT_API virtual int32_t GetSurface2DInfo( uint32_t width, uint32_t height, CM_SURFACE_FORMAT format, uint32_t & pitch, uint32_t & physicalSize)= 0; //! \brief Creates a CmSurface2DUP object. //! \details Creates a CmSurface2DUP in UP (User Provided) system memory //! with given surface width, height in pixel, and format. //! The UP system memory must be page (4K Bytes) aligned. //! The size of the system memory must larger than or equal to //! the size return by GetSurface2DInfo(). //! \param [in] width //! Width in pixel. //! \param [in] height //! Height in pixel. //! \param [in] format //! Format. //! \param [in] sysMem //! Reference to the pointer to the system memory which is CPU //! accessible. //! \param [out] surface //! Reference to the pointer to the CmSurface2DUP. //! \retval CM_SUCCESS if the CmSurface2DUPis successfully created. //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or //! larger than CM_MAX_2D_SURF_WIDTH, or for YUY2 or NV12 //! format, the width is odd. //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT //! or larger than CM_MAX_2D_SURF_HEIGHT, or for NV12 format, //! the height is odd. //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not //! supported. The supported formats can be obtained by //! querying cap CAP_SURFACE2D_FORMAT_COUNT //! and CAP_SURFACE2D_FORMATS. //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces //! is exceeded. The amount is the amount of the surfaces that //! can co-exist. The amount can be obtained by //! querying the cap CAP_SURFACE2D_COUNT. //! \retval CM_SURFACE_ALLOCATION_FAILURE if allocation is failed. //! \retval CM_FAILURE otherwise. //! \note Application can access the memory though the memory point //! returned from CPU; can also access the surface created //! upon the same memory from GPU. It is application's //! responsibility to make sure accesses from both sides are //! not overlapped. When accessing the system memory from CPU, //! the user needs to be aware about pitch, which is equal to //! (pixel_width * byte_per_pixel + necessary_padding). //! \note Refer to the CmSurface2DUP class for member APIs, and //! 'MDF runtime host programming guide' for usages. CM_RT_API virtual int32_t CreateSurface2DUP( uint32_t width, uint32_t height, CM_SURFACE_FORMAT format, void* sysMem, CmSurface2DUP* &surface)= 0; //! \brief Destroys CmSurface2DUP surface. //! \details The UP (User Provided) memory is still existing after the //! CmSurface2DUP object is destroyed. //! \param [in] surface //! Reference to the pointer pointing to CmSurface2DUP. It will //! be assigned to nullptr once this function is returned. //! \retval CM_SUCCESS if CmSurface2DUPis successfully destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroySurface2DUP( CmSurface2DUP* & surface) = 0; //! \brief Creates a VME surface for AVC messages in kernel. //! \details Creates a VME surface by using the given 2D surfaces: //! the current frame, the forward frames and, the backward //! frames. The last two can be nullptr if not used. The function //! indicates these 2D surfaces are used for VME; no extra //! surface is actually created. A SurfaceIndex object is created //! instead, which is passed to CM kernel function (genx_main) //! as argument to indicate the frame surface. Please see VME //! examples in "MDF Host Programming Guide" document and CM //! language specification for details. //! \param [in] currentSurface //! Pointer to current surface (can't be nullptr). //! \param [in] forwardSurfaceArray //! Array of forward surfaces (can be nullptr). //! \param [in] backwardSurfaceArray //! Array of backward surfaces (can be nullptr). //! \param [in] surfaceCountForward //! Count of forward surfaces, up to 16 forward surfaces can be //! used. //! \param [in] surfaceCountBackward //! Count of backward surfaces, up to 16 backward surfaces can //! be used. //! \param [out] vmeSurfaceIndex //! Reference to pointer to SurfaceIndex object to be created. //! \retval CM_SUCCESS if the SurfaceIndex is successfully created. //! \retval CM_NULL_POINTER if currentSurface is nullptr. //! \retval CM_INVALID_ARG_VALUE if any parameter is not valid. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of VME surfaces //! is exceeded. The amount is the amount of VME surfaces that //! can co-exist. The amount can be obtained by querying the //! cap CAP_VME_SURFACE_COUNT. //! \retval CM_FAILURE otherwise. //! \note This can be used for all Gen7_5 and plus platforms. CM_RT_API virtual int32_t CreateVmeSurfaceG7_5 ( CmSurface2D* currentSurface, CmSurface2D** forwardSurfaceArray, CmSurface2D** backwardSurfaceArray, const uint32_t surfaceCountForward, const uint32_t surfaceCountBackward, SurfaceIndex* & vmeSurfaceIndex )=0; //! \brief Destroy a VME surface object. //! \details Any VME surface not destroyed by calling this function //! explicitly will be destroyed when CmDevice is destroyed. //! \param [in] vmeSurfaceIndex //! Pointer to the SurfaceIndex of the VME surface. It will be //! assigned to nullptr once destroy is done. //! \retval CM_SUCCESS if the VME surface is successfully destroyed. //! \retval CM_FAILURE otherwise. //! \note This can be used for all Gen7_5 and plus platforms. CM_RT_API virtual int32_t DestroyVmeSurfaceG7_5( SurfaceIndex* &vmeSurfaceIndex) = 0; //! \brief Creates a CmSampler8x8 object. //! \param [in] samplerDescriptor //! Const reference to a CM_SAMPLER_8X8_DESCR specifying the //! characteristics of the Sampler8x8 state to be created. //! Currently, AVS, VA Convolve and VA Misc( including MinMax //! Filter/Erode/Dilate ) states are supported. //! \param [out] sampler //! Reference to the pointer to the CmSampler8x8 object. //! \retval CM_SUCCESS if the CmSampler8x8is successfully created. //! \retval CM_INVALID_ARG_VALUE wrong sampler8x8 type. //! \retval CM_EXCEED_SAMPLER_AMOUNT if the co-existed sampler exceeds //! maximum count which can be queried by CAP_SAMPLER_COUNT cap. CM_RT_API virtual int32_t CreateSampler8x8(const CM_SAMPLER_8X8_DESCR &samplerDescriptor, CmSampler8x8* &sampler) = 0; //! \brief Destroys a CmSampler8x8 object. //! \details A CmSampler8x8 which is not destroyed by calling this //! function will be destroyed when the CmDevice is destroyed. //! \param [in, out] sampler //! Reference to a sampler of CmSampler8x8. It will be assigned //! to nullptr once destroy is done. //! \retval CM_SUCCESS if the CmSampler8x8 is successfully destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroySampler8x8(CmSampler8x8* &sampler) = 0; //! \brief Creates a CmSampler8x8 surface. //! \details Creates a CmSampler8x8 surface by using the given 2D surface. //! The function indicates the 2D surface is used for sampler //! 8x8; no extra surface is actually created. A SurfaceIndex //! object is created instead, which is passed to CM kernel //! function (genx_main) as argument to indicate the surface //! for sampler 8x8. //! \param [in] surface2d //! Pointer to CmSurface2D. //! \param [out] surfaceIndex //! Reference to pointer to SurfaceIndex. //! \param [in] surfaceType //! Enumeration data type of CM_SAMPLER8x8_SURFACE. //! \param [in] addressControl //! Enumeration data type of CM_SURFACE_ADDRESS_CONTROL_MODE. //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully //! created. //! \retval CM_EXCEED_SURFACE_AMOUNT if there is too many co-existed //! surfaces and exceed the maximum number. Destroying some //! unused surfaces could solve this error. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateSampler8x8Surface( CmSurface2D *surface2d, SurfaceIndex* &surfaceIndex, CM_SAMPLER8x8_SURFACE surfaceType = CM_VA_SURFACE, CM_SURFACE_ADDRESS_CONTROL_MODE addressControl = CM_SURFACE_CLAMP) = 0; //! \brief Destroys a CmSampler8x8 surface. //! \details A CmSampler8x8 surface which is not destroyed by calling //! this function will be destroyed when the CmDevice is //! destroyed. //! \param [in] surfaceIndex //! Reference to SurfaceIndex. It will be assigned to nullptr //! once destroy is done. //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully //! destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroySampler8x8Surface(SurfaceIndex* &surfaceIndex) = 0; //! \brief Creates a 2-dimensional thread group space object. //! \details This function creates a thread group space specified by the //! height and width dimensions of the group space, and the //! height and width dimensions of the thread space within a //! group. This information is used to execute a kernel in GPGPU pipe //! (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol07-3d_media_gpgpu.pdf). //! Relevant sample code is shown in "MDF Host Programming Guide" //! \param [in] threadSpaceWidth //! width in unit of threads of each thread group. //! \param [in] threadSpaceHeight //! height in unit of threads of each thread group. //! \param [in] groupSpaceWidth //! width in unit of groups of thread group space. //! \param [in] groupSpaceHeight //! height in unit of groups of thread group space. //! \param [out] threadGroupSpace //! Reference to the pointer to CmThreadGroupSpace object to be //! created. //! \retval CM_SUCCESS if the CmThreadGroupSpace is successfully //! created. //! \retval CM_INVALID_THREAD_GROUP_SPACE if any input is 0 or the //! threadSpaceWidth is more than MAX_THREAD_SPACE_WIDTH_PERGROUP, //! or the threadSpaceHeight is more than //! MAX_THREAD_SPACE_HEIGHT_PERGROUP. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory. //! \retval CM_FAILURE otherwise. //! \note The total thread count is width*height*grpWidth*grpHeight. //! CmKernel::SetThreadCount() calling is not necessary in this //! GPGPU working mode. Currently, it's only used for SLM //! enabled kernels. See also CreateThreadGroupSpaceEx() API which //! specifies a 3-dimensional thread group space with width, height //! and depth. CM_RT_API virtual int32_t CreateThreadGroupSpace( uint32_t threadSpaceWidth, uint32_t threadSpaceHeight, uint32_t groupSpaceWidth, uint32_t groupSpaceHeight, CmThreadGroupSpace* &threadGroupSpace) = 0; //! \brief Destroys the created thread group space object. //! \details Caller provides the reference of thread group space pointer //! \param [in] threadGroupSpace //! Pointer to a CmThreadGroupSpace. It will be assigned to //! nullptr once destroy is done. //! \retval CM_SUCCESS if the CmThreadGroupSpace pointer is //! successfully destroyed. //! \note User can call this API to explicitly destroy //! CmThreadGroupSpace instance, otherwise, DestroyCmDevice() //! takes care of all of such instances release. CM_RT_API virtual int32_t DestroyThreadGroupSpace(CmThreadGroupSpace* &threadGroupSpace) = 0; //! \brief Sets the configuration for L3 cache. //! \details This API allows users to configure L3 cach by themselves. //! \param [in] registerValues //! L3ConfigRegisterValues contains the values of L3 control //! registers. The registers are different from platform to //! platform.\n //! struct L3ConfigRegisterValues \n //! { \n //! \t unsigned int config_register0; \n //! \t unsigned int config_register1; \n //! \t unsigned int config_register2; \n //! \t unsigned int config_register3; \n //! }; \n //! \retval CM_SUCCESS if the L3 configuration pointer is set correctly. //! \retval CM_FAILURE if the platform does not support L3 or L3 //! configuration failed to be set. //! \note This function is implemented for both hardware mode and //! simulation mode. CM_RT_API virtual int32_t SetL3Config(const L3ConfigRegisterValues *registerValues) = 0; //! \brief Sets the suggested configuration for L3 cache. //! \param [in] configIndex //! Index of suggested configuration plan. These configurations //! are defined in ::L3_SUGGEST_CONFIG which is a enumeration //! definition. //! \retval CM_SUCCESS if the L3 configuration pointer is set correctly. //! \retval CM_FAILURE if the platform does not support L3 or L3 //! configuration failed to be set. //! \note This function is only implemented for hardware and //! simulation modes. CM_RT_API virtual int32_t SetSuggestedL3Config( L3_SUGGEST_CONFIG configIndex) = 0; //! \brief This function can be used to set/limit hardware //! capabilities- number of threads that HW can run in parallel //! \details Hardware thread number can be set from 1 to maximum. //! \param [in] capName //! Name of cap to set. //! \param [in] capValueSize //! The size of the cap value. //! \param [in] capValue //! Pointer to the cap value. //! \retval CM_SUCCESS if cap value is valid and is set correctly. //! \retval CM_INVALID_HARDWARE_THREAD_NUMBER specific SetCaps error //! message if cap value is not valid. //! \retval CM_NOT_IMPLEMENTED for emulation mode. //! \retval CM_FAILURE otherwise. //! \note The following is the specific behavior for the cap value //! that is being set. //! //! //! //!
Cap name< / th> //! Behavior< / th> //! < / tr> //!
CAP_HW_THREAD_COUNT< / td> //! The number of hardware threads is per - task.A call //! to the SetCaps function to set the CAP_HW_THREAD_COUNT //! will limit the maximum number of hardware threads for //! the ensuing call to Enqueue.After the call to Enqueue, //! the maximum number of hardware threads will be restored //! to its default value, which is determined by the //! hardware's capability. //! < / td> //! < / tr> //! < / table> CM_RT_API virtual int32_t SetCaps(CM_DEVICE_CAP_NAME capName, size_t capValueSize, void* capValue) = 0; //! \brief This function creates a sampler surface index by a given //! CmSurface2D. //! \details This sampler surface doesn't create any actual surface. It //! just binds the actual 2D surface with a virtual sampler //! surface index. User need pass this surface index as kernel //! argument if the surface is used for sampler, otherwise, //! the runtime will report error if user pass the 2D surface //! index. For the 2D surface format, for now supports //! following formats: \n //! CM_SURFACE_FORMAT_A16B16G16R16 \n //! CM_SURFACE_FORMAT_A16B16G16R16F \n //! CM_SURFACE_FORMAT_R32G32B32A32F \n //! CM_SURFACE_FORMAT_A8 \n //! CM_SURFACE_FORMAT_A8R8G8B8 \n //! CM_SURFACE_FORMAT_YUY2 \n //! CM_SURFACE_FORMAT_R32F \n //! CM_SURFACE_FORMAT_R32_UINT \n //! CM_SURFACE_FORMAT_L16 \n //! CM_SURFACE_FORMAT_R16G16_UNORM \n //! CM_SURFACE_FORMAT_R16_FLOAT \n //! CM_SURFACE_FORMAT_NV12 \n //! CM_SURFACE_FORMAT_L8 \n //! CM_SURFACE_FORMAT_AYUV \n //! CM_SURFACE_FORMAT_Y410 \n //! CM_SURFACE_FORMAT_Y416 \n //! CM_SURFACE_FORMAT_Y210 \n //! CM_SURFACE_FORMAT_Y216 \n //! CM_SURFACE_FORMAT_P010 \n //! CM_SURFACE_FORMAT_P016 \n //! CM_SURFACE_FORMAT_YV12 \n //! CM_SURFACE_FORMAT_411P \n //! CM_SURFACE_FORMAT_411R \n //! CM_SURFACE_FORMAT_IMC3 \n //! CM_SURFACE_FORMAT_I420 \n //! CM_SURFACE_FORMAT_422H \n //! CM_SURFACE_FORMAT_422V \n //! CM_SURFACE_FORMAT_444P \n //! CM_SURFACE_FORMAT_P208 \n //! CM_SURFACE_FORMAT_RGBP \n //! CM_SURFACE_FORMAT_BGRP \n //! \param [in] surface2d //! Pointer to CmSurface2D object. //! \param [out] samplerSurfaceIndex //! Reference to the pointer to SurfaceIndex object to be //! created. //! \retval CM_SUCCESS if the new sampler surface index is successfully //! created. //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the input surface format //! is not list above. //! \retval CM_EXCEED_SURFACE_AMOUNT if the total number of //! co-existed surfaces are exceed maximum count. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateSamplerSurface2D( CmSurface2D* surface2d, SurfaceIndex* &samplerSurfaceIndex) = 0; //! \brief This function creates a sampler surface index by a given //! CmSurface3D. //! \details This function call doesn't create any actual surface. It //! just binds the actual 3D surface with a virtual sampler //! surface index. User need pass this surface index as kernel //! argument if the surface is used for sampler, otherwise, the //! runtime will report error if user pass the 3D surface //! index. For the 3D surface format, for now only supports the //! CM_SURFACE_FORMAT_A8R8G8B8 and CM_SURFACE_FORMAT_A16B16G16R16 //! formats. //! \param [in] surface3d //! Pointer to CmSurface3D object. //! \param [out] samplerSurfaceIndex //! Reference to the pointer to SurfaceIndex object to be //! created. //! \retval CM_SUCCESS if the sampler surface index is successfully //! created. //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the input surface format //! is not list above. //! \retval CM_EXCEED_SURFACE_AMOUNT if the total number of created //! co-existed surfaces are exceed maximum count. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateSamplerSurface3D( CmSurface3D* surface3d, SurfaceIndex* &samplerSurfaceIndex) = 0; //! \brief This function destroys a sampler surface index created by //! CreateSamplerSurface2D(), CreateSamplerSurface2DUP, or //! CreateSamplerSurface3D(). //! \details Caller provides the reference of a pointer to the surface //! index needs t be destoryed. //! \param [in] samplerSurfaceIndex //! Reference to the pointer to SurfaceIndex object to be //! destroyed. //! \retval CM_SUCCESS if the sampler surface index is successfully //! destroyed. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroySamplerSurface( SurfaceIndex* & samplerSurfaceIndex) = 0; //! \brief This function creates a buffer to store the message printed //! by printf() in kernel side. //! \details The default size of print buffer is 1M bytes. User can set //! its size according to the length of message printed in //! kernel and the number of threads. printf() can be used for //! kernel debug purpose //! \param [in] printbufsize //! The size of print buffer in bytes. //! \retval CM_SUCCESS if the print buffer is created successfully. //! \retval CM_OUT_OF_HOST_MEMORY if print buffer allication is failed. //! \retval CM_FAILURE otherwise. //! \note Internally the print buffer occupies static buffer index 1, //! thus only other 3 static buffers can be used by host (0, 2, 3) //! if print functionality is enabled. CM_RT_API virtual int32_t InitPrintBuffer(size_t printbufsize = CM_DEFAULT_PRINT_BUFFER_SIZE) = 0; //! \brief This function prints the message on the standard display //! device that are dumped by kernel. //! \details It should be called after the task being finished. The //! order of printf output is not deterministic due to thread //! scheduling and the fact that different threads may be //! interleaved. To distinguish which thread the printf string //! comes from, it is better to print the thread id as the //! first value. Alternatively you could always //! put the printf inside if statement that limits the printf to a //! given thread. If one task has more than one kernels call //! printf() , their outputs could mix together. //! \retval CM_SUCCESS if the buffer is flushed successfully. //! \retval CM_FAILURE otherwise. //! \note See also FlushPrintBufferIntoFile() which is a variant to //! print message to a file. CM_RT_API virtual int32_t FlushPrintBuffer() = 0; //! \brief This function creates a VEBOX object for VEBOX //! operations (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol09-media_vebox.pdf). //! \details Caller provides a reference of CmVebox pointer to get the //! CmVebox object created from this function. //! \param [in, out] vebox //! the created VEBOX object. //! \retval CM_SUCCESS if creation is successfully. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateVebox(CmVebox* &vebox) = 0; //! \brief This function destroys a VEBOX object. //! \details Caller provides a reference of CmVebox pointer to destroy. //! \param [in, out] vebox //! The VEBOX object to be destroyed. It will be assigned to //! nullptr once destroy is done. //! \retval CM_SUCCESS if creation is successfully. //! \retval CM_NULL_POINTER if the pVebox pointer is nullptr. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t DestroyVebox(CmVebox* & vebox) = 0; //! \brief This function get the pointer to VADisplay. //! \details Caller provides a reference of pointer to VADisplay. //! \param [in,out] vaDisplay //! A poniter of type VADisplay for Libva Surface //! \retval CM_SUCCESS always. //! \note This is Linux only API. CM_RT_API virtual int32_t GetVaDpy(VADisplay* &vaDisplay) = 0; //! \brief Create Libva Surface and wrap it as a CmSurface. //! \details It is caller's responsibility to allocation memory for all //! pointers to CmSurface2D. //! \param [in] width //! Surface's width //! \param [in] height //! Surface's height //! \param [in] format //! Surface's format //! \param [out] vaSurfaceId //! Reference to created VASurfaceID //! \param [out] surface //! Reference to pointer of created Cm Surface //! \retval CM_SUCCESS if all CmSurface2D are successfully created //! \retval CM_VA_SURFACE_NOT_SUPPORTED if libva surface creation fail //! \retval CM_FAILURE otherwise. //! \note This is a Linux only API. CM_RT_API virtual int32_t CreateVaSurface2D( uint32_t width, uint32_t height, CM_SURFACE_FORMAT format, VASurfaceID &vaSurfaceId, CmSurface2D* &surface) = 0; //! //! \brief It creates a CmBufferSVM of the specified size in bytes by //! using the SVM (shared virtual memory) system memory. //! (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol05-memory_views.pdf). //! \details The SVM memory can be accessed by both CPU and GPU. The SVM //! memory will be allocated in runtime internally(if user pass //! nullptr pointer) or user provided (if user pass a valid //! pointer). In both way, the memory should be page aligned //! (4K bytes). And the staring address is returned. //! \param [in] size //! SVM buffer size in bytes. //! \param [in,out] sysMem //! Pointer to the SVM memory starting address. //! \param [in] accessFlag //! Buffer access flags. //! \param [out] buffer //! Reference to the pointer to the CmBufferSVM. //! \retval CM_SUCCESS if the CmBufferSVM is successfully created. //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D //! surface fails. //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or //! larger than CM_MAX_1D_SURF_WIDTH. //! \retval CM_OUT_OF_HOST_MEMORY if runtime can't allocate such size //! SVM memory. //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces //! is exceeded. The amount is the amount of the surfaces that //! can co-exist. The amount can be obtained by querying the //! cap CAP_BUFFER_COUNT. //! \retval CM_FAILURE otherwise. //! \note This API is not implemented in Linux for now. //! CM_RT_API virtual int32_t CreateBufferSVM(uint32_t size, void* &sysMem, uint32_t accessFlag, CmBufferSVM* &buffer) = 0; //! //! \brief Destroys CmBufferSVM object and associated SVM memory. //! \param [in,out] buffer //! Reference to the pointer pointing to CmBufferSVM, will be //! assigned to nullptr once it is destroyed successfully. //! \retval CM_SUCCESS if CmBufferSVM and associated SVM meory are //! successfully destroyed. //! \retval CM_FAILURE otherwise. //! CM_RT_API virtual int32_t DestroyBufferSVM( CmBufferSVM* &buffer) = 0; //! //! \brief This function creates a sampler surface index by a //! CmSurface2DUP. //! \details This sampler surface doesn't create any actual surface, //! and just bind the actual 2D UP (User Provided) surface //! with a virtual sampler surface index. User need pass this //! surface index as kernel argument if the surface is used //! for sampler, otherwise, the runtime will report error if //! user pass the 2D UP surface index. For the 2DUP surface //! formats, for now supports following formats: \n //! CM_SURFACE_FORMAT_A16B16G16R16 \n //! CM_SURFACE_FORMAT_A8 \n //! CM_SURFACE_FORMAT_A8R8G8B8 \n //! CM_SURFACE_FORMAT_YUY2 \n //! CM_SURFACE_FORMAT_R32F \n //! CM_SURFACE_FORMAT_R32_UINT \n //! CM_SURFACE_FORMAT_L16 \n //! CM_SURFACE_FORMAT_R16G16_UNORM \n //! CM_SURFACE_FORMAT_NV12 \n //! CM_SURFACE_FORMAT_L8 \n //! CM_SURFACE_FORMAT_AYUV \n //! CM_SURFACE_FORMAT_Y410 \n //! CM_SURFACE_FORMAT_Y416 \n //! CM_SURFACE_FORMAT_Y210 \n //! CM_SURFACE_FORMAT_Y216 \n //! CM_SURFACE_FORMAT_P010 \n //! CM_SURFACE_FORMAT_P016 \n //! CM_SURFACE_FORMAT_YV12 \n //! CM_SURFACE_FORMAT_411P \n //! CM_SURFACE_FORMAT_411R \n //! CM_SURFACE_FORMAT_IMC3 \n //! CM_SURFACE_FORMAT_I420 \n //! CM_SURFACE_FORMAT_422H \n //! CM_SURFACE_FORMAT_422V \n //! CM_SURFACE_FORMAT_444P \n //! CM_SURFACE_FORMAT_P208 \n //! CM_SURFACE_FORMAT_RGBP \n //! CM_SURFACE_FORMAT_BGRP \n //! \param [in] surface2dUP //! Pointer to CmSurface2DUP object. //! \param [out] samplerSurfaceIndex //! Reference to the pointer to SurfaceIndex object to be //! created. //! \retval CM_SUCCESS if the new sampler surface index is //! successfully created. //! \retval CM_NULL_POINTER if p2DUPSurface is nullptr. //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not supported. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory. //! \retval CM_FAILURE otherwise. //! \note This API is supported for HW mode only. //! CM_RT_API virtual int32_t CreateSamplerSurface2DUP( CmSurface2DUP* surface2dUP, SurfaceIndex* & samplerSurfaceIndex) = 0; //! //! \brief Copies the content of source kernel to a new kernel. //! \param [out] destKernel //! pointer to the destination kernel. The new pointer will be //! returned to destKernel. //! \param [in] srcKernel //! pointer to the source kernel. //! \retval CM_SUCCESS If the clone operation is successful. //! \retval CM_FAILURE If the clone operation is failed. //! \note This API is not supported in emulation mode. //! CM_RT_API virtual int32_t CloneKernel(CmKernel * &destKernel, CmKernel *srcKernel) = 0; //! //! \brief Creates an alias to CmSurface2D. //! \details Returns a new surface index for this surface. This API is //! used with CmSurface2D::SetSurfaceStateParam in order //! to reinterpret surface for different surface states, //! i.e., the same memory is used but different width and //! height can be programmed through the surface state. //! \param [in] originalSurface //! pointer to the surface used to create an alias. //! \param [out] aliasSurfaceIndex //! new surface index pointing to 2D surface. //! \retval CM_SUCCESS if alias is created successfully. //! \retval CM_INVALID_ARG_VALUE if p2DSurface is not a valid pointer. //! \retval CM_MAX_NUM_2D_ALIASES if try to create more than 10 aliases //! for same surface. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory. //! \retval CM_FAILURE otherwise. //! \note This API is implemented for HW and SIM modes only. //! CM_RT_API virtual int32_t CreateSurface2DAlias(CmSurface2D* originalSurface, SurfaceIndex* &aliasSurfaceIndex) = 0; //! //! \brief Creates an HEVC VME surface by using the given 2D surfaces: //! the current frame, the forward frames and, the backward //! frames. //! \details No extra surface is actually created. A SurfaceIndex //! object is created instead, which is passed to CM kernel //! function (genx_main) as argument to indicate the frame //! surface. This can be used for Gen10 and plus platforms. //! \param [in] currentSurface //! Pointer to current surface (can't be nullptr). //! \param [in] forwardSurfaceArray //! Array of forward surfaces (can be nullptr if backward //! surfaces not a nullptr). //! \param [in] backwardSurfaceArray //! Array of backward surfaces (can be nullptr if forward //! surfaces not a nullptr). //! \param [in] surfaceCountForward //! Count of forward surfaces, up to 9 forward surfaces can //! be used. //! \param [in] surfaceCountBackward //! Count of backward surfaces, up to 9 backward surfaces can //! be used. //! \param [out] vmeSurfaceIndex //! Reference to pointer to SurfaceIndex object to be created. //! \retval CM_SUCCESS if the SurfaceIndex is successfully created. //! \retval CM_NULL_POINTER if currentSurface is nullptr. //! \retval CM_INVALID_ARG_VALUE if invalid surface pointers for forward //! and backward surfaces. //! \retval CM_EXCEED_SURFACE_AMOUNT if there is too much co-existed //! surfaces are created. Destroying unused surfaces to solve //! such error. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_FAILURE otherwise. //! \note This API is only supported for Gen10 and plus platforms. //! CM_RT_API virtual int32_t CreateHevcVmeSurfaceG10(CmSurface2D* currentSurface, CmSurface2D** forwardSurfaceArray, CmSurface2D** backwardSurfaceArray, const uint32_t surfaceCountForward, const uint32_t surfaceCountBackward, SurfaceIndex* & vmeSurfaceIndex) = 0; //! //! \brief Destroys an HEVC VME surface. This can be used for Gen10. //! \param [in] vmeSurfaceIndex //! Pointer to the SurfaceIndex of the VME surface. It will be //! assigned to nullptr once destroy is done. //! \retval CM_SUCCESS if the HEVC VME surface is successfully destroyed //! \retval CM_FAILURE otherwise. //! \note This API is only supported for Gen10 and plus platforms. \n //! Any HEVC VME surface not destroyed by calling this function //! explicitly will be destroyed when CmDevice is destroyed. //! CM_RT_API virtual int32_t DestroyHevcVmeSurfaceG10(SurfaceIndex* & vmeSurfaceIndex) = 0; //! //! \brief Creates a CmSampler object with border color setting. //! \param [in] sampleState //! Const reference to a CM_SAMPLER_STATE_EX specifying the //! characteristics of the sampler to be created. //! \param [out] sampler //! Reference to the pointer to the CmSampler object. //! \retval CM_SUCCESS if the CmSampler is successfully created. //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory. //! \retval CM_EXCEED_SAMPLER_AMOUNT if maximum amount of sampler is //! exceeded. The amount is the amount of the sampler that can //! co-exist. The amount can be obtained by querying the cap //! CAP_SAMPLER_COUNT. //! \retval CM_FAILURE otherwise. //! \note This API is not implemented for EMU mode. \n Point, linear, //! and anisotropic filter types are supported for hardware and //! simulation modes. \n Wrap, mirror, clamp and border are //! supported in hardware and simulation modes. Clamp is //! supported in emulation mode. //! CM_RT_API virtual int32_t CreateSamplerEx(const CM_SAMPLER_STATE_EX & sampleState, CmSampler* &sampler) = 0; //! //! \brief This function prints the message dumped by kernel into file //! instead of stdout. //! \details This function's usage is the same as //! CmDevice::FlushPrintBuffer(). It is recommended to use this //! interface when there are tons of messages from kernel. //! \param [in] filename //! name of file the message printed into. //! \retval CM_SUCCESS if the buffer is flushed successfully into file. //! \retval CM_FAILURE otherwise. //! \note This is API is supported in hardware mode. See also //! FlushPrintBuffer(). //! CM_RT_API virtual int32_t FlushPrintBufferIntoFile(const char *filename) = 0; //! //! \brief This function creates a 3-dimensional thread group space specified by the //! depth, height and width dimensions of the group space, and //! the depth, the height and width dimensions of the thread //! space within a group. //! \details This information is used to execute a kernel in GPGPU pipe //! (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol07-3d_media_gpgpu.pdf). //! \param [in] threadSpaceWidth //! width in unit of threads of each thread group. //! \param [in] threadSpaceHeight //! height in unit of threads of each thread group. //! \param [in] threadSpaceDepth //! Depth in unit of threads of each thread group. //! \param [in] groupSpaceWidth //! width in unit of groups of thread group space. //! \param [in] groupSpaceHeight //! height in unit of groups of thread group space. //! \param [in] groupSpaceDepth //! Depth in unit of groups of thread group space. //! \param [out] threadGroupSpace //! Reference to the pointer to CmThreadGroupSpace object to be //! created. //! \retval CM_SUCCESS if the CmThreadGroupSpace is successfully created. //! \retval CM_INVALID_THREAD_GROUP_SPACE if any input is 0 or the //! threadSpaceWidth is more than MAX_THREAD_SPACE_WIDTH_PERGROUP, //! or the threadSpaceHeight is more than //! MAX_THREAD_SPACE_HEIGHT_PERGROUP. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory. //! \retval CM_FAILURE otherwise. //! \note The total thread count is //! width*height*depth*grpWidth*grpHeight*grpDepth. //! The function need to be called when Z dimension //! is larger than 1. when thrdSpaceDepth is 1 and grpSpaceDepth //! is 1, it is equivalent to call function //! CmDevice::CreateThreadGroupSpace(uint32_t threadSpaceWidth, uint32_t //! threadSpaceHeight, uint32_t groupSpaceWidth, uint32_t groupSpaceHeight, //! CmThreadGroupSpace* &threadGroupSpace). \n //! See also CmDevice::CreateThreadGroupSpace(). //! CM_RT_API virtual int32_t CreateThreadGroupSpaceEx(uint32_t threadSpaceWidth, uint32_t threadSpaceHeight, uint32_t threadSpaceDepth, uint32_t groupSpaceWidth, uint32_t groupSpaceHeight, uint32_t groupSpaceDepth, CmThreadGroupSpace* &threadGroupSpace) = 0; //! //! \brief Creates a CmSampler8x8 surface by using given 2D surface //! and given flags. //! \details The function indicates the 2D surface is used for sampler //! 8x8; no extra surface is actually created. A SurfaceIndex //! object is created instead, which is passed to CM kernel //! function(genx_main) as argument to indicate the surface for //! sampler 8x8. Compared to CmDeive::CreateSampler8x8Surface, //! this API is used to support rotation and chroma siting for //! MediaSampler. //! \param [in] surface //! Pointer to CmSurface2D. //! \param [out] surfaceIndex //! Reference to pointer to SurfaceIndex. //! \param [in] surfaceType //! Enumeration data type of CM_SAMPLER8x8_SURFACE. //! \param [in] addressControl //! Enumeration data type of CM_SURFACE_ADDRESS_CONTROL_MODE. //! \param [in] flag //! Pointer to CM_FLAG. //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully //! created. //! \retval CM_EXCEED_SURFACE_AMOUNT if there is too many co-existed //! surfaces and exceed the maximum number. Destroying some //! unused surfaces could solve this error. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory //! \retval CM_FAILURE otherwise. //! \note This API is not supported in emulation mode. //! CM_RT_API virtual int32_t CreateSampler8x8SurfaceEx( CmSurface2D *surface, SurfaceIndex* &surfaceIndex, CM_SAMPLER8x8_SURFACE surfaceType, CM_SURFACE_ADDRESS_CONTROL_MODE addressControl = CM_SURFACE_CLAMP, CM_FLAG *flag = nullptr) = 0; //! //! \brief Create sampler surface by using given 2D surface and flags. //! \details This sampler surface does't create any actual surface, and //! just bind the actual 2D surface with a virtual sampler //! surface index. User need pass this surface index as kernel //! argument if the surface is used for sampler, otherwise, //! the runtime will report error if user pass the 2D surface //! index. Compared to CmDevice::CreateSampler8x8Surface, this //! API is used to support rotation for 3D sampler. For given //! surface's formats, for now, we support following: \n //! CM_SURFACE_FORMAT_A16B16G16R16 \n //! CM_SURFACE_FORMAT_A16B16G16R16F \n //! CM_SURFACE_FORMAT_R32G32B32A32F \n //! CM_SURFACE_FORMAT_A8 \n //! CM_SURFACE_FORMAT_A8R8G8B8 \n //! CM_SURFACE_FORMAT_YUY2 \n //! CM_SURFACE_FORMAT_R32F \n //! CM_SURFACE_FORMAT_R32_UINT \n //! CM_SURFACE_FORMAT_L16 \n //! CM_SURFACE_FORMAT_R16G16_UNORM \n //! CM_SURFACE_FORMAT_R16_FLOAT \n //! CM_SURFACE_FORMAT_NV12 \n //! CM_SURFACE_FORMAT_L8 \n //! CM_SURFACE_FORMAT_AYUV \n //! CM_SURFACE_FORMAT_Y410 \n //! CM_SURFACE_FORMAT_Y416 \n //! CM_SURFACE_FORMAT_Y210 \n //! CM_SURFACE_FORMAT_Y216 \n //! CM_SURFACE_FORMAT_P010 \n //! CM_SURFACE_FORMAT_P016 \n //! CM_SURFACE_FORMAT_YV12 \n //! CM_SURFACE_FORMAT_411P \n //! CM_SURFACE_FORMAT_411R \n //! CM_SURFACE_FORMAT_IMC3 \n //! CM_SURFACE_FORMAT_I420 \n //! CM_SURFACE_FORMAT_422H \n //! CM_SURFACE_FORMAT_422V \n //! CM_SURFACE_FORMAT_444P \n //! CM_SURFACE_FORMAT_P208 \n //! CM_SURFACE_FORMAT_RGBP \n //! CM_SURFACE_FORMAT_BGRP \n //! \param [in] surface2d //! Pointer to CmSurface2D object. //! \param [out] samplerSurfaceIndex //! Reference to the pointer to SurfaceIndex object to be //! created. //! \param [in] flag //! Pointer to CM_FLAG. //! \retval CM_SUCCESS if the new sampler surface index is //! successfully created. //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the input surface format //! is not list above. //! \retval CM_EXCEED_SURFACE_AMOUNT if the total number of created //! co-existed surfaces are exceed maximum count. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory. //! \retval CM_FAILURE otherwise. //! \note This API is not supported in emulation mode. //! CM_RT_API virtual int32_t CreateSamplerSurface2DEx(CmSurface2D* surface2d, SurfaceIndex* & samplerSurfaceIndex, CM_FLAG* flag = nullptr) = 0; //! \brief Create an alias to CmBuffer. //! \details Returns a new surface index for this surface. This API is //! used with CmBuffer::SetSurfaceStateParam in order //! to reinterpret buffer for different surface states, //! i.e., the same memory is used but different size //! can be programmed through the surface state. //! \param [in] originalBuffer //! pointer to CmBuffer object used to create an alias. //! \param [out] aliasIndex //! \retval CM_SUCCESS if alias is created successfully. //! new surface index pointing to CmBuffer. //! \retval CM_EXCEED_MAX_NUM_BUFFER_ALIASES if try to create more //! than 10 aliases for same surface. //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory. //! \retval CM_FAILURE if alias cannot be created. //! \note This API is not implemented for EMU mode. //! CM_RT_API virtual int32_t CreateBufferAlias(CmBuffer *originalBuffer, SurfaceIndex* &aliasIndex) = 0; //! \brief Set the width and height values in the VME surface state. //! \param [in] vmeIndex //! Pointer to VME surface index. //! \param [in] surfStateParam //! Pointer to CM_VME_SURFACE_STATE_PARAM to set width and //! height of this surface //! \retval CM_SUCCESS if setting VME surface state values successfully. //! \retval CM_INVALID_ARG_VALUE if invalid input. //! \note This API will work on HW and SIM modes. //! CM_RT_API virtual int32_t SetVmeSurfaceStateParam(SurfaceIndex* vmeIndex, CM_VME_SURFACE_STATE_PARAM *surfStateParam) = 0; //! //! \brief Gets the VISA version up-to which IGC supports. //! \param [out] majorVersion //! The major Version of VISA. //! \param [out] minorVersion //! The minor Version of VISA. //! \retval CM_SUCCESS if get the right VISA version. //! \retval CM_JITDLL_LOAD_FAILURE if loading igc library is failed. //! \retval CM_FAILURE otherwise. //! \note This API is implemented in hardware mode only. //! CM_RT_API virtual int32_t GetVISAVersion(uint32_t& majorVersion, uint32_t& minorVersion) = 0; //! //! \brief Creates a CmQueue object with option. //! \param [out] queue //! Pointer to the CmQueue object created. //! \param [in] createOption //! The option to create a queue. The sturcture of the //! QueueCreateOption is:\n //! \code //! struct CM_QUEUE_CREATE_OPTION //! { //! CM_QUEUE_TYPE QueueType : 3; //! bool RAMode : 1; //! unsigned int Reserved0 : 3; //! bool UserGPUContext : 1; //! unsigned int GPUContext : 8; //! CM_QUEUE_SSEU_USAGE_HINT_TYPE SseuUsageHint : 3; //! unsigned int Reserved1 : 1; //! unsigned int Reserved2 : 12; //! } //! \endcode //! \n //! QueueType indicates which engine the queue will be created for:\n //! \code //! enum CM_QUEUE_TYPE //! { //! CM_QUEUE_TYPE_NONE = 0, //! CM_QUEUE_TYPE_RENDER = 1, //! CM_QUEUE_TYPE_COMPUTE = 2 //! }; //! \endcode //! \n //! RAMode decides if the queue will occupy GPU //! exclusively during execution. //! \n //! UserGPUContext indicates whether a existed GPU context is passed //! by user via below GPUContext field. //! \n //! GPUContext indicates GPU context passed by user. //! \n //! SseuUsageHint indicates SSEU setting, will be created for:\n //! \code //! enum CM_QUEUE_SSEU_USAGE_HINT_TYPE //! { //! CM_QUEUE_SSEU_USAGE_HINT_DEFAULT = 0, //! CM_QUEUE_SSEU_USAGE_HINT_VME = 1 //! }; //! \endcode //! \n //! \retval CM_SUCCESS if the CmQueue object is created. //! \note This API is implemented in hardware mode only. Only //! CM_QUEUE_TYPE_RENDER and CM_QUEUE_TYPE_COMPUTE are //! implemented at this moment. //! CM_RT_API virtual int32_t CreateQueueEx(CmQueue *&queue, CM_QUEUE_CREATE_OPTION createOption) = 0; //! //! \brief It creates a CmBufferStateless of the specified size in bytes by //! using the vedio memory or the system memory. //! \details The stateless buffer means it is stateless-accessed by GPU. There //! are two ways to create a stateless buffer. One is to create from //! vedio memory, then it can be only accessed by GPU. The other way is //! to create from system memory, then it can be accessed by both GPU //! and CPU. In this way, The system memory will be allocated in runtime //! internally(if user pass nullptr pointer) or user provided (if user //! pass a valid pointer). And the system memory should be page aligned //! (4K bytes). //! \param [in] size //! Stateless buffer size in bytes. //! \param [in] option //! Stateless buffer create option. //! \param [in] sysMem //! Pointer to user provided system memory if option is system memory. //! \param [out] pSurface //! Reference to the pointer to the CmBufferStateless. //! \retval CM_SUCCESS if the CmBufferStateless is successfully created. //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D //! surface fails. //! \retval CM_OUT_OF_HOST_MEMORY if runtime can't allocate such size //! system memory. //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces //! is exceeded. The amount is the amount of the surfaces that //! can co-exist. The amount can be obtained by querying the //! cap CAP_BUFFER_COUNT. //! \retval CM_INVALID_CREATE_OPTION_FOR_BUFFER_STATELESS if option is invalid. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateBufferStateless(size_t size, uint32_t option, void *sysMem, CmBufferStateless *&buffer) = 0; //! //! \brief Destroy CmBufferStateless object and associated vedio/system memory. //! \param [in,out] pSurface //! Reference to the pointer pointing to CmBufferStateless, will be //! assigned to nullptr once it is destroyed successfully. //! \retval CM_SUCCESS if CmBufferStateless and associated vedio/system memory are //! successfully destroyed. //! \retval CM_FAILURE otherwise. //! CM_RT_API virtual int32_t DestroyBufferStateless(CmBufferStateless* &buffer) = 0; CM_RT_API virtual int32_t DispatchTask() = 0; //! //! \brief It creates a CmSurface2DStateless of the specified width, height and //! pitch in bytes by using the vedio memory. //! \details The stateless surface means it is stateless-accessed by GPU. It is //! created from vedio memory, and can be only accessed by GPU. //! \param [in] width //! Surface width in bytes. //! \param [in] width //! Surface height in bytes. //! \param [out] pitch //! Surface pitch in bytes. //! \param [out] pSurface //! Reference to the pointer to the CmSurface2DStateless. //! \retval CM_SUCCESS if the CmSurface2DStateless is successfully created. //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 2D //! surface fails. //! \retval CM_OUT_OF_HOST_MEMORY if runtime can't allocate such size //! system memory. //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces //! is exceeded. The amount is the amount of the surfaces that //! can co-exist. The amount can be obtained by querying the //! cap CAP_SURFACE2D_COUNT. //! \retval CM_FAILURE otherwise. CM_RT_API virtual int32_t CreateSurface2DStateless(uint32_t width, uint32_t height, uint32_t &pitch, CmSurface2DStateless *&pSurface) = 0; //! //! \brief Destroy CmSurface2DStateless object and associated vedio memory. //! \param [in,out] pSurface //! Reference to the pointer pointing to CmSurface2DStateless, will be //! assigned to nullptr once it is destroyed successfully. //! \retval CM_SUCCESS if CmSurface2DStateless and associated vedio memory are //! successfully destroyed. //! \retval CM_FAILURE otherwise. //! CM_RT_API virtual int32_t DestroySurface2DStateless(CmSurface2DStateless *&pSurface) = 0; protected: virtual ~CmDevice() = default; }; #endif // #ifndef CMRTLIB_LINUX_SHARE_CM_DEVICE_BASE_H_