/******************************************************************************
|
*
|
* Copyright 2007, Silicon Image, Inc. All rights reserved.
|
* No part of this work may be reproduced, modified, distributed, transmitted,
|
* transcribed, or translated into any language or computer format, in any form
|
* or by any means without written permission of: Silicon Image, Inc., 1060
|
* East Arques Avenue, Sunnyvale, California 94085
|
*
|
*****************************************************************************/
|
/**
|
* @file media_buffer_pool.h
|
*
|
* @brief
|
* Media Buffer Pool interface
|
*
|
* <pre>
|
*
|
* Principal Author: Joerg Detert
|
* Creation date: Feb 28, 2008
|
*
|
* </pre>
|
*
|
*****************************************************************************/
|
/**
|
* @mainpage Welcome to the MediaBufferPool Interface Documentation
|
*
|
* Doc-Id: xx-xxx-xxx-xxx (MediaBufferPool Implementation Spec)\n
|
* Author: Klaus Kaiser
|
*
|
* @image html silicon_image_logo.gif
|
* \n
|
*
|
* This buffer service is the central instance for all multimedia modules, which
|
* transmit data through buffers. All buffers are grouped into buffer pools.
|
* Each buffer pool contains one or multiple buffers with the same size. The buffer
|
* service usually manages buffers with uncompressed data (e.g. YUV, RGB, PCM) or
|
* compressed data (Audio-PES, Video-PES) but could be used for any type of data.
|
* Beside the plain data each buffer holds sideband information, e.g. timestamp
|
* and frame resolution. The following picture shows the buffer pool structure.
|
*
|
* @image html MediaBufferPool.png
|
* \n
|
*
|
* Allocation and management of memory is done through those Media Buffer Pools.
|
* The Buffer Pool is created with a bounded size of a contiguous physical memory block,
|
* separated into equally sized smaller blocks, the so called Media Buffer. Furthermore
|
* it is possible during initialization to specify a random access or ring buffer like
|
* access pattern, supporting different types of applications. For example hardware blocks,
|
* like decoders, which accesses content in memory through a ring buffer scheme must be
|
* supported. The Media Buffer Pool interface provides functionality to request empty
|
* buffers, to put or release filled buffers and to request filled buffers. This is the
|
* core functionality made available to connected Media Modules.
|
*
|
*
|
* - @subpage media_buffer_queue
|
*
|
*/
|
|
#ifndef MEDIA_BUFFER_POOL_H
|
#define MEDIA_BUFFER_POOL_H
|
|
|
#if defined (__cplusplus)
|
extern "C" {
|
#endif
|
|
#include "media_buffer.h"
|
|
|
/**
|
* Definition of Media Buffer Pool Flags.
|
*/
|
|
/** Buffer pool acts like a ring buffer, that means no random access */
|
#define BUFPOOL_RINGBUFFER 0x00000001U
|
|
/**
|
* @brief Callback function that can be registered to receive
|
* Media Buffer Pool events.
|
*/
|
typedef void (*MediaBufPoolCbNotify_t)
|
(
|
void* pUserContext,
|
const MediaBuffer_t* pMediaBuffer //!< Just for information purposes, may be used to handle chained ancillary buffers.
|
);
|
|
|
/**
|
* @brief Structure holding all information to notify a registered user
|
*/
|
typedef struct MediaBufPoolNotify_s
|
{
|
MediaBufPoolCbNotify_t fpCallback; /**< Notification callback */
|
void* pUserContext; /**< Pointer to user context to pass to callback */
|
} MediaBufPoolNotify_t;
|
|
|
/**
|
* @brief MediaBufPool pool object, used to maintain a number of
|
* MediaBuffer_t elements. Each MediaBuffer_t can be automatically
|
* associated to a memory chunk. The pool has to be initialized via
|
* MediaBufPoolCreate() and released via MediaBufPoolDestroy().
|
*/
|
typedef struct MediaBufPool_s
|
{
|
void* pBaseAddress; /**< Base address of buffer pool. Note that */
|
/**< a buffer pool is a contingous chunk of */
|
/**< memory. */
|
void* pMetaDataMediaBufBase; /**< Base address of meta data buffer pool for Media Buffers.
|
These meta data structures are linked to the Media Buffers. */
|
uint32_t bufSize; /**< Size of each buffer in bytes. */
|
uint32_t metaDataSizeMediaBuf; /**< Size of meta data associated with media buffer. */
|
|
uint16_t bufNum; /**< Number of buffers in buffer pool. */
|
uint16_t maxBufNum;
|
uint32_t poolSize; /**< Size of complete buffer pool in bytes. */
|
MediaBuffer_t* pBufArray; /**< Array used to manage each buffer in the pool */
|
uint32_t flags; /**< Buffer Pool flags. */
|
uint16_t freeBufNum; /**< Resources count: Number of free buffers */
|
uint32_t fillLevel; /**< How many buffers are filled with data */
|
uint16_t highWatermark; /**< if value is reached high watermark callback is triggered */
|
uint16_t lowWatermark; /**< if value is reached low watermark callback is triggered */
|
uint32_t index; /**< Pointer to current index in buffer array (internal use) */
|
MediaBufPoolNotify_t notify; /**< Array with info about users registered for notification */
|
} MediaBufPool_t;
|
|
|
/**
|
* @brief The MediaBufPoolConfig is used to calculate the amount of memory needed to use
|
* pool. The call to @ref MediaBufPoolGetSize will fill the sizes of the needed memory.
|
* The user is then responsible to allocate the memory and pass the structure to the
|
* @ref MediaBufPoolCreate function.
|
*
|
*/
|
typedef struct MediaBufPoolConfig_s
|
{
|
/* Input parameters */
|
uint32_t bufSize; /**< Size of memory chunk a buffer represents */
|
uint32_t metaDataSizeMediaBuf; /**< Size of extra meta data strutucture attached to each Media buffer (pointed to by MediaBuffer_t.pMetaData) */
|
uint32_t flags; /**< Configuration flags */
|
uint16_t bufNum; /**< Initial number of buffers */
|
uint16_t bufAlign; /**< Needed alignment of each memory chunk the buffers represent */
|
uint16_t maxBufNum; /**< Maximum number of buffers */
|
|
/* Output parameters */
|
uint32_t metaDataMemSize; /**< Size of memory for buffer structures plus extra meta data.
|
This needs to be directly accesable by CPU. */
|
uint32_t bufMemSize; /**< Size of complete data memory which is represented by the buffers. */
|
} MediaBufPoolConfig_t;
|
|
|
/**
|
* @brief MediaBufPoolMemory is used to pass memory to the Media Buffer Pool.
|
*/
|
typedef struct MediaBufPoolMemory_s
|
{
|
void* pMetaDataMemory; /**< Memory for administrative and extra meta data structures (for MediaBuffer),
|
must be of size MediaBufPoolConfig_t.metaDataMemSize as reported by MediaBufPoolGetSize. */
|
void* pBufferMemory; /**< Actual memory where the data is going to be placed,
|
must be of size MediaBufPoolConfig_t.bufMemSize as reported by MediaBufPoolGetSize.
|
Furthermore, must be aligned as specified by MediaBufPoolConfig_t.bufAlign. */
|
} MediaBufPoolMemory_t;
|
|
|
/**
|
* @brief Get a free buffer from the MediaBufferPool.
|
*
|
* @param pBufPool Pointer to the MediaBufferPool.
|
*
|
*****************************************************************************/
|
MediaBuffer_t* MediaBufPoolGetBuffer(MediaBufPool_t* pBufPool);
|
|
|
/**
|
* @brief Inform MediaBufferPool that buffer has been filled.
|
*
|
* @param pBuf Full buffer to add.
|
*
|
*****************************************************************************/
|
void MediaBufPoolBufferFilled(MediaBufPool_t* pBufPool, MediaBuffer_t* pBuf);
|
|
|
/**
|
* @brief Free a buffer from the bufferpool.
|
*
|
* @param pBuf Buffer to free
|
*
|
*****************************************************************************/
|
void MediaBufPoolFreeBuffer(MediaBufPool_t* pBufPool, MediaBuffer_t* pBuf);
|
|
|
/**
|
* @brief Calculate the size of the memory the MediaBufferPool needs
|
* for the metadata the internal structure and the array of buffers.
|
* The caller has to assure to fill the structure with the corresponding
|
* information need. He has to fill bufSize, metaDataSize, bufNum,
|
* bufAlign and maxBufNum. With these information the function can
|
* calculate the amount of memory need.
|
* When the function returns the values for bufPoolMemSize and
|
* bufMemSize are filled.
|
*
|
* @param pPoolConfig Configuration parameters for the media buffer pool.
|
*
|
* @return Status of operation.
|
*****************************************************************************/
|
RESULT MediaBufPoolGetSize(MediaBufPoolConfig_t* pPoolConfig);
|
|
|
/**
|
* @brief Create a buffer pool.
|
*
|
* @param pBufPool Pointer to buffer pool object to be created.
|
* @param pPoolConfig Pointer to config params for buffer pool.
|
* @param poolMemory Pool memory information.
|
*
|
* @return Status of operation.
|
*****************************************************************************/
|
extern RESULT MediaBufPoolCreate(MediaBufPool_t* pBufPool,
|
MediaBufPoolConfig_t* pPoolConfig,
|
MediaBufPoolMemory_t poolMemory);
|
|
|
/*****************************************************************************/
|
/**
|
* @brief Destroy a buffer pool.
|
*
|
* @param pBufPool Pointer to buffer pool object to be destroyed.
|
*
|
* @return Status of operation.
|
*****************************************************************************/
|
extern RESULT MediaBufPoolDestroy(MediaBufPool_t* pBufPool);
|
|
|
/*****************************************************************************/
|
/**
|
* @brief Reset a buffer pool.
|
*
|
* @param pBufPool Pointer to buffer pool object to be reset.
|
*
|
* @return Status of operation.
|
*****************************************************************************/
|
extern RESULT MediaBufPoolReset(MediaBufPool_t* pBufPool);
|
|
|
/* ***************************************************************************/
|
/**
|
* @brief Register a callback to get informed about MediaBufPool status.
|
*
|
* @param pBufPool Pointer to buffer pool object.
|
* @param fpCallback Function to be triggered in case of event.
|
* @param pUserContext Pointer passed in each call of the callback.
|
*
|
* @return Status of operation.
|
*****************************************************************************/
|
extern RESULT MediaBufPoolRegisterCb(MediaBufPool_t* pBufPool,
|
MediaBufPoolCbNotify_t fpCallback,
|
void* pUserContext);
|
|
|
/****************************************************************************/
|
/**
|
* @brief Deregister a callback from MediaBufPool
|
*
|
* @param pBufPool Pointer to buffer pool object.
|
* @param fpCallback Function to be deregistered.
|
*
|
* @return Status of operation.
|
*****************************************************************************/
|
extern RESULT MediaBufPoolDeregisterCb(MediaBufPool_t* pBufPool,
|
MediaBufPoolCbNotify_t fpCallback);
|
|
|
#if defined (__cplusplus)
|
}
|
#endif
|
|
|
#endif /* MEDIA_BUFFER_POOL_H*/
|
