handle.h

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

/* -*- c-file-style: "img" -*-
<module>
 * Name         : handle.c
 * Title        : Handle Management.
 * Author       : Marcus Shawcroft
 * Created      : 14 May 2003
 *
 * Copyright    : 2003 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 :  Handle's are unique identifiers within a handle space
 *                associated with a user pointer. Handles can be tested
 *                for validity and mapped back to their associated
 *                user pointer.
 * 
 * Platform     : ALL
 *
</module>
 */

#ifndef _HDL_H_
#define _HDL_H_

typedef IMG_INT32 HDL;

typedef struct _HDL_SPACE_ HDL_SPACE;

#define HDL_INVALID (-1)

/*----------------------------------------------------------------------------
<function>
	FUNCTION:   HDL_SpaceCreate

	PURPOSE:    Create a handle space.
	                	
	PARAMETERS:	In:  uInitialSize - initial number of handles in the handle
	                 space.
	            In:  uGrow - number of handles to uGrow the handle space by
	                 when handle are exhausted.
	RETURNS:	IMG_NULL or HDL_SPACE.
</function>
-----------------------------------------------------------------------------*/
HDL_SPACE *
HDL_SpaceCreate (IMG_UINT32 uInitialSize, IMG_UINT32 uGrow);

/*----------------------------------------------------------------------------
<function>
	FUNCTION:   HDL_SpaceDelete

	PURPOSE:    Delete a handle space.
	                	
	PARAMETERS:	In:  pHandleSpace - handle space.
	RETURNS:	None
</function>
-----------------------------------------------------------------------------*/
void
HDL_SpaceDelete (HDL_SPACE *pHandleSpace);

/*----------------------------------------------------------------------------
<function>
	FUNCTION:   HDL_SpaceAlloc

	PURPOSE:    Allocate a handle within a handle space and associate it with a
	            arbitrary user pointer.
	                	
	PARAMETERS:	In:  pHandleSpace - handle space.
	            In:  pRef - arbitrary user handle
	            Out: pHandle - receives allocated handle
	RETURNS:	IMG_TRUE Success
	            IMG_FALSE Failure
</function>
-----------------------------------------------------------------------------*/
IMG_BOOL
HDL_SpaceAlloc (HDL_SPACE *pHandleSpace,
				void *pRef,
				HDL *pHandle);

/*----------------------------------------------------------------------------
<function>
	FUNCTION:   HDL_SpaceFree

	PURPOSE:    Free a handle within a handle space.
	                	
	PARAMETERS:	In:  pHandleSpace - handle space.
	            In:  handle - handle to free
	            Out: pHandle - received the allocated handle
	RETURNS:	IMG_TRUE Success.
	            IMG_FALSE Failure.
</function>
-----------------------------------------------------------------------------*/
void
HDL_SpaceFree (HDL_SPACE *pHandleSpace, HDL handle);

/*----------------------------------------------------------------------------
<function>
	FUNCTION:   HDL_SpaceLookup

	PURPOSE:    Lookup a handle within a handle space and return the associated
	            arbitrary user pointer.
	                	
	PARAMETERS:	In:  pHandleSpace - handle space.
	            In:  handle - handle to free
	RETURNS:	IMG_NULL if illegal handle, or associted user pointer.
</function>
-----------------------------------------------------------------------------*/
void *
HDL_SpaceLookup (HDL_SPACE *pHandleSpace, HDL handle);

/*----------------------------------------------------------------------------
<function>
	FUNCTION:   HDL_SpaceFirstHandle

	PURPOSE:    Retreive the first allocated handle within a handle space.
	                	
	PARAMETERS:	In:  pHandleSpace - handle space.
	            Out: pHandle - receives the first handle
	RETURNS:	IMG_FALSE - there are no allocated handles in this handle space
	            IMG_TRUE - first allocated handle returned
</function>
-----------------------------------------------------------------------------*/
IMG_BOOL
HDL_SpaceFirstHandle (HDL_SPACE *pHandleSpace, HDL *pHandle);

/*----------------------------------------------------------------------------
<function>
	FUNCTION:   HDL_SpaceNextHandle

	PURPOSE:    Retreive the next allocated handle within a handle space.
	                	
	PARAMETERS:	In:  pHandleSpace - handle space.
	            Out: pHandle - current handle, modified to be the next
	                 allocated handle in the handle space.
	RETURNS:	IMG_FALSE - there are no further allocated handles in this
	            handle space
	            IMG_TRUE - next allocated handle returned
</function>
-----------------------------------------------------------------------------*/
IMG_BOOL
HDL_SpaceNextHandle (HDL_SPACE *pHandleSpace, HDL *pHandle);

#endif