ra.h

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

/**
 * 
 * @File          ra.h
 * 
 * @Title         Resource Allocator API
 * 
 * @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
 *
 * Implements generic resource allocation.
 * 
 * Platform       ALL
 * $Date: 2004/07/20 10:51:51 $ $Revision: 1.6 $
 * $Log: ra.h $

 */

#ifndef _RA_H_
#define _RA_H_

#include "img_types.h"
#include "hash.h"
#include "hostfunc.h"

/** Enable support for arena statistics. */
#define RA_STATS 

/** Resource allocation state.
 *  struct _RA_STATE_ deliberately opaque
 */
typedef struct _RA_STATE_ RA_STATE;

/** Resource arena.
 *  struct _RA_ARENA_ deliberately opaque
 */
typedef struct _RA_ARENA_ RA_ARENA;

/** Resource arena statistics. */
struct _RA_STATISTICS_
{
    /** total number of segments add to the arena */
    IMG_UINT32 uSpanCount;

    /** number of current live segments within the arena */
    IMG_UINT32 uLiveSegmentCount;

    /** number of current free segments within the arena */
    IMG_UINT32 uFreeSegmentCount;

    /** total number of resource within the arena */
    IMG_UINT32 uTotalResourceCount;
    
    /** number of free resource within the arena */
    IMG_UINT32 uFreeResourceCount;

    /** total number of resources allocated from the arena */
    IMG_UINT32 uCumulativeAllocs;

    /** total number of resources returned to the arena */
    IMG_UINT32 uCumulativeFrees;

    /** total number of spans allocated by the callback mechanism */
    IMG_UINT32 uImportCount;

    /** total number of spans deallocated by the callback mechanism */
    IMG_UINT32 uExportCount;
};
typedef struct _RA_STATISTICS_ RA_STATISTICS;

/**
 *  @Function   RA_Initialise
 *
 *  @Description
 *
 *  To initialise the ra module. Must be called before any other ra
 *  API function.
 *
 *  @Input pHashState -
 *  @Output ppState - receives pointer to RA state.
 *
 *  @Return IMG_FALSE failure or IMG_TRUE success
 */
IMG_BOOL
RA_Initialise (HASH_STATE *pHashState, RA_STATE **ppState);

/**
 *
 *  @Function   RA_Finalise
 *
 *  @Description
 *
 *  To finalise the ra module.
 *
 *  @Input pState - RA state pointer (from RA_Initialise)
 *
 *  @Return None
 */
void
RA_Finalise (RA_STATE *pState);

/**
 *  @Function   RA_Create
 *
 *  @Description
 *
 *  To create a resource arena.
 *
 *  @Input pState - pointer to ra state created by RA_Initialise
 *  @Input name - the name of the arena for diagnostic purposes.
 *  @Input base - the base of an initial resource span or 0.
 *  @Input uSize - the size of an initial resource span or 0.
 *  @Input uQuantum - the arena allocation quantum.
 *  @Input alloc - a resource allocation callback or 0.
 *  @Input free - a resource de-allocation callback or 0.
 *  @Input import_handle - handle passed to alloc and free or 0.
 *  @Return arena handle, or IMG_NULL.
 */
RA_ARENA *
RA_Create (RA_STATE *pState,
           IMG_CHAR *name,
           IMG_UINTPTR_T base,
           IMG_SIZE_T uSize,        
           IMG_SIZE_T uQuantum, 
           IMG_BOOL (*alloc)(IMG_VOID *_h,
                             IMG_SIZE_T uSize,
                             IMG_SIZE_T *pActualSize,
                             IMG_VOID **ppRef,
                             IMG_UINT32 uFlags,
                        IMG_UINTPTR_T *pBase),
           IMG_VOID (*free) (IMG_VOID *,
							IMG_UINTPTR_T,
							IMG_VOID *pRef),
           IMG_VOID *import_handle);

/**
 *  @Function   RA_Delete
 *
 *  @Description
 *
 *  To delete a resource arena. All resources allocated from the arena
 *  must be freed before deleting the arena.
 *                  
 *  @Input  pArena - the arena to delete.
 *  @Return None
 */
void
RA_Delete (RA_ARENA *pArena);

/**
 *  @Function   RA_Add
 *
 *  @Description
 *
 *  To add a resource span to an arena. The span must not overlapp with
 *  any span previously added to the arena.
 *
 *  @Input pArena - the arena to add a span into.
 *  @Input base - the base of the span.
 *  @Input uSize - the extent of the span.
 *  @Return IMG_TRUE - success, IMG_FALSE - failure
 */
IMG_BOOL
RA_Add (RA_ARENA *pArena, IMG_UINTPTR_T base, IMG_SIZE_T uSize);

/**
 *  @Function   RA_Alloc
 *
 *  @Description
 *
 *  To allocate resource from an arena.
 *
 *  @Input  pArena - the arena
 *  @Input  uRequestSize - the size of resource segment requested.
 *  @Output pActualSize - the actual_size of resource segment allocated,
 *          typcially rounded up by quantum.
 *  @Output ppRef - the user reference associated with allocated
 *          resource span.
 *  @Input  uFlags - flags influencing allocation policy.
 *  @Input  uAlignment - the alignment constraint required for the
 *          allocated segment, use 0 if alignment not required.
	    uAlignmentOffset - the required alignment offset
 *  @Output pBase - allocated base resource
 *  @Return IMG_TRUE - success, IMG_FALSE - failure
 */
IMG_BOOL
RA_Alloc (RA_ARENA *pArena, 
          IMG_SIZE_T uSize,
          IMG_SIZE_T *pActualSize,
          void **ppRef, 
          IMG_UINT32 uFlags,
          IMG_UINT32 uAlignment,
	  IMG_UINT32 uAlignmentOffset,
          IMG_UINTPTR_T *pBase);

/**
 *  @Function   RA_Free
 *
 *  @Description    To free a resource segment.
 *  
 *  @Input  pArena - the arena the segment was originally allocated from.
 *  @Input  base - the base of the resource span to free.
 *  @Input  pRef - TODO check why we still need this.
 *
 *  @Return None
 */
void 
RA_Free (RA_ARENA *pArena, IMG_UINTPTR_T base, void *pRef);

#ifdef RA_STATS
/**
 *  @Function   RA_Statistics
 *
 *  @Description    To query an arena's statistics.
 *
 *  @Input pArena - the arena.
 *  @Output ppStats - receives a pointer to the arena statistics.
 *  @Return None
 */
void 
RA_Statistics (RA_ARENA *pArena,
               RA_STATISTICS **ppStats);

#endif
#endif