/* * 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. */ //! //! \file cm_buffer.h //! \brief Contains Class CmBuffer/CmBufferUp definitions //! #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMBUFFER_H_ #define MEDIADRIVER_AGNOSTIC_COMMON_CM_CMBUFFER_H_ #include "cm_def.h" // Parameters used to set the surface state of the buffer struct CM_BUFFER_STATE_PARAM { uint32_t uiSize; uint32_t uiBaseAddressOffset; CM_SURFACE_MEM_OBJ_CTRL mocs; }; namespace CMRT_UMD { class CmEvent; //! \brief CmBufferSVM Class to manage SVM (Shared Virtual Memory) resource. //! \details CmBufferSVM represents a 1D surface in SVM (Shared Virtual Memory) //! memory space that is shared between CPU and GPU. The SVM memory must //! be page(4K Bytes) aligned and runtime allocates SVM memory when //! CmDevice::CreateBufferSVM is called. CPU can access the memory by using //! the address returned by GetAddress. GPU can access the memory in two ways //! One way is to use the surfaceIndex returned by GetIndex, similiar to all //! other surfaces and buffers. The other way is to pass the address to CM //! kernel function(genx_main) as an argument for kernel to use. //! \note Right now BufferSVM feature is not working on Linux yet. class CmBufferSVM { public: //! //! \brief This function returns the SurfaceIndex object associated //! with the SVM resource. //! \param [out] index //! Reference to the pointer to SurfaceIndex. //! \returns CM_SUCCESS. //! CM_RT_API virtual int32_t GetIndex(SurfaceIndex* &index) = 0; //! //! \brief Get the pointer of allocated SVM memory starting address. //! \param [out] addr //! return the allocated SVM memory starting address. //! \returns CM_SUCCESS. //! CM_RT_API virtual int32_t GetAddress(void* &addr) = 0; }; //! //! \brief CmBufferUP class to manage 1D surface in user provided system memory. //! \details CmBufferUP represents a 1D surface in system memory. It is //! created upon the UP(User Provided) memory. The UP memory //! must be page(4K Bytes) aligned. CPU can access the memory //! as usual.Each CmBufferUP object is associated with a SurfaceIndex //! object containing a unique index value the surface is mapped to //! when created by the CmDevice.The CmDevice keeps the mapping b/w //! index and CmBufferUP. The SurfaceIndex is passed to CM kernel //! function(genx_main) as argument to indicate the surface. It is //! application's responsibility to make sure the accesses from CPU //! and GPU are not overlapped. //! class CmBufferUP { public: //! //! \brief This function returns the SurfaceIndex object associated //! with this CmBufferUp object. //! \param [out] index //! Reference to the pointer to SurfaceIndex. //! \returns CM_SUCCESS. //! CM_RT_API virtual int32_t GetIndex(SurfaceIndex* &index) = 0; //! //! \brief Selects one of the pre-defined memory object control //! settings for this buffer. //! \param [in] memCtrl //! The selected pre-defined memory object control setting. //! \retval CM_SUCCESS if the memory object control is set successfully. //! \retval CM_FAILURE otherwise. //! \note This API is only supported for Gen9 and plus platform. //! CM_RT_API virtual int32_t SelectMemoryObjectControlSetting(MEMORY_OBJECT_CONTROL memCtrl) = 0; //! //! \brief Selects one of the pre-defined mos resource usage //! this cm_buffer //! \note This function works on Gen9+ paltforms. //! \param [in] mosUsage //! The selected pre-defined MOS resource usage for memory object control setting. //! \retval CM_SUCCESS if the given parameter is valid //! \retval CM_FAILURE otherwise. //! CMRT_UMD_API virtual int32_t SetResourceUsage(const MOS_HW_RESOURCE_DEF mosUsage) = 0; }; //! //! \brief CmBuffer Class to manage 1D surface in video memory. //! \details CmBuffer represents a 1D surface in video memory. Each CmBuffer //! object is associated with a SurfaceIndex object containing a //! unique index value the surface is mapped to when created by the //! CmDevice. The CmDevice keeps the mapping b/w index and CmBuffer. //! The SurfaceIndex is passed to CM kernel function (genx_main) as //! argument to indicate the surface. //! class CmBuffer { public: //! //! \brief This function returns the SurfaceIndex object associated //! with this CmBuffer object. //! \param [out] index //! Reference to the pointer to SurfaceIndex. //! \returns CM_SUCCESS. //! CM_RT_API virtual int32_t GetIndex(SurfaceIndex* &index) = 0; //! //! \brief Copies data in this buffer to system memory using CPU. //! \details The size of data copied is the size of data in buffer.This //! API is a blocking function, i.e. the function will not //! return until the copy operation is completed. Buffer //! reading will not happen until the status of the dependent //! event becomes CM_STATUS_FINISHED. It is application's //! responsibility to make sure no other task enqueued after //! the task corresponding to the dependent task but before //! ReadSurface. If sysMemSize is given, it will be checked //! against the size needed for the buffer. If the sysMemSize //! is less than the CmBuffer size, copy only happens for sysMemSize //! bytes, not all data in CmBuffer. //! \param [out] sysMem //! Pointer to the system memory receiving buffer data. //! \param [in] event //! Pointer to the dependent event used for sychronization. //! \param [in] sysMemSize //! Size of the system memory in byte. //! \retval CM_SUCCESS if copy is successful. //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr. //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed. //! \retval CM_FAILURE otherwise. //! CM_RT_API virtual int32_t ReadSurface(unsigned char* sysMem, CmEvent* event, uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0; //! //! \brief Copies system memory content to this buffer usingg CPU. //! \details The size of data copied is the size of data in the //! buffer. This is a blocking function, i.e. the function will //! not return until the copy operation is completed. Buffer //! writing will not happen until the status of the dependent //! event becomes CM_STATUS_FINISHED. The dependent event for //! WriteSurface is usually NULL. If sysMemSize is given, it //! will be checked against the size needed for the buffer. //! If the sysMemSize is less than the CmBuffer size, copy only //! happens for sysMemSize bytes, not all data in CmBuffer. //! \param [in] sysMem //! Pointer to the system memory storing the buffer data. //! \param [in] event //! Pointer to the dependent event used for sychronization. //! \param [in] sysMemSize //! Size of the system memory in byte. //! \retval CM_SUCCESS if copy is successful. //! \retval CM_INVALID_ARG_VALUE if sysMem pointer is nullptr. //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed. //! \retval CM_FAILURE otherwise. //! CM_RT_API virtual int32_t WriteSurface(const unsigned char* sysMem, CmEvent* event, uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0; //! //! \brief Sets memory in this buffer to uint32_t value using CPU. //! \details The size of data initialized is the size of data in the //! buffer. This is a blocking function, i.e. the function will //! not return until the set operation is completed. Buffer //! initialization will not happen until the status of the //! dependent event becomes CM_STATUS_FINISHED. The dependent //! event for InitSurface is usually NULL. //! \param [in] initValue //! uint32_t value used to initialize to. //! \param [in] event //! Pointer to the dependent event used for sychronization. //! \retval CM_SUCCESS if copy is successful. //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed. //! \retval CM_FAILURE otherwise. //! CM_RT_API virtual int32_t InitSurface(const uint32_t initValue, CmEvent* event) = 0; //! //! \brief Selects one of the pre-defined memory object control //! settings for this buffer. //! \param [in] memCtrl //! The selected pre-defined memory object control setting. //! \retval CM_SUCCESS if the memory object control is set successfully. //! \retval CM_FAILURE otherwise. //! \note This API is only supported for Gen9 and plus platform. //! CM_RT_API virtual int32_t SelectMemoryObjectControlSetting(MEMORY_OBJECT_CONTROL memCtrl) = 0; //! //! \brief Sets the surface state of this buffer. //! \details Set the new size, offset, and mocs to the surface index, //! so they will take effect during surface state setting. //! Usually, the surface index is an alias surface index created //! by calling CmDevice::CreateBufferAlias. This function can be used to //! reinterpret the size, offset, and mocs of an existing CmBuffer. //! \param [in] surfIndex //! Pointer to surface index of this buffer. //! \param [in] bufferStateParam //! The surface state parameter of this buffer. It contains //! size, base address offset and memory object control setting. The //! offset must be 16-aligned due to hardware requirement. //! \retval CM_SUCCESS if the surface state is set successfully. //! \retval CM_INVALID_ARG_VALUE if the surface state parameter is //! invalid. //! \retval CM_NULL_POINTER if any internal used pointer is nullptr. //! \retval CM_FAILURE otherwise. //! CM_RT_API virtual int32_t SetSurfaceStateParam(SurfaceIndex *surfIndex, const CM_BUFFER_STATE_PARAM *bufferStateParam) = 0; //! //! \brief Selects one of the pre-defined mos resource usage //! settings for this buffer. //! \note This function works on Gen9+ paltforms. //! \param [in] mosUsage //! The selected pre-defined MOS resource usage for memory object control setting. //! \retval CM_SUCCESS if the memory object control is set successfully. //! \retval CM_FAILURE otherwise. //! \note This API is only supported for Gen9 and plus platform. //! CMRT_UMD_API virtual int32_t SetResourceUsage(const MOS_HW_RESOURCE_DEF mosUsage) = 0; }; //! \brief CmBufferStateless Class to manage 1D surface created from vedio or //! system memory. //! \details CmBufferStateless represents a 1D surface in vedio memory or system //! space that is stateless-accessed by GPU. The stateless buffer can be //! created from vedio memory, which can be only accessed by GPU. It also //! can be created from system memory, which is local shared memor //! between GPU and CPU and can be access by both GPU and CPU. GPU can //! access the memory by passing the graphics address to CM kernel //! function(genx_main) as an argument for kernel to use. CPU can access the //! system address dirtectly. class CmBufferStateless { public: //! //! \brief Get the staring address in graphics memory space. //! \param [out] gfxAddr //! Staring address in graphics memory space. //! \returns CM_SUCCESS. //! CM_RT_API virtual int32_t GetGfxAddress(uint64_t &gfxAddr) = 0; //! //! \brief Get the starting address in system memory space. //! \param [out] sysAddr //! Starting address in system memory space. //! \returns CM_SUCCESS. //! CM_RT_API virtual int32_t GetSysAddress(void *&sysAddr) = 0; //! //! \brief Copies data in stateless buffer to system memory using CPU. //! \details The size of data copied is the size of data in buffer.This //! API is a blocking function, i.e. the function will not //! return until the copy operation is completed. Buffer //! reading will not happen until the status of the dependent //! event becomes CM_STATUS_FINISHED. It is application's //! responsibility to make sure no other task enqueued after //! the task corresponding to the dependent task but before //! ReadSurface. If sysMemSize is given, it will be checked //! against the size needed for the buffer. If the sysMemSize //! is less than the CmBufferStateless size, copy only happens //! for sysMemSize bytes, not all data in CmBufferStateless. //! \param [out] sysMem //! Pointer to the system memory receiving buffer data. //! \param [in] event //! Pointer to the dependent event used for sychronization. //! \param [in] sysMemSize //! Size of the system memory in byte. //! \retval CM_SUCCESS if copy is successful. //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr. //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed. //! \retval CM_FAILURE otherwise. //! CM_RT_API virtual int32_t ReadSurface(unsigned char *sysMem, CmEvent *event, uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0; //! //! \brief Copies system memory content to stateless buffer usingg CPU. //! \details The size of data copied is the size of data in the //! buffer. This is a blocking function, i.e. the function will //! not return until the copy operation is completed. Buffer //! writing will not happen until the status of the dependent //! event becomes CM_STATUS_FINISHED. The dependent event for //! WriteSurface is usually NULL. If sysMemSize is given, it //! will be checked against the size needed for the buffer. //! If the sysMemSize is less than the CmBufferStateless size, //! copy onlyhappens for sysMemSize bytes, not all data in //! CmBufferStateless. //! \param [in] sysMem //! Pointer to the system memory storing the buffer data. //! \param [in] event //! Pointer to the dependent event used for sychronization. //! \param [in] sysMemSize //! Size of the system memory in byte. //! \retval CM_SUCCESS if copy is successful. //! \retval CM_INVALID_ARG_VALUE if sysMem pointer is nullptr. //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed. //! \retval CM_FAILURE otherwise. //! CM_RT_API virtual int32_t WriteSurface(const unsigned char *sysMem, CmEvent *event, uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0; }; }//namespace #endif // #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMBUFFER_H_