/**************************************************************************/ /*!
@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_TDFWCODE,
	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);

#if defined(USING_HYPERVISOR)
    IMG_HANDLE (*pfnGetPmr)(PMR_IMPL_PRIVDATA pvPriv, size_t ulOffset);
#endif
#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 */