dual_page.h

Lido PXA270平台开发板的最新BSP,包括源代码

/**
 * @File          dual_page.h
 *
 * @Title         Dual Space Page Management.
 *
 * @Author        Marcus Shawcroft
 *
 * @Date          14 May 2003
 *
 * @Copyright     2003-2004 by Imagination Technologies Limited.
 *                All rights reserved.  No part of this software, either
 *                material or conceptual may be copied or distributed,
 *                transmitted, transcribed, stored in a retrieval system
 *                or translated into any human or computer language in any
 *                form by any means, electronic, mechanical, manual or
 *                other-wise, or disclosed to third parties without the
 *                express written permission of Imagination Technologies
 *                Limited, Unit 8, HomePark Industrial Estate,
 *                King's Langley, Hertfordshire, WD4 8LZ, U.K.
 *
 * @Description
 *
 * Manages pages mapped into two virtual memory spaces, cpu and
 * device.
 * 
 * @Platform      ALL
 *
 */

#ifndef _DUAL_PAGE_H_
#define _DUAL_PAGE_H_

#include "ra.h"
#include "hostfunc.h"

/** Dual page pager.
 *  struct _DP_PAGER_ deliberately opaque
 */
typedef struct _DP_PAGER_ DP_PAGER;

struct _DP_MAPPING_
{
	enum
	{
		hm_none,				/*!< no origin */
		hm_wrapped,				/*!< wrapped user supplied */
		hm_env,					/*!< obtained from environment */
		hm_contiguous			/*!< contigous arena */
	} eCpuMemoryOrigin;
	IMG_CPU_VIRTADDR CpuVAddr;
	IMG_CPU_PHYADDR CpuPAddr;
	IMG_DEV_VIRTADDR DevVAddr;
	DP_PAGER *pPager;
	IMG_SIZE_T uSize;
    IMG_UINT32 uPoolNr;
};
typedef struct _DP_MAPPING_ DP_MAPPING;

struct device_tag;
typedef struct _DP_STATE_ DP_STATE;

/**
 *	@Function   DP_Initialise
 *
 *  @Description
 *
 *  Initialise the dual page module, must be called before any
 *  other dual_page module function.
 *
 *  @Input pRAState (from RA_Initialise)
 *  @Output ppState - receives DP_STATE
 *  @Return	IMG_TRUE - Success, IMG_FALSE - Failed.
 */
IMG_BOOL
DP_Initialise (RA_STATE *pRAState, DP_STATE **ppState);

/**
 *	@Function   DP_Finalise
 *
 *  @Description
 *
 *  Finalise the dual page module. All page allocations must be
 *  free'd before calling this function.
 *	            
 *  @Input pDPState - dual page state (from DP_Initialise)
 *  @Return	None.
 */

void
DP_Finalise (DP_STATE *pDPState);

/**
 *	@Function   DP_Create
 *
 *  @Description
 *
 *  Create a source of pages mapped into both cpu and device virtual
 *  address spaces for a specific device.
 *            
 *  @Input  pDPState - dual page state (from DP_Initialise)
 *  @Input  pDev - device handle
 *  @Return	dual page handle
 */
DP_PAGER *
DP_Create (DP_STATE *pDPState, struct device_tag *pDev);

/**
 *	@Function   DP_Delete
 *
 *  @Description
 *
 *  Delete a source of pages created with DP_create ().
 *            
 *  @Input  pPager - dual page handle
 *  @Return	None
 */
void
DP_Delete (DP_PAGER *pPager);

/**
 * 	@Function   DP_AllocMany
 *
 *  @Description
 *
 *  Wrapper around DP_alloc conforming to the resource allocator's
 *  callback resource requestor interface. Allocates a block of pages
 *  larger than requested, allowing the resource allocator to
 *  operate a * small cache of pre allocated pages.
 *            
 *  @Input  pH - dual page handle, not the void type is dictated by
 *          the generic nature of the resource allocator interface.
 *  @Input  uSize - requested size in bytes
 *  @Output pActualSize - received the actual size allocated in bytes
 *          which may be >= requested size
 *  @Output ppRef - receives the arbitrary user reference associated
 *          with the underlying storage.
 *  @Input  uFlags - bit mask of allocation flags
 *  @Output pBase - receives a pointer to the allocated storage.
 *  @Return	IMG_TRUE - success, IMG_FALSE - failed
 */
IMG_BOOL
DP_AllocMany (void *pH,
			  IMG_SIZE_T uSize,
			  IMG_SIZE_T *pActualSize,
			  void **ppRef,
			  IMG_UINT32 uFlags,
			  IMG_UINTPTR_T *pBase);

/**
 * 	@Function   DP_Alloc
 *
 *  @Description
 *
 *  Allocate a block of pages mapped in both cpu and device virtual
 *  address spaces.
 *
 *  @Input  pH - dual page handle, not the void type is dictated by
 *          the generic nature of the resource allocator interface.
 *  @Input  uSize - requested size in bytes
 *  @Output pActualSize - received the actual size allocated in bytes
 *          which may be >= requested size
 *  @Output ppRef - receives the arbitrary user reference associated
 *          with the underlying storage.
 *  @Input  uFlags - bit mask of allocation flags.
 *  @Input  uDevVAddrAlignment - required alignment of device virtual
 *          address, or 0.
 *  @Output pBase - receives a pointer to the allocated storage.
 *  @Return	IMG_TRUE - success, IMG_FALSE - failed
 */
IMG_BOOL
DP_Alloc (void *pH,
		  IMG_SIZE_T uSize,
		  IMG_SIZE_T *pActualSize,
		  void **ppRef,
		  IMG_UINT32 uFlags,
		  IMG_UINT32 uDevVAddrAlignment,
		  IMG_UINTPTR_T *pBase);

/**
 *	@Function   DP_Free
 *
 *	@Description
 *
 *  Free a block of pages previously allocated via DP_Alloc or
 *  DP_AllocMany.
 *
 *  @Input  pH - dual page handle, not the void type is dictated by
 *          the generic nature of the resource allocator interface.
 *  @Input  base - base address of blocks to free.
 *  @Input  pRef - arbitrary user reference associated with the
 *          underlying storage provided by DP_alloc or DP_AllocMany.
 *  @Return	None
 */
void
DP_Free (void *pH, IMG_UINTPTR_T base, void *pRef);

/**
 * @Function   DP_Wrap
 *
 * @Description
 *
 * Allocate a block of pages mapped in both cpu and device virtual
 * address spaces.
 *
 *  @Input  pH - dual page handle, not the void type is dictated by
 *          the generic nature of the resource allocator interface.
 *  @Input  base - system physical address base
 *  @Input  uSize - requested size in bytes
 *  @Output pActualSize - received the actual size allocated in bytes
 *          which may be >= requested size
 *  @Output ppRef - receives the arbitrary user reference associated
 *          with the underlying storage.
 *  @Input  uFlags - bit mask of allocation flags.
 *  @Input  uDevVAddrAlignment - required alignment of device virtual
 *          address, or 0.
 *  @Output pBase - receives a pointer to the allocated storage.
 *  @Return	IMG_TRUE - success, IMG_FALSE - failed
 */
IMG_BOOL
DP_Wrap (void *pH,
		 IMG_SYS_PHYADDR base,
		 IMG_SIZE_T uSize,
		 IMG_SIZE_T *pActualSize,
		 void **ppRef,
		 IMG_UINT32 uFlags,
		 IMG_UINT32 uDevVAddrAlignment,
		 IMG_UINTPTR_T *pDevVAddr);

/**
 *	@Function   DP_HaveHiArena
 *
 *  @Description
 *
 *  Test if we have a high arena.
 *            
 *  @Input  pPager - dual page pager to test.
 *  @Return	IMG_TRUE - high arena present, IMG_FALSE - no high arena.
 */
IMG_BOOL
DP_HaveHiArena (DP_PAGER *pPager);

/**
 *	@Function   DP_ContiguousStatistics
 *
 *  @Description
 *
 *  Retrieve the contiguous buffer arena statistics.
 *            
 *  @Input  pDPState - dual page state (from DP_Initialise)
 *  @Input  uFlags - Allocation flags to report stats from.
 *  @Output ppStats - Receives reference to requested statistics.
 *  @Return	IMG_TRUE - Success, IMG_FALSE - Failed
 */
IMG_BOOL
DP_ContiguousStatistics (DP_STATE *pDPState,
                         IMG_UINT32 uFlags,
						 RA_STATISTICS **ppStats);

/**
 *	@Function   DP_AllocContiguous
 *
 *  @Description
 *
 *  Allocate from the contiguous arena.
 *            
 *  @Input  pPager - dual page pager to allocate from.
 *  @Input  uPoolNr - pool to allocate from.
 *  @Input  uSize - Size in bytes of required region.
 *  @Output pActualSize - Receives actual size in bytes if non null.
 *  @Input  uDevVAddrAlignment - Device v address alignment required.
 *  @Output pCPUVAddr - Receives cpu virtual address.
 *  @Output pCPUPAddr - Receives cpu physical address.
 *
 *  @Return	IMG_TRUE - Success, IMG_FALSE - Failure.
 */
IMG_BOOL
DP_AllocContiguous (DP_PAGER *pPager,
                    IMG_UINT32 uPoolNr,
                    IMG_SIZE_T uSize,
                    IMG_SIZE_T *pActualSize,
                    IMG_UINT32 uDevVAddrAlignment,
                    IMG_CPU_VIRTADDR *pCPUVAddr,
                    IMG_CPU_PHYADDR *pCPUPAddr);

/**
 *
 *  @Function   DP_FreeContiguous
 *
 *  @Description    Free allocation from the contiguous arena.
 *            
 *  @Input  pPager - dual page pager to allocate from.
 *  @Input  uPoolNr - pool to deallocate to.
 *  @Input  CpuPAddr - CPU physical address of allocated region.
 *
 *  @Return	None
 */
void
DP_FreeContiguous (DP_PAGER *pPager,
                   IMG_UINT32 uPoolNr,
                   IMG_CPU_PHYADDR cpuPAddr);

#endif

/*
 * arch-tag: cd602d65-c755-4546-9c4d-76a332c55050
 *
 * Local Variables: *
 * c-file-style: "img" *
 * End: *
 */