blob: 44c0bce288415e97f34ac9fb4b643cec08f4784a [file] [log] [blame]
/**************************************************************************/ /*!
@File
@Title Implementation Callbacks for Physmem (PMR) abstraction
@Copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved
@Description Part of the memory management. This file is for definitions
that are private to the world of PMRs, but that need to be
shared between pmr.c itself and the modules that implement the
callbacks for the PMR.
@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 SRVSRV_PMR_IMPL_H
#define SRVSRV_PMR_IMPL_H
#include "img_types.h"
#include "img_defs.h"
#include "pvrsrv_error.h"
/*! Physical Memory Resource type.
*/
typedef struct _PMR_ PMR;
/*! Per-flavour callbacks need to be shared with generic implementation
* (pmr.c).
*/
typedef void *PMR_IMPL_PRIVDATA;
/*! Type for holding flags passed to the PMR factory.
*/
typedef PVRSRV_MEMALLOCFLAGS_T PMR_FLAGS_T;
/*! Mapping table for the allocation.
*
* PMR's can be sparse in which case not all the logical addresses in it are
* valid. The mapping table translates logical offsets into physical offsets.
*
* This table is always passed to the PMR factory regardless if the memory is
* sparse or not. In case of non-sparse memory all virtual offsets are mapped
* to physical offsets.
*/
typedef struct _PMR_MAPPING_TABLE_ PMR_MAPPING_TABLE;
/*! Private data passed to the ::PFN_MMAP_FN function.
*/
typedef void *PMR_MMAP_DATA;
/*! PMR factory type.
*/
typedef enum _PMR_IMPL_TYPE_
{
PMR_TYPE_NONE = 0,
PMR_TYPE_OSMEM,
PMR_TYPE_LMA,
PMR_TYPE_DMABUF,
PMR_TYPE_EXTMEM,
PMR_TYPE_DC,
PMR_TYPE_TDFWMEM,
PMR_TYPE_TDSECBUF
} PMR_IMPL_TYPE;
/*************************************************************************/ /*!
@Brief Callback function type PFN_LOCK_PHYS_ADDRESSES_FN
@Description Called to lock down the physical addresses for all pages
allocated for a PMR.
The default implementation is to simply increment a
lock-count for debugging purposes.
If overridden, the PFN_LOCK_PHYS_ADDRESSES_FN function will
be called when someone first requires a physical address,
and the PFN_UNLOCK_PHYS_ADDRESSES_FN counterpart will be
called when the last such reference is released.
The PMR implementation may assume that physical addresses
will have been "locked" in this manner before any call is
made to the pfnDevPhysAddr() callback
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Return PVRSRV_OK if the operation was successful, an error code
otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_LOCK_PHYS_ADDRESSES_FN)(PMR_IMPL_PRIVDATA pvPriv);
/*************************************************************************/ /*!
@Brief Callback function type PFN_UNLOCK_PHYS_ADDRESSES_FN
@Description Called to release the lock taken on the physical addresses
for all pages allocated for a PMR.
The default implementation is to simply decrement a
lock-count for debugging purposes.
If overridden, the PFN_UNLOCK_PHYS_ADDRESSES_FN will be
called when the last reference taken on the PMR is
released.
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Return PVRSRV_OK if the operation was successful, an error code
otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_UNLOCK_PHYS_ADDRESSES_FN)(PMR_IMPL_PRIVDATA pvPriv);
/*************************************************************************/ /*!
@Brief Callback function type PFN_DEV_PHYS_ADDR_FN
@Description Called to obtain one or more physical addresses for given
offsets within a PMR.
The PFN_LOCK_PHYS_ADDRESSES_FN callback (if overridden) is
guaranteed to have been called prior to calling the
PFN_DEV_PHYS_ADDR_FN callback and the caller promises not to
rely on the physical address thus obtained after the
PFN_UNLOCK_PHYS_ADDRESSES_FN callback is called.
Implementation of this callback is mandatory.
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Input ui32Log2PageSize The log2 page size.
@Input ui32NumOfAddr The number of addresses to be returned
@Input puiOffset The offset from the start of the PMR
(in bytes) for which the physical
address is required. Where multiple
addresses are requested, this will
contain a list of offsets.
@Output pbValid List of boolean flags indicating which
addresses in the returned list
(psDevAddrPtr) are valid (for sparse
allocations, not all pages may have a
physical backing)
@Output psDevAddrPtr Returned list of physical addresses
@Return PVRSRV_OK if the operation was successful, an error code
otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_DEV_PHYS_ADDR_FN)(PMR_IMPL_PRIVDATA pvPriv,
IMG_UINT32 ui32Log2PageSize,
IMG_UINT32 ui32NumOfAddr,
IMG_DEVMEM_OFFSET_T *puiOffset,
IMG_BOOL *pbValid,
IMG_DEV_PHYADDR *psDevAddrPtr);
/*************************************************************************/ /*!
@Brief Callback function type PFN_ACQUIRE_KERNEL_MAPPING_DATA_FN
@Description Called to obtain a kernel-accessible address (mapped to a
virtual address if required) for the PMR for use internally
in Services.
Implementation of this function for the (default) PMR factory providing
OS-allocations is mandatory (the driver will expect to be able to call
this function for OS-provided allocations).
For other PMR factories, implementation of this function is only necessary
where an MMU mapping is required for the Kernel to be able to access the
allocated memory.
If no mapping is needed, this function can remain unimplemented and the
pfn may be set to NULL.
@Input pvPriv Private data (which was generated by
the PMR factory when PMR was created)
@Input uiOffset Offset from the beginning of the PMR
at which mapping is to start
@Input uiSize Size of mapping (in bytes)
@Output ppvKernelAddressOut Mapped kernel address
@Output phHandleOut Returned handle of the new mapping
@Input ulFlags Mapping flags
@Return PVRSRV_OK if the mapping was successful, an error code
otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_ACQUIRE_KERNEL_MAPPING_DATA_FN)(PMR_IMPL_PRIVDATA pvPriv,
size_t uiOffset,
size_t uiSize,
void **ppvKernelAddressOut,
IMG_HANDLE *phHandleOut,
PMR_FLAGS_T ulFlags);
/*************************************************************************/ /*!
@Brief Callback function type PFN_RELEASE_KERNEL_MAPPING_DATA_FN
@Description Called to release a mapped kernel virtual address
Implementation of this callback is mandatory if
PFN_ACQUIRE_KERNEL_MAPPING_DATA_FN is provided for the PMR factory,
otherwise this function can remain unimplemented and the pfn may be set
to NULL.
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Input hHandle Handle of the mapping to be released
@Return None
*/ /**************************************************************************/
typedef void (*PFN_RELEASE_KERNEL_MAPPING_DATA_FN)(PMR_IMPL_PRIVDATA pvPriv,
IMG_HANDLE hHandle);
/*************************************************************************/ /*!
@Brief Callback function type PFN_READ_BYTES_FN
@Description Called to read bytes from an unmapped allocation
Implementation of this callback is optional - where it is not provided,
the driver will use PFN_ACQUIRE_KERNEL_MAPPING_DATA_FN to map the entire
PMR (if an MMU mapping is required for the Kernel to be able to access the
allocated memory).
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Input uiOffset Offset from the beginning of the PMR at
which to begin reading
@Output pcBuffer Buffer in which to return the read data
@Input uiBufSz Number of bytes to be read
@Output puiNumBytes Number of bytes actually read (may be
less than uiBufSz)
@Return PVRSRV_OK if the read was successful, an error code
otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_READ_BYTES_FN)(PMR_IMPL_PRIVDATA pvPriv,
IMG_DEVMEM_OFFSET_T uiOffset,
IMG_UINT8 *pcBuffer,
size_t uiBufSz,
size_t *puiNumBytes);
/*************************************************************************/ /*!
@Brief Callback function type PFN_WRITE_BYTES_FN
@Description Called to write bytes into an unmapped allocation
Implementation of this callback is optional - where it is not provided,
the driver will use PFN_ACQUIRE_KERNEL_MAPPING_DATA_FN to map the entire
PMR (if an MMU mapping is required for the Kernel to be able to access the
allocated memory).
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Input uiOffset Offset from the beginning of the PMR at
which to begin writing
@Input pcBuffer Buffer containing the data to be written
@Input uiBufSz Number of bytes to be written
@Output puiNumBytes Number of bytes actually written (may be
less than uiBufSz)
@Return PVRSRV_OK if the write was successful, an error code
otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_WRITE_BYTES_FN)(PMR_IMPL_PRIVDATA pvPriv,
IMG_DEVMEM_OFFSET_T uiOffset,
IMG_UINT8 *pcBuffer,
size_t uiBufSz,
size_t *puiNumBytes);
/*************************************************************************/ /*!
@Brief Callback function type PFN_UNPIN_MEM_FN
@Description Called to unpin an allocation.
Once unpinned, the pages backing the allocation may be
re-used by the Operating System for another purpose.
When the pages are required again, they may be re-pinned
(by calling PFN_PIN_MEM_FN). The driver will try to return
same pages as before. The caller will be told if the
content of these returned pages has been modified or if
the pages returned are not the original pages.
Implementation of this callback is optional.
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Return PVRSRV_OK if the unpin was successful, an error code
otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_UNPIN_MEM_FN)(PMR_IMPL_PRIVDATA pPriv);
/*************************************************************************/ /*!
@Brief Callback function type PFN_PIN_MEM_FN
@Description Called to pin a previously unpinned allocation.
The driver will try to return same pages as were previously
assigned to the allocation. The caller will be told if the
content of these returned pages has been modified or if
the pages returned are not the original pages.
Implementation of this callback is optional.
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Input psMappingTable Mapping table, which describes how
virtual 'chunks' are to be mapped to
physical 'chunks' for the allocation.
@Return PVRSRV_OK if the original pages were returned unmodified.
PVRSRV_ERROR_PMR_NEW_MEMORY if the memory returned was modified
or different pages were returned.
Another PVRSRV_ERROR code on failure.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_PIN_MEM_FN)(PMR_IMPL_PRIVDATA pPriv,
PMR_MAPPING_TABLE *psMappingTable);
/*************************************************************************/ /*!
@Brief Callback function type PFN_CHANGE_SPARSE_MEM_FN
@Description Called to modify the physical backing for a given sparse
allocation.
The caller provides a list of the pages within the sparse
allocation which should be backed with a physical allocation
and a list of the pages which do not require backing.
Implementation of this callback is mandatory.
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Input psPMR The PMR of the sparse allocation to be
modified
@Input ui32AllocPageCount The number of pages specified in
pai32AllocIndices
@Input pai32AllocIndices The list of pages in the sparse
allocation that should be backed with a
physical allocation. Pages are
referenced by their index within the
sparse allocation (e.g. in a 10 page
allocation, pages are denoted by
indices 0 to 9)
@Input ui32FreePageCount The number of pages specified in
pai32FreeIndices
@Input pai32FreeIndices The list of pages in the sparse
allocation that do not require
a physical allocation.
@Input ui32Flags Allocation flags
@Return PVRSRV_OK if the sparse allocation physical backing was updated
successfully, an error code otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_CHANGE_SPARSE_MEM_FN)(PMR_IMPL_PRIVDATA pPriv,
const PMR *psPMR,
IMG_UINT32 ui32AllocPageCount,
IMG_UINT32 *pai32AllocIndices,
IMG_UINT32 ui32FreePageCount,
IMG_UINT32 *pai32FreeIndices,
IMG_UINT32 uiFlags);
/*************************************************************************/ /*!
@Brief Callback function type PFN_CHANGE_SPARSE_MEM_CPU_MAP_FN
@Description Called to modify which pages are mapped for a given sparse
allocation.
The caller provides a list of the pages within the sparse
allocation which should be given a CPU mapping and a list
of the pages which do not require a CPU mapping.
Implementation of this callback is mandatory.
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Input psPMR The PMR of the sparse allocation to be
modified
@Input sCpuVAddrBase The virtual base address of the sparse
allocation
@Input ui32AllocPageCount The number of pages specified in
pai32AllocIndices
@Input pai32AllocIndices The list of pages in the sparse
allocation that should be given a CPU
mapping. Pages are referenced by their
index within the sparse allocation (e.g.
in a 10 page allocation, pages are
denoted by indices 0 to 9)
@Input ui32FreePageCount The number of pages specified in
pai32FreeIndices
@Input pai32FreeIndices The list of pages in the sparse
allocation that do not require a CPU
mapping.
@Return PVRSRV_OK if the page mappings were updated successfully, an
error code otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_CHANGE_SPARSE_MEM_CPU_MAP_FN)(PMR_IMPL_PRIVDATA pPriv,
const PMR *psPMR,
IMG_UINT64 sCpuVAddrBase,
IMG_UINT32 ui32AllocPageCount,
IMG_UINT32 *pai32AllocIndices,
IMG_UINT32 ui32FreePageCount,
IMG_UINT32 *pai32FreeIndices);
/*************************************************************************/ /*!
@Brief Callback function type PFN_MMAP_FN
@Description Called to map pages in the specified PMR.
Implementation of this callback is optional.
Where it is provided, it will be used in place of OSMMapPMRGeneric().
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Input psPMR The PMR of the allocation to be mapped
@Input pMMapData OS-specific data to describe how mapping
should be performed
@Return PVRSRV_OK if the mapping was successful, an error code
otherwise.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_MMAP_FN)(PMR_IMPL_PRIVDATA pPriv,
PMR *psPMR,
PMR_MMAP_DATA pMMapData);
/*************************************************************************/ /*!
@Brief Callback function type PFN_FINALIZE_FN
@Description Called to destroy the PMR.
This callback will be called only when all references to
the PMR have been dropped.
The PMR was created via a call to PhysmemNewRamBackedPMR()
and is destroyed via this callback.
Implementation of this callback is mandatory.
@Input pvPriv Private data (which was generated by the
PMR factory when PMR was created)
@Return PVRSRV_OK if the PMR destruction was successful, an error
code otherwise.
Currently PVRSRV_ERROR_PMR_STILL_REFERENCED is the only
error returned from physmem_dmabuf.c layer and on this
error, destroying of the PMR is aborted without disturbing
the PMR state.
*/ /**************************************************************************/
typedef PVRSRV_ERROR (*PFN_FINALIZE_FN)(PMR_IMPL_PRIVDATA pvPriv);
/*************************************************************************/ /*!
@Brief Callback function type PFN_ACQUIRE_PMR_FACTORY_LOCK_FN
@Description Called to acquire the PMR factory's global lock, if it has one,
hence callback optional. Factories which support entry points
in addition to the normal bridge calls, for example, from the
native OS that manipulate the PMR reference count should
create a factory lock and implementations for these call backs.
Implementation of this callback is optional.
@Return None
*/
/*****************************************************************************/
typedef void (*PFN_ACQUIRE_PMR_FACTORY_LOCK_FN)(void);
/*************************************************************************/ /*!
@Brief Callback function type PFN_RELEASE_PMR_FACTORY_LOCK_FN
@Description Called to release the PMR factory's global lock acquired by calling
pfn_acquire_pmr_factory_lock callback.
Implementation of this callback is optional.
@Return None
*/ /**************************************************************************/
typedef void (*PFN_RELEASE_PMR_FACTORY_LOCK_FN)(void);
/*! PMR factory callback table.
*/
struct _PMR_IMPL_FUNCTAB_ {
/*! Callback function pointer, see ::PFN_LOCK_PHYS_ADDRESSES_FN */
PFN_LOCK_PHYS_ADDRESSES_FN pfnLockPhysAddresses;
/*! Callback function pointer, see ::PFN_UNLOCK_PHYS_ADDRESSES_FN */
PFN_UNLOCK_PHYS_ADDRESSES_FN pfnUnlockPhysAddresses;
/*! Callback function pointer, see ::PFN_DEV_PHYS_ADDR_FN */
PFN_DEV_PHYS_ADDR_FN pfnDevPhysAddr;
/*! Callback function pointer, see ::PFN_ACQUIRE_KERNEL_MAPPING_DATA_FN */
PFN_ACQUIRE_KERNEL_MAPPING_DATA_FN pfnAcquireKernelMappingData;
/*! Callback function pointer, see ::PFN_RELEASE_KERNEL_MAPPING_DATA_FN */
PFN_RELEASE_KERNEL_MAPPING_DATA_FN pfnReleaseKernelMappingData;
#if defined(INTEGRITY_OS)
/*
* MapMemoryObject()/UnmapMemoryObject()
*
* called to map/unmap memory objects in Integrity OS
*/
PVRSRV_ERROR (*pfnMapMemoryObject)(PMR_IMPL_PRIVDATA pvPriv,
IMG_HANDLE *phMemObj,
void **pvClientAddr,
IMG_HANDLE *phHandleOut);
PVRSRV_ERROR (*pfnUnmapMemoryObject)(PMR_IMPL_PRIVDATA pvPriv);
#endif
/*! Callback function pointer, see ::PFN_READ_BYTES_FN */
PFN_READ_BYTES_FN pfnReadBytes;
/*! Callback function pointer, see ::PFN_WRITE_BYTES_FN */
PFN_WRITE_BYTES_FN pfnWriteBytes;
/*! Callback function pointer, see ::PFN_UNPIN_MEM_FN */
PFN_UNPIN_MEM_FN pfnUnpinMem;
/*! Callback function pointer, see ::PFN_PIN_MEM_FN */
PFN_PIN_MEM_FN pfnPinMem;
/*! Callback function pointer, see ::PFN_CHANGE_SPARSE_MEM_FN */
PFN_CHANGE_SPARSE_MEM_FN pfnChangeSparseMem;
/*! Callback function pointer, see ::PFN_CHANGE_SPARSE_MEM_CPU_MAP_FN */
PFN_CHANGE_SPARSE_MEM_CPU_MAP_FN pfnChangeSparseMemCPUMap;
/*! Callback function pointer, see ::PFN_MMAP_FN */
PFN_MMAP_FN pfnMMap;
/*! Callback function pointer, see ::PFN_FINALIZE_FN */
PFN_FINALIZE_FN pfnFinalize;
/*! Callback function pointer, see ::PFN_ACQUIRE_PMR_FACTORY_LOCK_FN */
PFN_ACQUIRE_PMR_FACTORY_LOCK_FN pfnGetPMRFactoryLock;
/*! Callback function pointer, see ::PFN_RELEASE_PMR_FACTORY_LOCK_FN */
PFN_RELEASE_PMR_FACTORY_LOCK_FN pfnReleasePMRFactoryLock;
};
/*! PMR factory callback table.
*/
typedef struct _PMR_IMPL_FUNCTAB_ PMR_IMPL_FUNCTAB;
#endif /* SRVSRV_PMR_IMPL_H */