1 /** \file bufferPoolApi.h 2 * \brief This file include public definitions for the buffer pool data structure, 3 * \brief comprising its API. 4 * \author Ronen Kalish 5 * \date 05-December-2005 6 */ 7 8 /**************************************************************************** 9 **+-----------------------------------------------------------------------+** 10 **| |** 11 **| Copyright(c) 1998 - 2008 Texas Instruments. All rights reserved. |** 12 **| All rights reserved. |** 13 **| |** 14 **| Redistribution and use in source and binary forms, with or without |** 15 **| modification, are permitted provided that the following conditions |** 16 **| are met: |** 17 **| |** 18 **| * Redistributions of source code must retain the above copyright |** 19 **| notice, this list of conditions and the following disclaimer. |** 20 **| * Redistributions in binary form must reproduce the above copyright |** 21 **| notice, this list of conditions and the following disclaimer in |** 22 **| the documentation and/or other materials provided with the |** 23 **| distribution. |** 24 **| * Neither the name Texas Instruments nor the names of its |** 25 **| contributors may be used to endorse or promote products derived |** 26 **| from this software without specific prior written permission. |** 27 **| |** 28 **| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |** 29 **| "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |** 30 **| LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |** 31 **| A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |** 32 **| OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |** 33 **| SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |** 34 **| LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |** 35 **| DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |** 36 **| THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |** 37 **| (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |** 38 **| OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |** 39 **| |** 40 **+-----------------------------------------------------------------------+** 41 ****************************************************************************/ 42 43 #include "osTIType.h" 44 45 #ifndef __BUFFER_POOL_API_H__ 46 #define __BUFFER_POOL_API_H__ 47 /* 48 *********************************************************************** 49 * Constant definitions. 50 *********************************************************************** 51 */ 52 #define BUFFER_POOL_NO_BUFFER NULL 53 54 #ifdef TI_DBG 55 /* Maximum number of buffers being tracked in debug mode */ 56 #define BUFFER_POOL_MAX_NUM_OF_BUFFERS_FOR_DBG 1000 57 #endif /* TI_DBG */ 58 59 /* 60 *********************************************************************** 61 * Enums. 62 *********************************************************************** 63 */ 64 65 /* 66 *********************************************************************** 67 * Typedefs. 68 *********************************************************************** 69 */ 70 71 /** \typedef bufferPool_buffer_t 72 * \brief Defines a buffer data type (pointer to void) 73 */ 74 typedef void* bufferPool_buffer_t; 75 76 /* 77 *********************************************************************** 78 * Structure definitions. 79 *********************************************************************** 80 */ 81 #ifdef TI_DBG 82 /** \struct bufferPoolDbg_t 83 * \brief This structure holds buffer pool debug information.\n 84 */ 85 typedef struct 86 { 87 UINT32 numberOfUsedBuffers; /**< 88 * The number of buffers currently 89 * not allocated in this pool 90 */ 91 UINT32 NumberOfSuccessfulAllocations; /**< 92 * Number of allocation requests 93 * ended successfuly 94 */ 95 UINT32 NumberOfDeclinedAllocations; /**< 96 * Number of failed allocation requests 97 * due to no memory 98 */ 99 UINT32 NumberOfFreeBufferRefreed; /**< 100 * Number of buffers for which free was 101 * called when they were already free 102 */ 103 BOOLEAN bAllocated[ BUFFER_POOL_MAX_NUM_OF_BUFFERS_FOR_DBG ]; 104 /**< 105 * A boolean array indicating for each 106 * buffer if its allocation status 107 */ 108 } bufferPoolDbg_t; 109 #endif /* TI_DBG */ 110 111 /* 112 *********************************************************************** 113 * External data definitions. 114 *********************************************************************** 115 */ 116 117 /* 118 *********************************************************************** 119 * External functions definitions 120 *********************************************************************** 121 */ 122 /** 123 * \author Ronen Kalish\n 124 * \date 05-December-2005\n 125 * \brief Creates a buffer pool object 126 * 127 * Function Scope \e Public.\n 128 * \param hOS - handle to the OS object.\n 129 * \param numOfBuffers - the number of buffers to allocate for this pool.\n 130 * \param bufferSize - the size of each buffer in this pool.\n 131 * \return a handle to a buffer pool object, NULL if an error occurred.\n 132 */ 133 TI_HANDLE bufferPool_create( TI_HANDLE hOS, UINT32 numOfBuffers, UINT32 bufferSize ); 134 135 /** 136 * \author Ronen Kalish\n 137 * \date 05-December-2005\n 138 * \brief Configures a buffer pool object.\n 139 * 140 * Function Scope \e Public.\n 141 * \param hbufferPool - handle to a buffer pool object.\n 142 * \param hReport - handle to the report module.\n 143 */ 144 void bufferPool_config( TI_HANDLE hBufferPool, TI_HANDLE hReport ); 145 146 /** 147 * \author Ronen Kalish\n 148 * \date 05-December-2005\n 149 * \brief releasing a buffer pool object.\n 150 * 151 * Function Scope \e Public.\n 152 * \param hbufferPool - handle to a buffer pool object.\n 153 */ 154 void bufferPool_destroy( TI_HANDLE hBufferPool ); 155 156 /** 157 * \author Ronen Kalish\n 158 * \date 05-December-2005\n 159 * \brief Reinitializes the buffer pool object, by marking all buffers 160 * \brief as unallocated.\n 161 * 162 * Function Scope \e Public.\n 163 * \param hbufferPool - handle to a buffer pool object.\n 164 */ 165 void bufferPool_reinit( TI_HANDLE hBufferPool ); 166 167 /** 168 * \author Ronen Kalish\n 169 * \date 05-December-2005\n 170 * \brief Allocates a buffer.\n 171 * 172 * Function Scope \e Public.\n 173 * \param hbufferPool - handle to a buffer pool object.\n 174 * \return a buffer object, BUFFER_POOL_NO_BUFFER indication if non is available.\n 175 */ 176 bufferPool_buffer_t bufferPool_allocateBuffer( TI_HANDLE hBufferPool ); 177 178 /** 179 * \author Ronen Kalish\n 180 * \date 05-December-2005\n 181 * \brief returns a buffer to the pool.\n 182 * 183 * Function Scope \e Public.\n 184 * \param hbufferPool - handle to a buffer pool object.\n 185 * \param buffer - the buffer object to return to the pool.\n 186 */ 187 void bufferPool_releaseBuffer( TI_HANDLE hBufferPool, bufferPool_buffer_t buffer ); 188 189 #ifdef TI_DBG 190 /** 191 * \author Ronen Kalish\n 192 * \date 29-December-2005\n 193 * \brief Returns the buffer pool debug structure.\n 194 * 195 * Function Scope \e Public.\n 196 * \param hbufferPool - handle to a buffer pool object.\n 197 */ 198 bufferPoolDbg_t *bufferPool_getDebugInformation( TI_HANDLE hBufferPool ); 199 #endif /* TI_DBG */ 200 201 #endif /* __BUFFER_POOL_API_H__ */ 202 203