/*************************************************************************/ /*!
|
@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 <powervr/sync_external.h>
|
#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 */
|
