buffer_manager.h

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

/** 
 * @File         buffer_manager.h
 *
 * @Title        Buffer 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 buffers mapped into two virtual memory spaces, host and
 * device and referenced by handles.
 * 
 * @Platform     ALL
 *
 * @defgroup BM Buffer Manager
 *
 * @{
 */

#ifndef _BUFFER_MANAGER_H_
#define _BUFFER_MANAGER_H_

#include "img_types.h"
#include "handle.h"

/** Buffer handle.
 */
typedef struct
{
    HDL h;
} BM_HANDLE;

/** Test for a valid buffer manager handle.
 */
#define BM_IS_VALID_HANDLE(hdl) (hdl.h != HDL_INVALID)

/** Invalid buffer manager handle initialiser.
 *
 *  An initialiser providing an invalid handle. The function
 *  BM_IS_VALID_HANDLE can be used to test for an invalid handle.
 */
#define BM_HANDLE_INVALID {HDL_INVALID}

/** Buffer manager allocation flags.
 *
 *  Flags passed to BM_Alloc to specify buffer capabilities.
 *
 * @defgroup BMAFS Buffer Manager Allocation Flags
 * @{
 */

/** Pool number mask. */
#define BP_POOL_MASK         0x7 

/* Request physically contiguous pages of memory */
#define BP_CONTIGUOUS          8
#define BP_HI_MEMORY          16
#define BP_AVOID_2K_BOUNDARY  32

/** @} */

/**
 *  @Function BM_Initialise
 *
 *  @Description
 *
 *  Initialise the buffer manager. This function must be called before
 *  any other buffer manager function.
 *
 *  @Input registers - cpu virtual address for the device registers.
 *    	slaveports - cpu virtual address for the slaveports.
    	ui32CoreConfig - the configuration word of the device

 *  @Return IMG_TRUE - Success, IMG_FALSE - Failed
 */
IMG_BOOL
BM_Initialise (IMG_CPU_VIRTADDR registers, IMG_CPU_VIRTADDR slaveports, 
			   IMG_UINT32 ui32CoreConfig);

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


 *  @Function   BM_Finalise
 *
 *  @Description
 *
 *  Finalise the buffer manager. Calling this function will release
 *  all allocated buffers then deallocate any resources helf by the
 *  buffer manager.
 *                      
 *  @Input None
 *  @Return None
 */
IMG_VOID
BM_Finalise (void);

/**
 *  @Function   BM_Alloc
 *
 *  @Description
 *
 *  Allocate a buffer mapped into both host and device virtual memory
 *  maps.
 *                    
 *  @Input uSize - require size in bytes of the buffer.
 *  @Input uFlags - bit mask of buffer property flags.
 *  @Input uDevVAddrAlignment - required alignment in bytes, or 0.
 *  @Output pBuf - receives the buffer handle.
 *  @Return IMG_TRUE - Success, IMG_FALSE - Failed.
 */
IMG_BOOL
BM_Alloc (IMG_SIZE_T uSize,
          IMG_UINT32 uFlags,
          IMG_UINT32 uDevVAddrAlignment,
          BM_HANDLE *pBuf);

/**
 *  @Function   BM_Wrap
 *
 *  @Description
 *
 *  Create a buffer which wraps user provided host physical memory.
 *  The wrapped memory must be page aligned. BM_Wrap will roundup the
 *  size to a multiple of host pages.
 *                      
 *  @Input base - system physical base address of memory to wrap.
 *  @Input uSize - size of memory to wrap.
 *  @Input uFlags - bit mask of buffer property flags.
 *  @Input uDevVAddrAlignment - required device virtual address
 *         alignment in bytes, or 0.
 *  @Input pBuf - receives the buffer handle.
 *  @Return IMG_TRUE - Success, IMG_FALSE - Failed
 */
IMG_BOOL
BM_Wrap (IMG_SYS_PHYADDR base,
         IMG_UINT32 uSize,
         IMG_UINT32 uFlags,
         IMG_UINT32 uDevVAddrAlignment,
         BM_HANDLE *pBuf);

/**
 *  @Function   BM_Free
 *
 *  @Description
 *
 *  Free a buffer previously allocated via BM_Alloc.
 *                      
 *  @Input  hBuf - buffer handle.
 *  @Return None.
 */
void
BM_Free (BM_HANDLE hBuf);

/**
 *  @Function   BM_HandleToCpuVaddr
 *
 *  @Description
 *
 *  Retreive the host virtual address associated with a buffer.
 *                      
 *  @Input  hBuf - buffer handle.
 *  
 *  @Return buffers host virtual address.
 */
IMG_CPU_VIRTADDR
BM_HandleToCpuVaddr (BM_HANDLE hBuf);

/**
 *  @Function   BM_HandleToDevVaddr
 *
 *  @Description
 *
 *  Retreive the device virtual address associated with a buffer.
 *                      
 *  @Input hBuf - buffer handle.
 *  @Return buffers device virtual address.
 */
IMG_DEV_VIRTADDR
BM_HandleToDevVaddr (BM_HANDLE hBuf);

/**
 *  @Function   BM_HandleToSysPaddr
 *
 *  @Description
 *
 *  Retreive the system physical address associated with a buffer.
 *                      
 *  @Input hBuf - buffer handle.
 *  @Return buffers device virtual address.
 */
IMG_SYS_PHYADDR
BM_HandleToSysPaddr (BM_HANDLE hBuf);

/**
 *  @Function BM_ContiguousStatistics
 *
 *  @Description
 *
 *  Retreive the total size of the contiguous memory source and the
 *  number of available_bytes. Neither of these statistics reflect the
 *  effects of fragmentation within the contiguous arena. The buffer
 *  manager must be initialised by calling BM_Initialise() before
 *  calling this function.
 *                      
 *  @Output pTotalBytes - receives the total number of bytes in
 *          the contiguous memory source.
 *
 *  @Output pAvailableBytes - receives the number of available
 *          bytes in the contiguous memory source.
 *
 *  @Return IMG_TRUE - Success, IMG_FALSE - Failure
 */
IMG_BOOL
BM_ContiguousStatistics (IMG_UINT32 uFlags,
                         IMG_UINT32 *pTotalBytes,
                         IMG_UINT32 *pAvailableBytes);

#endif

/* @} */