/*************************************************************************/ /*! @File @Title Device Memory Management core @Copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved @Description Client side part of device memory management -- This file defines the exposed Services API to core memory management functions. @License Dual MIT/GPLv2 The contents of this file are subject to the MIT license as set out below. 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. Alternatively, the contents of this file may be used under the terms of the GNU General Public License Version 2 ("GPL") in which case the provisions of GPL are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of GPL, and not to allow others to use your version of this file under the terms of the MIT license, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by GPL as set out in the file called "GPL-COPYING" included in this distribution. If you do not delete the provisions above, a recipient may use your version of this file under the terms of either the MIT license or GPL. This License is also included in this distribution in the file called "MIT-COPYING". EXCEPT AS OTHERWISE STATED IN A NEGOTIATED AGREEMENT: (A) 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; AND (B) 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 PVRSRV_DEVMEM_H #define PVRSRV_DEVMEM_H #if defined __cplusplus extern "C" { #endif #include "img_types.h" #include "devicemem_typedefs.h" #include "pdumpdefs.h" #include "pvrsrv_error.h" #include "pvrsrv_memallocflags.h" #include #include "services_km.h" /* for PVRSRV_DEV_CONNECTION */ /* Device memory contexts, heaps and memory descriptors are passed through to underlying memory APIs directly, but are to be regarded as an opaque handle externally. */ typedef struct _PVRSRV_DEVMEMCTX_ *PVRSRV_DEVMEMCTX; /*!< Device-Mem Client-Side Interface: Typedef for Context Ptr */ typedef DEVMEM_HEAP *PVRSRV_HEAP; /*!< Device-Mem Client-Side Interface: Typedef for Heap Ptr */ typedef DEVMEM_MEMDESC *PVRSRV_MEMDESC; /*!< Device-Mem Client-Side Interface: Typedef for Memory Descriptor Ptr */ typedef DEVMEM_EXPORTCOOKIE PVRSRV_DEVMEM_EXPORTCOOKIE; /*!< Device-Mem Client-Side Interface: Typedef for Export Cookie */ typedef DEVMEM_FLAGS_T PVRSRV_MEMMAP_FLAGS_T; /*!< Device-Mem Client-Side Interface: Typedef for Memory-Mapping Flags Enum */ typedef IMG_HANDLE PVRSRV_REMOTE_DEVMEMCTX; /*!< Type to use with context export import */ typedef struct _PVRSRV_EXPORT_DEVMEMCTX_ *PVRSRV_EXPORT_DEVMEMCTX; /* To use with PVRSRVSubAllocDeviceMem() as the default factor if no * over-allocation is desired. */ #define PVRSRV_DEVMEM_PRE_ALLOC_MULTIPLIER_NONE DEVMEM_NO_PRE_ALLOCATE_MULTIPLIER /* N.B. Flags are now defined in pvrsrv_memallocflags.h as they need to be omnipresent. */ /* * * API functions * */ /**************************************************************************/ /*! @Function PVRSRVCreateDeviceMemContext @Description Creates a device memory context. There is a one-to-one correspondence between this context data structure and the top level MMU page table (known as the Page Catalogue, in the case of a 3-tier MMU). It is intended that a process with its own virtual space on the CPU will also have its own virtual space on the GPU. Thus there is loosely a one-to-one correspondence between process and device memory context, but this is not enforced at this API. Every process must create the device memory context before any memory allocations are made, and is responsible for freeing all such allocations before destroying the context This is a wrapper function above the "bare-metal" device memory context creation function which would create just a context and no heaps. This function will also create the heaps, according to the heap config that the device specific initialization code has nominated for use by this API. The number of heaps thus created is returned to the caller, such that the caller can allocate an array and the call in to fetch details of each heap, or look up the heap with the "Find Heap" API described below. In order to derive the details of the MMU configuration for the device, and for retrieving the "bridge handle" for communication internally in services, it is necessary to pass in a PVRSRV_DEV_CONNECTION. @Input psDev dev data @Output phCtxOut On success, the returned DevMem Context. The caller is responsible for providing storage for this. @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ extern IMG_IMPORT PVRSRV_ERROR PVRSRVCreateDeviceMemContext(PVRSRV_DEV_CONNECTION *psDevConnection, PVRSRV_DEVMEMCTX *phCtxOut); /**************************************************************************/ /*! @Function PVRSRVDestroyDeviceMemContext @Description Destroy cannot fail. Well. It shouldn't, assuming the caller has obeyed the protocol, i.e. has freed all his allocations beforehand. @Input hCtx Handle to a DevMem Context @Return None */ /***************************************************************************/ extern IMG_IMPORT void PVRSRVDestroyDeviceMemContext(PVRSRV_DEVMEMCTX hCtx); /**************************************************************************/ /*! @Function PVRSRVFindHeapByName @Description Returns the heap handle for the named heap which is assumed to exist in this context. PVRSRV_HEAP *phHeapOut, N.B. No need for acquire/release semantics here, as when using this wrapper layer, the heaps are automatically instantiated at context creation time and destroyed when the context is destroyed. The caller is required to know the heap names already as these will vary from device to device and from purpose to purpose. @Input hCtx Handle to a DevMem Context @Input pszHeapName Name of the heap to look for @Output phHeapOut a handle to the heap, for use in future calls to OpenAllocation / AllocDeviceMemory / Map DeviceClassMemory, etc. (The PVRSRV_HEAP type to be regarded by caller as an opaque, but strongly typed, handle) @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ extern IMG_IMPORT PVRSRV_ERROR PVRSRVFindHeapByName(PVRSRV_DEVMEMCTX hCtx, const IMG_CHAR *pszHeapName, PVRSRV_HEAP *phHeapOut); /**************************************************************************/ /*! @Function PVRSRVDevmemGetHeapBaseDevVAddr @Description returns the device virtual address of the base of the heap. @Input hHeap Handle to a Heap @Output pDevVAddr On success, the device virtual address of the base of the heap. @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ IMG_IMPORT PVRSRV_ERROR PVRSRVDevmemGetHeapBaseDevVAddr(PVRSRV_HEAP hHeap, IMG_DEV_VIRTADDR *pDevVAddr); /**************************************************************************/ /*! @Function PVRSRVSubAllocDeviceMem @Description Allocate memory from the specified heap, acquiring physical memory from OS as we go and mapping this into the GPU (mandatorily) and CPU (optionally) Size must be a positive integer multiple of alignment, or, to put it another way, the uiLog2Align LSBs should all be zero, but at least one other bit should not be. Caller to take charge of the PVRSRV_MEMDESC (the memory descriptor) which is to be regarded as an opaque handle. If the allocation is supposed to be used with PVRSRVDevmemUnpin() the size must be a page multiple. This is a general rule when suballocations are to be avoided. @Input uiPreAllocMultiplier Size factor for internal pre-allocation of memory to make subsequent calls with the same flags faster. Independently if a value is set, the function will try to allocate from any pre-allocated memory first and -if successful- not pre-allocate anything more. That means the factor can always be set and the correct thing will be done internally. @Input hHeap Handle to the heap from which memory will be allocated @Input uiSize Amount of memory to be allocated. @Input uiLog2Align LOG2 of the required alignment @Input uiMemAllocFlags Allocation Flags @Input pszText Text to describe the allocation @Output phMemDescOut On success, the resulting memory descriptor @Return PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ extern IMG_IMPORT PVRSRV_ERROR PVRSRVSubAllocDeviceMem(IMG_UINT8 uiPreAllocMultiplier, PVRSRV_HEAP hHeap, IMG_DEVMEM_SIZE_T uiSize, IMG_DEVMEM_LOG2ALIGN_T uiLog2Align, PVRSRV_MEMALLOCFLAGS_T uiMemAllocFlags, const IMG_CHAR *pszText, PVRSRV_MEMDESC *phMemDescOut); #define PVRSRVAllocDeviceMem(...) \ PVRSRVSubAllocDeviceMem(PVRSRV_DEVMEM_PRE_ALLOC_MULTIPLIER_NONE, __VA_ARGS__) /**************************************************************************/ /*! @Function PVRSRVFreeDeviceMem @Description Free that allocated by PVRSRVSubAllocDeviceMem (Memory descriptor will be destroyed) @Input hMemDesc Handle to the descriptor of the memory to be freed @Return None */ /***************************************************************************/ extern IMG_IMPORT void PVRSRVFreeDeviceMem(PVRSRV_MEMDESC hMemDesc); /**************************************************************************/ /*! @Function PVRSRVAcquireCPUMapping @Description Causes the allocation referenced by this memory descriptor to be mapped into cpu virtual memory, if it wasn't already, and the CPU virtual address returned in the caller-provided location. The caller must call PVRSRVReleaseCPUMapping to advise when he has finished with the mapping. Does not accept unpinned allocations. Returns PVRSRV_ERROR_INVALID_MAP_REQUEST if an unpinned MemDesc is passed in. @Input hMemDesc Handle to the memory descriptor for which a CPU mapping is required @Output ppvCpuVirtAddrOut On success, the caller's ptr is set to the new CPU mapping @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ extern IMG_IMPORT PVRSRV_ERROR PVRSRVAcquireCPUMapping(PVRSRV_MEMDESC hMemDesc, void **ppvCpuVirtAddrOut); /**************************************************************************/ /*! @Function PVRSRVReleaseCPUMapping @Description Relinquishes the cpu mapping acquired with PVRSRVAcquireCPUMapping() @Input hMemDesc Handle of the memory descriptor @Return None */ /***************************************************************************/ extern IMG_IMPORT void PVRSRVReleaseCPUMapping(PVRSRV_MEMDESC hMemDesc); /**************************************************************************/ /*! @Function PVRSRVMapToDevice @Description Map allocation into the device MMU. This function must only be called once, any further calls will return PVRSRV_ERROR_DEVICEMEM_ALREADY_MAPPED The caller must call PVRSRVReleaseDeviceMapping when they are finished with the mapping. Does not accept unpinned allocations. Returns PVRSRV_ERROR_INVALID_MAP_REQUEST if an unpinned MemDesc is passed in. @Input hMemDesc Handle of the memory descriptor @Input hHeap Device heap to map the allocation into @Output psDevVirtAddrOut Device virtual address @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ extern IMG_IMPORT PVRSRV_ERROR PVRSRVMapToDevice(PVRSRV_MEMDESC hMemDesc, PVRSRV_HEAP hHeap, IMG_DEV_VIRTADDR *psDevVirtAddrOut); /**************************************************************************/ /*! @Function PVRSRVMapToDeviceAddress @Description Same as PVRSRVMapToDevice but caller chooses the address to map into. The caller is able to overwrite existing mappings so never use this function on a heap where PVRSRVMapToDevice() has been used before or will be used in the future. In general the caller has to know which regions of the heap have been mapped already and should avoid overlapping mappings. @Input hMemDesc Handle of the memory descriptor @Input hHeap Device heap to map the allocation into @Output sDevVirtAddr Device virtual address to map to @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ extern IMG_IMPORT PVRSRV_ERROR PVRSRVMapToDeviceAddress(DEVMEM_MEMDESC *psMemDesc, DEVMEM_HEAP *psHeap, IMG_DEV_VIRTADDR sDevVirtAddr); /**************************************************************************/ /*! @Function PVRSRVAcquireDeviceMapping @Description Acquire a reference on the device mapping the allocation. If the allocation wasn't mapped into the device then and the device virtual address returned in the PVRSRV_ERROR_DEVICEMEM_NO_MAPPING will be returned as PVRSRVMapToDevice must be called first. The caller must call PVRSRVReleaseDeviceMapping when they are finished with the mapping. Does not accept unpinned allocations. Returns PVRSRV_ERROR_INVALID_MAP_REQUEST if an unpinned MemDesc is passed in. @Input hMemDesc Handle to the memory descriptor for which a device mapping is required @Output psDevVirtAddrOut On success, the caller's ptr is set to the new device mapping @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ extern IMG_IMPORT PVRSRV_ERROR PVRSRVAcquireDeviceMapping(PVRSRV_MEMDESC hMemDesc, IMG_DEV_VIRTADDR *psDevVirtAddrOut); /**************************************************************************/ /*! @Function PVRSRVReleaseDeviceMapping @Description Relinquishes the device mapping acquired with PVRSRVAcquireDeviceMapping or PVRSRVMapToDevice @Input hMemDesc Handle of the memory descriptor @Return None */ /***************************************************************************/ extern IMG_IMPORT void PVRSRVReleaseDeviceMapping(PVRSRV_MEMDESC hMemDesc); /*************************************************************************/ /*! @Function PVRSRVDevmemLocalImport @Description Import a PMR that was created with this connection. The general usage of this function is as follows: 1) Create a devmem allocation on server side. 2) Pass back the PMR of that allocation to client side by creating a handle of type PMR_LOCAL_EXPORT_HANDLE. 3) Pass the PMR_LOCAL_EXPORT_HANDLE to PVRSRVMakeLocalImportHandle()to create a new handle type (DEVMEM_MEM_IMPORT) that can be used with this function. @Input hExtHandle External memory handle @Input uiFlags Import flags @Output phMemDescPtr Created MemDesc @Output puiSizePtr Size of the created MemDesc @Input pszAnnotation Annotation string for this allocation/import @Return PVRSRV_OK is successful */ /*****************************************************************************/ PVRSRV_ERROR PVRSRVDevmemLocalImport(const PVRSRV_DEV_CONNECTION *psDevConnection, IMG_HANDLE hExtHandle, PVRSRV_MEMMAP_FLAGS_T uiFlags, PVRSRV_MEMDESC *phMemDescPtr, IMG_DEVMEM_SIZE_T *puiSizePtr, const IMG_CHAR *pszAnnotation); /*************************************************************************/ /*! @Function PVRSRVDevmemGetImportUID @Description Get the UID of the import that backs this MemDesc @Input hMemDesc MemDesc @Return UID of import */ /*****************************************************************************/ PVRSRV_ERROR PVRSRVDevmemGetImportUID(PVRSRV_MEMDESC hMemDesc, IMG_UINT64 *pui64UID); /**************************************************************************/ /*! @Function PVRSRVAllocExportableDevMem @Description Allocate memory without mapping into device memory context. This memory is exported and ready to be mapped into the device memory context of other processes, or to CPU only with PVRSRVMapMemoryToCPUOnly(). The caller agrees to later call PVRSRVFreeUnmappedExportedMemory(). The caller must give the page size of the heap into which this memory may be subsequently mapped, or the largest of such page sizes if it may be mapped into multiple places. This information is to be communicated in the Log2Align field. Size must be a positive integer multiple of the page size @Input uiLog2Align Log2 of the alignment required @Input uiLog2HeapPageSize The page size to allocate. Must be a multiple of the heap that this is going to be mapped into. @Input uiSize the amount of memory to be allocated @Input uiFlags Allocation flags @Input pszText Text to describe the allocation @Output hMemDesc @Return PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVAllocExportableDevMem(const PVRSRV_DEV_CONNECTION *psDevConnection, IMG_DEVMEM_SIZE_T uiSize, IMG_DEVMEM_LOG2ALIGN_T uiLog2Align, IMG_UINT32 uiLog2HeapPageSize, PVRSRV_MEMALLOCFLAGS_T uiFlags, const IMG_CHAR *pszText, PVRSRV_MEMDESC *hMemDesc); /**************************************************************************/ /*! @Function PVRSRVChangeSparseDevMem @Description This function alters the underlying memory layout of the given allocation by allocating/removing pages as requested This function also re-writes the GPU & CPU Maps accordingly The specific actions can be controlled by corresponding flags @Input psMemDesc The memory layout that needs to be modified @Input ui32AllocPageCount New page allocation count @Input pai32AllocIndices New page allocation indices (page granularity) @Input ui32FreePageCount Number of pages that need to be freed @Input pai32FreeIndices Indices of the pages that need to be freed @Input uiFlags Flags that control the behaviour of the call @Return PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVChangeSparseDevMem(PVRSRV_MEMDESC psMemDesc, IMG_UINT32 ui32AllocPageCount, IMG_UINT32 *pai32AllocIndices, IMG_UINT32 ui32FreePageCount, IMG_UINT32 *pai32FreeIndices, SPARSE_MEM_RESIZE_FLAGS uiFlags); /**************************************************************************/ /*! @Function PVRSRVAllocSparseDevMem2 @Description Allocate sparse memory without mapping into device memory context. Sparse memory is used where you have an allocation that has a logical size (i.e. the amount of VM space it will need when mapping it into a device) that is larger than the amount of physical memory that allocation will use. An example of this is a NPOT texture where the twiddling algorithm requires you to round the width and height to next POT and so you know there will be pages that are never accessed. This memory is can to be exported and mapped into the device memory context of other processes, or to CPU. Size must be a positive integer multiple of the page size @Input psDevConnection Device to allocation the memory for @Input uiSize The logical size of allocation @Input uiChunkSize The size of the chunk @Input ui32NumPhysChunks The number of physical chunks required @Input ui32NumVirtChunks The number of virtual chunks required @Input pui32MappingTable index based Mapping table @Input uiLog2Align Log2 of the required alignment @Input uiLog2HeapPageSize Log2 of the heap we map this into @Input uiFlags Allocation flags @Input pszText Text to describe the allocation @Output hMemDesc @Return PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVAllocSparseDevMem2(const PVRSRV_DEVMEMCTX psDevMemCtx, IMG_DEVMEM_SIZE_T uiSize, IMG_DEVMEM_SIZE_T uiChunkSize, IMG_UINT32 ui32NumPhysChunks, IMG_UINT32 ui32NumVirtChunks, IMG_UINT32 *pui32MappingTable, IMG_DEVMEM_LOG2ALIGN_T uiLog2Align, IMG_UINT32 uiLog2HeapPageSize, PVRSRV_MEMMAP_FLAGS_T uiFlags, const IMG_CHAR *pszText, PVRSRV_MEMDESC *hMemDesc); /**************************************************************************/ /*! @Function PVRSRVAllocSparseDevMem (DEPRECATED and will be removed in future) @Description Allocate sparse memory without mapping into device memory context. Sparse memory is used where you have an allocation that has a logical size (i.e. the amount of VM space it will need when mapping it into a device) that is larger than the amount of physical memory that allocation will use. An example of this is a NPOT texture where the twiddling algorithm requires you to round the width and height to next POT and so you know there will be pages that are never accessed. This memory is can to be exported and mapped into the device memory context of other processes, or to CPU. Size must be a positive integer multiple of the page size This function is deprecated and should not be used in any new code It will be removed in the subsequent changes. @Input psDevConnection Device to allocation the memory for @Input uiSize The logical size of allocation @Input uiChunkSize The size of the chunk @Input ui32NumPhysChunks The number of physical chunks required @Input ui32NumVirtChunks The number of virtual chunks required @Input pabMappingTable boolean based Mapping table @Input uiLog2Align Log2 of the required alignment @Input uiLog2HeapPageSize Log2 of the heap we map this into @Input uiFlags Allocation flags @Input pszText Text to describe the allocation @Output hMemDesc @Return PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVAllocSparseDevMem(const PVRSRV_DEVMEMCTX psDevMemCtx, IMG_DEVMEM_SIZE_T uiSize, IMG_DEVMEM_SIZE_T uiChunkSize, IMG_UINT32 ui32NumPhysChunks, IMG_UINT32 ui32NumVirtChunks, IMG_BOOL *pabMappingTable, IMG_DEVMEM_LOG2ALIGN_T uiLog2Align, IMG_UINT32 uiLog2HeapPageSize, DEVMEM_FLAGS_T uiFlags, const IMG_CHAR *pszText, PVRSRV_MEMDESC *hMemDesc); /**************************************************************************/ /*! @Function PVRSRVGetOSLog2PageSize @Description Just call AFTER setting up the connection to the kernel module otherwise it will run into an assert. Gives the log2 of the page size that is utilised by the OS. @Return The page size */ /***************************************************************************/ IMG_UINT32 PVRSRVGetOSLog2PageSize(void); /**************************************************************************/ /*! @Function PVRSRVGetHeapLog2PageSize @Description Queries the page size of a passed heap. @Input hHeap Heap that is queried @Output puiLog2PageSize Log2 page size will be returned in this @Return PVRSRV_OK on success. Otherwise, a PVRSRV error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVGetHeapLog2PageSize(PVRSRV_HEAP hHeap, IMG_UINT32* puiLog2PageSize); /**************************************************************************/ /*! @Function PVRSRVGetHeapTilingProperties @Description Queries the import alignment and tiling stride conversion factor of a passed heap. @Input hHeap Heap that is queried @Output puiLog2ImportAlignment Log2 import alignment will be returned in this @Output puiLog2TilingStrideFactor Log2 alignment to tiling stride conversion factor will be returned in this @Return PVRSRV_OK on success. Otherwise, a PVRSRV error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVGetHeapTilingProperties(PVRSRV_HEAP hHeap, IMG_UINT32* puiLog2ImportAlignment, IMG_UINT32* puiLog2TilingStrideFactor); /**************************************************************************/ /*! @Function PVRSRVMakeLocalImportHandle @Description This is a "special case" function for making a local import handle. The server handle is a handle to a PMR of bridge type PMR_LOCAL_EXPORT_HANDLE. The returned local import handle will be of the bridge type DEVMEM_MEM_IMPORT that can be used with PVRSRVDevmemLocalImport(). @Input psConnection Services connection @Input hServerHandle Server export handle @Output hLocalImportHandle Returned client import handle @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVMakeLocalImportHandle(const PVRSRV_DEV_CONNECTION *psConnection, IMG_HANDLE hServerHandle, IMG_HANDLE *hLocalImportHandle); /**************************************************************************/ /*! @Function PVRSRVUnmakeLocalImportHandle @Description Destroy the hLocalImportHandle created with PVRSRVMakeLocalImportHandle(). @Input psConnection Services connection @Output hLocalImportHandle Local import handle @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVUnmakeLocalImportHandle(const PVRSRV_DEV_CONNECTION *psConnection, IMG_HANDLE hLocalImportHandle); #if defined(SUPPORT_INSECURE_EXPORT) /**************************************************************************/ /*! @Function PVRSRVExport @Description Given a memory allocation allocated with Devmem_Allocate(), create a "cookie" that can be passed intact by the caller's own choice of secure IPC to another process and used as the argument to "map" to map this memory into a heap in the target processes. N.B. This can also be used to map into multiple heaps in one process, though that's not the intention. Note, the caller must later call Unexport before freeing the memory. @Input hMemDesc handle to the descriptor of the memory to be exported @Output phExportCookie On success, a handle to the exported cookie @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVExportDevMem(PVRSRV_MEMDESC hMemDesc, PVRSRV_DEVMEM_EXPORTCOOKIE *phExportCookie); /**************************************************************************/ /*! @Function PVRSRVUnexport @Description Undo the export caused by "PVRSRVExport" - note - it doesn't actually tear down any mapping made by processes that received the export cookie. It will simply make the cookie null and void and prevent further mappings. @Input hMemDesc handle to the descriptor of the memory which will no longer be exported @Output phExportCookie On success, the export cookie provided will be set to null @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVUnexportDevMem(PVRSRV_MEMDESC hMemDesc, PVRSRV_DEVMEM_EXPORTCOOKIE *phExportCookie); /**************************************************************************/ /*! @Function PVRSRVImportDevMem @Description Import memory that was previously exported with PVRSRVExport() into the current process. Note: This call only makes the memory accessible to this process, it doesn't map it into the device or CPU. @Input psConnection Connection to services @Input phExportCookie Ptr to the handle of the export-cookie identifying @Output phMemDescOut On Success, a handle to a new memory descriptor representing the memory as mapped into the local process address space. @Input uiFlags Device memory mapping flags @Input pszText Text to describe the import @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ PVRSRV_ERROR PVRSRVImportDevMem(const PVRSRV_DEV_CONNECTION *psConnection, PVRSRV_DEVMEM_EXPORTCOOKIE *phExportCookie, PVRSRV_MEMMAP_FLAGS_T uiFlags, PVRSRV_MEMDESC *phMemDescOut); #endif /* SUPPORT_INSECURE_EXPORT */ /**************************************************************************/ /*! @Function PVRSRVIsDeviceMemAddrValid @Description Checks if given device virtual memory address is valid from the GPU's point of view. This method is intended to be called by a process that imported another process' memory context, hence the expected PVRSRV_REMOTE_DEVMEMCTX parameter. See PVRSRVAcquireRemoteDevMemContext for details about importing memory contexts. @Input hContext handle to memory context @Input sDevVAddr device 40bit virtual memory address @Return PVRSRV_OK if address is valid or PVRSRV_ERROR_INVALID_GPU_ADDR when address is invalid */ /***************************************************************************/ PVRSRV_ERROR PVRSRVIsDeviceMemAddrValid(PVRSRV_REMOTE_DEVMEMCTX hContext, IMG_DEV_VIRTADDR sDevVAddr); /**************************************************************************/ /*! @Function PVRSRVDevmemPin @Description This is the counterpart to PVRSRVDevmemUnpin. It is meant to be called after unpinning an allocation. It will make an unpinned allocation available again and unregister it from the OS shrinker. In the case the shrinker was invoked by the OS while the allocation was unpinned it will allocate new physical pages. If any GPU mapping existed before, the same virtual address range will be valid again. @Input hMemDesc The MemDesc that is going to be pinned. @Return PVRSRV_ERROR: PVRSRV_OK on success and the pre-unpin content is still present and can be reused. PVRSRV_ERROR_PMR_NEW_MEMORY if the memory has been pinned successfully but the pre-unpin content was lost. PVRSRV_ERROR_INVALID_PARAMS if the MemDesc is invalid e.g. NULL. PVRSRV_ERROR_PMR_FAILED_TO_ALLOC_PAGES if the memory of the allocation is lost and we failed to allocate new one. */ /***************************************************************************/ extern PVRSRV_ERROR PVRSRVDevmemPin(PVRSRV_MEMDESC hMemDesc); /**************************************************************************/ /*! @Function PVRSRVDevmemUnpin @Description Unpins an allocation. Unpinning means that the memory must not be accessed anymore by neither CPU nor GPU. The physical memory pages will be registered with a shrinker and the OS is able to reclaim them in OOM situations when the shrinker is invoked. The counterpart to this is PVRSRVDevmemPin() which checks if the physical pages were reclaimed by the OS and then either allocates new physical pages or just unregisters the allocation from the shrinker. The device virtual address range (if any existed) will be kept. The GPU mapping will be kept but is going be invalidated. It is allowed to free an unpinned allocation or remove the GPU mapping. RESTRICTIONS: - Unpinning should only be done if the caller is sure that the GPU finished all pending/running operations on the allocation. - The caller must ensure that no other process than the calling one itself has imported or mapped the allocation, otherwise the unpinning will fail. - All CPU mappings have to be removed beforehand by the caller. - Any attempts to map the allocation while it is unpinned are forbidden. - When using PVRSRVAllocDeviceMem() the caller must allocate whole pages from the chosen heap to avoid suballocations. @Input hMemDesc The MemDesc that is going to be unpinned. @Return PVRSRV_ERROR: PVRSRV_OK on success. PVRSRV_ERROR_INVALID_PARAMS if the passed allocation is not a multiple of the heap page size but was allocated with PVRSRVAllocDeviceMem(), or if its NULL. PVRSRV_ERROR_PMR_STILL_REFERENCED if the passed allocation is still referenced i.e. is still exported or mapped somewhere else. PVRSRV_ERROR_STILL_MAPPED will be thrown if the calling process still has CPU mappings set up or the GPU mapping was acquired more than once. */ /***************************************************************************/ extern PVRSRV_ERROR PVRSRVDevmemUnpin(PVRSRV_MEMDESC hMemDesc); /**************************************************************************/ /*! @Function PVRSRVDevmemGetSize @Description Returns the allocated size for this device-memory. @Input hMemDesc handle to memory allocation @Output puiSize return value for size @Return PVRSRV_OK on success or PVRSRV_ERROR_INVALID_PARAMS */ /***************************************************************************/ extern PVRSRV_ERROR PVRSRVDevmemGetSize(PVRSRV_MEMDESC hMemDesc, IMG_DEVMEM_SIZE_T* puiSize); /**************************************************************************/ /*! @Function PVRSRVExportDevMemContext @Description Makes the given memory context available to other processes that can get a handle to it via PVRSRVAcquireRemoteDevmemContext. This handle can be used for e.g. the breakpoint functions. The context will be only available to other processes that are able to pass in a memory descriptor that is shared between this and the importing process. We use the memory descriptor to identify the correct context and verify that the caller is allowed to request the context. The whole mechanism is intended to be used with the debugger that for example can load USC breakpoint handlers into the shared allocation and then use the acquired remote context (that is exported here) to set/clear breakpoints in USC code. @Input hLocalDevmemCtx Context to export @Input hSharedAllocation A memory descriptor that points to a shared allocation between the two processes. Must be in the given context. @Output phExportCtx A handle to the exported context that is needed for the destruction with PVRSRVUnexportDevMemContext(). @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ extern PVRSRV_ERROR PVRSRVExportDevMemContext(PVRSRV_DEVMEMCTX hLocalDevmemCtx, PVRSRV_MEMDESC hSharedAllocation, PVRSRV_EXPORT_DEVMEMCTX *phExportCtx); /**************************************************************************/ /*! @Function PVRSRVUnexportDevMemContext @Description Removes the context from the list of sharable contexts that that can be imported via PVRSRVReleaseRemoteDevmemContext. @Input psExportCtx An export context retrieved from PVRSRVExportDevmemContext. */ /***************************************************************************/ extern void PVRSRVUnexportDevMemContext(PVRSRV_EXPORT_DEVMEMCTX hExportCtx); /**************************************************************************/ /*! @Function PVRSRVAcquireRemoteDevMemContext @Description Retrieves an exported context that has been made available with PVRSRVExportDevmemContext in the remote process. hSharedMemDesc must be a memory descriptor pointing to the same physical resource as the one passed to PVRSRVExportDevmemContext in the remote process. The memory descriptor has to be retrieved from the remote process via a secure buffer export/import mechanism like DMABuf. @Input hDevmemCtx Memory context of the calling process. @Input hSharedAllocation The memory descriptor used to export the context @Output phRemoteCtx Handle to the remote context. @Return PVRSRV_ERROR: PVRSRV_OK on success. Otherwise, a PVRSRV_ error code */ /***************************************************************************/ extern PVRSRV_ERROR PVRSRVAcquireRemoteDevMemContext(PVRSRV_DEVMEMCTX hDevmemCtx, PVRSRV_MEMDESC hSharedAllocation, PVRSRV_REMOTE_DEVMEMCTX *phRemoteCtx); /**************************************************************************/ /*! @Function PVRSRVReleaseRemoteDevMemContext @Description Releases the remote context and destroys it if this is the last reference. @Input hRemoteCtx Handle to the remote context that will be removed. */ /***************************************************************************/ extern void PVRSRVReleaseRemoteDevMemContext(PVRSRV_REMOTE_DEVMEMCTX hRemoteCtx); /*************************************************************************/ /*! @Function PVRSRVRegisterDevmemPageFaultNotify @Description Registers to be notified when a page fault occurs on a specific device memory context. @Input psDevmemCtx The context to be notified about. @Return PVRSRV_ERROR. */ /**************************************************************************/ extern PVRSRV_ERROR PVRSRVRegisterDevmemPageFaultNotify(PVRSRV_DEVMEMCTX psDevmemCtx); /*************************************************************************/ /*! @Function PVRSRVUnregisterDevmemPageFaultNotify @Description Unegisters to be notified when a page fault occurs on a specific device memory context. @Input psDevmemCtx The context to be unregistered from. @Return PVRSRV_ERROR. */ /**************************************************************************/ extern PVRSRV_ERROR PVRSRVUnregisterDevmemPageFaultNotify(PVRSRV_DEVMEMCTX psDevmemCtx); #if defined __cplusplus }; #endif #endif /* PVRSRV_DEVMEM_H */