1 /****************************************************************************** 2 * 3 * Copyright 2007, Silicon Image, Inc. All rights reserved. 4 * No part of this work may be reproduced, modified, distributed, transmitted, 5 * transcribed, or translated into any language or computer format, in any form 6 * or by any means without written permission of: Silicon Image, Inc., 1060 7 * East Arques Avenue, Sunnyvale, California 94085 8 * 9 *****************************************************************************/ 10 /** 11 * @file media_buffer_pool.h 12 * 13 * @brief 14 * Media Buffer Pool interface 15 * 16 * <pre> 17 * 18 * Principal Author: Joerg Detert 19 * Creation date: Feb 28, 2008 20 * 21 * </pre> 22 * 23 *****************************************************************************/ 24 /** 25 * @mainpage Welcome to the MediaBufferPool Interface Documentation 26 * 27 * Doc-Id: xx-xxx-xxx-xxx (MediaBufferPool Implementation Spec)\n 28 * Author: Klaus Kaiser 29 * 30 * @image html silicon_image_logo.gif 31 * \n 32 * 33 * This buffer service is the central instance for all multimedia modules, which 34 * transmit data through buffers. All buffers are grouped into buffer pools. 35 * Each buffer pool contains one or multiple buffers with the same size. The buffer 36 * service usually manages buffers with uncompressed data (e.g. YUV, RGB, PCM) or 37 * compressed data (Audio-PES, Video-PES) but could be used for any type of data. 38 * Beside the plain data each buffer holds sideband information, e.g. timestamp 39 * and frame resolution. The following picture shows the buffer pool structure. 40 * 41 * @image html MediaBufferPool.png 42 * \n 43 * 44 * Allocation and management of memory is done through those Media Buffer Pools. 45 * The Buffer Pool is created with a bounded size of a contiguous physical memory block, 46 * separated into equally sized smaller blocks, the so called Media Buffer. Furthermore 47 * it is possible during initialization to specify a random access or ring buffer like 48 * access pattern, supporting different types of applications. For example hardware blocks, 49 * like decoders, which accesses content in memory through a ring buffer scheme must be 50 * supported. The Media Buffer Pool interface provides functionality to request empty 51 * buffers, to put or release filled buffers and to request filled buffers. This is the 52 * core functionality made available to connected Media Modules. 53 * 54 * 55 * - @subpage media_buffer_queue 56 * 57 */ 58 59 #ifndef MEDIA_BUFFER_POOL_H 60 #define MEDIA_BUFFER_POOL_H 61 62 63 #if defined (__cplusplus) 64 extern "C" { 65 #endif 66 67 #include "media_buffer.h" 68 69 70 /** 71 * Definition of Media Buffer Pool Flags. 72 */ 73 74 /** Buffer pool acts like a ring buffer, that means no random access */ 75 #define BUFPOOL_RINGBUFFER 0x00000001U 76 77 /** 78 * @brief Callback function that can be registered to receive 79 * Media Buffer Pool events. 80 */ 81 typedef void (*MediaBufPoolCbNotify_t) 82 ( 83 void* pUserContext, 84 const MediaBuffer_t* pMediaBuffer //!< Just for information purposes, may be used to handle chained ancillary buffers. 85 ); 86 87 88 /** 89 * @brief Structure holding all information to notify a registered user 90 */ 91 typedef struct MediaBufPoolNotify_s 92 { 93 MediaBufPoolCbNotify_t fpCallback; /**< Notification callback */ 94 void* pUserContext; /**< Pointer to user context to pass to callback */ 95 } MediaBufPoolNotify_t; 96 97 98 /** 99 * @brief MediaBufPool pool object, used to maintain a number of 100 * MediaBuffer_t elements. Each MediaBuffer_t can be automatically 101 * associated to a memory chunk. The pool has to be initialized via 102 * MediaBufPoolCreate() and released via MediaBufPoolDestroy(). 103 */ 104 typedef struct MediaBufPool_s 105 { 106 void* pBaseAddress; /**< Base address of buffer pool. Note that */ 107 /**< a buffer pool is a contingous chunk of */ 108 /**< memory. */ 109 void* pMetaDataMediaBufBase; /**< Base address of meta data buffer pool for Media Buffers. 110 These meta data structures are linked to the Media Buffers. */ 111 uint32_t bufSize; /**< Size of each buffer in bytes. */ 112 uint32_t metaDataSizeMediaBuf; /**< Size of meta data associated with media buffer. */ 113 114 uint16_t bufNum; /**< Number of buffers in buffer pool. */ 115 uint16_t maxBufNum; 116 uint32_t poolSize; /**< Size of complete buffer pool in bytes. */ 117 MediaBuffer_t* pBufArray; /**< Array used to manage each buffer in the pool */ 118 uint32_t flags; /**< Buffer Pool flags. */ 119 uint16_t freeBufNum; /**< Resources count: Number of free buffers */ 120 uint32_t fillLevel; /**< How many buffers are filled with data */ 121 uint16_t highWatermark; /**< if value is reached high watermark callback is triggered */ 122 uint16_t lowWatermark; /**< if value is reached low watermark callback is triggered */ 123 uint32_t index; /**< Pointer to current index in buffer array (internal use) */ 124 MediaBufPoolNotify_t notify; /**< Array with info about users registered for notification */ 125 } MediaBufPool_t; 126 127 128 /** 129 * @brief The MediaBufPoolConfig is used to calculate the amount of memory needed to use 130 * pool. The call to @ref MediaBufPoolGetSize will fill the sizes of the needed memory. 131 * The user is then responsible to allocate the memory and pass the structure to the 132 * @ref MediaBufPoolCreate function. 133 * 134 */ 135 typedef struct MediaBufPoolConfig_s 136 { 137 /* Input parameters */ 138 uint32_t bufSize; /**< Size of memory chunk a buffer represents */ 139 uint32_t metaDataSizeMediaBuf; /**< Size of extra meta data strutucture attached to each Media buffer (pointed to by MediaBuffer_t.pMetaData) */ 140 uint32_t flags; /**< Configuration flags */ 141 uint16_t bufNum; /**< Initial number of buffers */ 142 uint16_t bufAlign; /**< Needed alignment of each memory chunk the buffers represent */ 143 uint16_t maxBufNum; /**< Maximum number of buffers */ 144 145 /* Output parameters */ 146 uint32_t metaDataMemSize; /**< Size of memory for buffer structures plus extra meta data. 147 This needs to be directly accesable by CPU. */ 148 uint32_t bufMemSize; /**< Size of complete data memory which is represented by the buffers. */ 149 } MediaBufPoolConfig_t; 150 151 152 /** 153 * @brief MediaBufPoolMemory is used to pass memory to the Media Buffer Pool. 154 */ 155 typedef struct MediaBufPoolMemory_s 156 { 157 void* pMetaDataMemory; /**< Memory for administrative and extra meta data structures (for MediaBuffer), 158 must be of size MediaBufPoolConfig_t.metaDataMemSize as reported by MediaBufPoolGetSize. */ 159 void* pBufferMemory; /**< Actual memory where the data is going to be placed, 160 must be of size MediaBufPoolConfig_t.bufMemSize as reported by MediaBufPoolGetSize. 161 Furthermore, must be aligned as specified by MediaBufPoolConfig_t.bufAlign. */ 162 } MediaBufPoolMemory_t; 163 164 165 /** 166 * @brief Get a free buffer from the MediaBufferPool. 167 * 168 * @param pBufPool Pointer to the MediaBufferPool. 169 * 170 *****************************************************************************/ 171 MediaBuffer_t* MediaBufPoolGetBuffer(MediaBufPool_t* pBufPool); 172 173 174 /** 175 * @brief Inform MediaBufferPool that buffer has been filled. 176 * 177 * @param pBuf Full buffer to add. 178 * 179 *****************************************************************************/ 180 void MediaBufPoolBufferFilled(MediaBufPool_t* pBufPool, MediaBuffer_t* pBuf); 181 182 183 /** 184 * @brief Free a buffer from the bufferpool. 185 * 186 * @param pBuf Buffer to free 187 * 188 *****************************************************************************/ 189 void MediaBufPoolFreeBuffer(MediaBufPool_t* pBufPool, MediaBuffer_t* pBuf); 190 191 192 /** 193 * @brief Calculate the size of the memory the MediaBufferPool needs 194 * for the metadata the internal structure and the array of buffers. 195 * The caller has to assure to fill the structure with the corresponding 196 * information need. He has to fill bufSize, metaDataSize, bufNum, 197 * bufAlign and maxBufNum. With these information the function can 198 * calculate the amount of memory need. 199 * When the function returns the values for bufPoolMemSize and 200 * bufMemSize are filled. 201 * 202 * @param pPoolConfig Configuration parameters for the media buffer pool. 203 * 204 * @return Status of operation. 205 *****************************************************************************/ 206 RESULT MediaBufPoolGetSize(MediaBufPoolConfig_t* pPoolConfig); 207 208 209 /** 210 * @brief Create a buffer pool. 211 * 212 * @param pBufPool Pointer to buffer pool object to be created. 213 * @param pPoolConfig Pointer to config params for buffer pool. 214 * @param poolMemory Pool memory information. 215 * 216 * @return Status of operation. 217 *****************************************************************************/ 218 extern RESULT MediaBufPoolCreate(MediaBufPool_t* pBufPool, 219 MediaBufPoolConfig_t* pPoolConfig, 220 MediaBufPoolMemory_t poolMemory); 221 222 223 /*****************************************************************************/ 224 /** 225 * @brief Destroy a buffer pool. 226 * 227 * @param pBufPool Pointer to buffer pool object to be destroyed. 228 * 229 * @return Status of operation. 230 *****************************************************************************/ 231 extern RESULT MediaBufPoolDestroy(MediaBufPool_t* pBufPool); 232 233 234 /*****************************************************************************/ 235 /** 236 * @brief Reset a buffer pool. 237 * 238 * @param pBufPool Pointer to buffer pool object to be reset. 239 * 240 * @return Status of operation. 241 *****************************************************************************/ 242 extern RESULT MediaBufPoolReset(MediaBufPool_t* pBufPool); 243 244 245 /* ***************************************************************************/ 246 /** 247 * @brief Register a callback to get informed about MediaBufPool status. 248 * 249 * @param pBufPool Pointer to buffer pool object. 250 * @param fpCallback Function to be triggered in case of event. 251 * @param pUserContext Pointer passed in each call of the callback. 252 * 253 * @return Status of operation. 254 *****************************************************************************/ 255 extern RESULT MediaBufPoolRegisterCb(MediaBufPool_t* pBufPool, 256 MediaBufPoolCbNotify_t fpCallback, 257 void* pUserContext); 258 259 260 /****************************************************************************/ 261 /** 262 * @brief Deregister a callback from MediaBufPool 263 * 264 * @param pBufPool Pointer to buffer pool object. 265 * @param fpCallback Function to be deregistered. 266 * 267 * @return Status of operation. 268 *****************************************************************************/ 269 extern RESULT MediaBufPoolDeregisterCb(MediaBufPool_t* pBufPool, 270 MediaBufPoolCbNotify_t fpCallback); 271 272 273 #if defined (__cplusplus) 274 } 275 #endif 276 277 278 #endif /* MEDIA_BUFFER_POOL_H*/ 279 280