00001 /** ============================================================================ 00002 * @file pool.h 00003 * 00004 * @path $(DSPLINK)/gpp/inc/usr/ 00005 * 00006 * @brief Defines signature of POOL API Functions. 00007 * 00008 * @ver 1.65.00.03 00009 * ============================================================================ 00010 * @copyright Copyright (C) 2002-2009, Texas Instruments Incorporated - 00011 * http://www.ti.com/ 00012 * 00013 * Redistribution and use in source and binary forms, with or without 00014 * modification, are permitted provided that the following conditions 00015 * are met: 00016 * 00017 * * Redistributions of source code must retain the above copyright 00018 * notice, this list of conditions and the following disclaimer. 00019 * 00020 * * Redistributions in binary form must reproduce the above copyright 00021 * notice, this list of conditions and the following disclaimer in the 00022 * documentation and/or other materials provided with the distribution. 00023 * 00024 * * Neither the name of Texas Instruments Incorporated nor the names of 00025 * its contributors may be used to endorse or promote products derived 00026 * from this software without specific prior written permission. 00027 * 00028 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00029 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 00030 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00031 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 00032 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00033 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00034 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 00035 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 00036 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 00037 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00038 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00039 * ============================================================================ 00040 */ 00041 00042 00043 #if !defined (POOL_H) 00044 #define POOL_H 00045 00046 00047 /* ----------------------------------- DSP/BIOS Link */ 00048 #include <dsplink.h> 00049 #include <pooldefs.h> 00050 00051 00052 #if defined (__cplusplus) 00053 extern "C" { 00054 #endif 00055 00056 00057 00058 /** ============================================================================ 00059 * @func POOL_open 00060 * 00061 * @brief This function opens a specific pool referenced by the pool Id 00062 * provided. 00063 * 00064 * @param poolId 00065 * Pool Identification number. 00066 * @param params 00067 * POOL Open specific parameters. 00068 * 00069 * @return DSP_SOK 00070 * Operation completed successfully. 00071 * DSP_SALREADYOPENED 00072 * The specified POOL has already been opened. 00073 * DSP_EACCESSDENIED 00074 * Access to the DSP is denied. 00075 * DSP_EINVALIDARG 00076 * Invalid argument. 00077 * DSP_EMEMORY 00078 * Memory error. 00079 * DSP_EFAIL 00080 * General failure. 00081 * 00082 * @pre Pool ID must be less than maximum allowed value. 00083 * PROC_attach has been successful. 00084 * 00085 * @post None. 00086 * 00087 * @see POOL_close () 00088 * ============================================================================ 00089 */ 00090 EXPORT_API 00091 DSP_STATUS 00092 POOL_open (IN PoolId poolId, IN Pvoid params) ; 00093 00094 00095 /** ============================================================================ 00096 * @func POOL_close 00097 * 00098 * @brief This function closes a specific pool whose pool id is provided. 00099 * 00100 * @param poolId 00101 * Pool Identification number. 00102 * 00103 * @return DSP_SOK 00104 * Operation completed successfully. 00105 * DSP_SCLOSED 00106 * The final process has closed the specified POOL. 00107 * DSP_EINVALIDARG 00108 * Invalid argument. 00109 * DSP_EMEMORY 00110 * Memory error. 00111 * DSP_EACCESSDENIED 00112 * The POOL was not opened. 00113 * DSP_EFAIL 00114 * General failure. 00115 * 00116 * @pre Pool ID must be less than maximum allowed value. 00117 * All buffers allocated using POOL_alloc have been free'd using 00118 * POOL_free. 00119 * 00120 * @post None. 00121 * 00122 * @see POOL_open () 00123 * ============================================================================ 00124 */ 00125 EXPORT_API 00126 DSP_STATUS 00127 POOL_close (IN PoolId poolId) ; 00128 00129 00130 /** ============================================================================ 00131 * @func POOL_alloc 00132 * 00133 * @brief This function allocates a buffer of the specified size from a pool. 00134 * 00135 * @param poolId 00136 * Pool Identification number. 00137 * @param bufPtr 00138 * Location to receive a pointer to the allocated buffer. 00139 * @param size 00140 * Size of buffer to be allocated. 00141 * 00142 * @return DSP_SOK 00143 * Operation completed successfully. 00144 * DSP_EINVALIDARG 00145 * Invalid argument. 00146 * DSP_EMEMORY 00147 * Memory error. 00148 * DSP_EFAIL 00149 * General failure. 00150 * 00151 * @pre Pool ID must be less than maximum allowed value. 00152 * bufPtr must be a valid pointer. 00153 * size must be greater than 0. 00154 * POOL_open has been successful. 00155 * 00156 * @post None. 00157 * 00158 * @see POOL_free () 00159 * ============================================================================ 00160 */ 00161 EXPORT_API 00162 DSP_STATUS 00163 POOL_alloc (IN PoolId poolId, OUT Pvoid * bufPtr, IN Uint32 size) ; 00164 00165 00166 /** ============================================================================ 00167 * @func POOL_free 00168 * 00169 * @brief This function frees a buffer into the specified pool. 00170 * 00171 * @param poolId 00172 * Pool Identification number. 00173 * @param buf 00174 * Pointer to the buffer to be freed. 00175 * @param size 00176 * Size of buffer to be freed. 00177 * 00178 * @return DSP_SOK 00179 * Operation completed successfully. 00180 * DSP_EINVALIDARG 00181 * Invalid argument. 00182 * DSP_EMEMORY 00183 * Memory error. 00184 * DSP_EFAIL 00185 * General failure. 00186 * 00187 * @pre Pool ID must be less than maximum allowed value. 00188 * buf must be a valid pointer. 00189 * size must be greater than 0. 00190 * POOL_alloc has been successful. 00191 * 00192 * @post None. 00193 * 00194 * @see POOL_alloc () 00195 * ============================================================================ 00196 */ 00197 EXPORT_API 00198 DSP_STATUS 00199 POOL_free (IN PoolId poolId, IN Pvoid buf, IN Uint32 size) ; 00200 00201 00202 /** ============================================================================ 00203 * @func POOL_translateAddr 00204 * 00205 * @brief This function translates addresses between two address spaces for a 00206 * buffer that was allocated from the pool. 00207 * 00208 * @param poolId 00209 * Pool Identification number. 00210 * @param dstAddr 00211 * Location to receive the translated address. 00212 * @param dstAddrType 00213 * Type of address to be translated to. 00214 * @param srcAddr 00215 * Address of the buffer to be translated. 00216 * @param srcAddrType 00217 * Type of address of the buffer to be translated. 00218 * 00219 * @return DSP_SOK 00220 * Operation completed successfully. 00221 * DSP_EINVALIDARG 00222 * Invalid argument. 00223 * DSP_ENOTFOUND 00224 * Information about specified buffer was not available. 00225 * DSP_EFAIL 00226 * General failure. 00227 * 00228 * @pre Pool ID must be less than maximum allowed value. 00229 * dstAddr must be a valid pointer. 00230 * dstAddrType must be a valid address type. 00231 * srcAddr must be a valid pointer. 00232 * srcAddrType must be a valid address type. 00233 * 00234 * @post None. 00235 * 00236 * @see None. 00237 * ============================================================================ 00238 */ 00239 EXPORT_API 00240 DSP_STATUS 00241 POOL_translateAddr (IN PoolId poolId, 00242 OUT Pvoid * dstAddr, 00243 IN AddrType dstAddrType, 00244 IN Pvoid srcAddr, 00245 IN AddrType srcAddrType) ; 00246 00247 00248 /** ============================================================================ 00249 * @func POOL_getPoolId 00250 * 00251 * @brief This function gets the pool id of the buffer that was allocated from 00252 * the pool. 00253 * 00254 * @param procId 00255 * Processor Identifier. 00256 * @param addr 00257 * Address of the buffer whose pool id has to be determined. 00258 * @param addrType 00259 * Type of address of the buffer whose pool id has to be determined. 00260 * @param poolId 00261 * Location to receive pool id number. 00262 * 00263 * @return DSP_SOK 00264 * Operation completed successfully. 00265 * DSP_EINVALIDARG 00266 * Invalid argument. 00267 * DSP_ENOTFOUND 00268 * Specified buffer was not present in any pools. 00269 * DSP_EFAIL 00270 * General failure. 00271 * 00272 * @pre addr must be a valid pointer. 00273 * addrType must be a valid address type. 00274 * poolId must be a valid pointer. 00275 * 00276 * @post None. 00277 * 00278 * @see None. 00279 * ============================================================================ 00280 */ 00281 EXPORT_API 00282 DSP_STATUS 00283 POOL_getPoolId (IN ProcessorId procId, 00284 IN Pvoid addr, 00285 IN AddrType addrType, 00286 OUT PoolId * poolId) ; 00287 00288 00289 /** ============================================================================ 00290 * @func POOL_writeback 00291 * 00292 * @brief This function write backs the content of the buffer to peer's 00293 * 00294 * @param poolId 00295 * Pool Identification number. 00296 * @param buf 00297 * Pointer to the buffer to be invalidated. 00298 * @param size 00299 * Size of buffer to be freed. 00300 * 00301 * @return DSP_SOK 00302 * Operation completed successfully. 00303 * DSP_EINVALIDARG 00304 * Invalid argument. 00305 * DSP_EMEMORY 00306 * Memory error. 00307 * DSP_EFAIL 00308 * General failure. 00309 * 00310 * @pre Pool ID must be less than maximum allowed value. 00311 * buf must be a valid pointer. 00312 * size must be greater than 0. 00313 * 00314 * @post None. 00315 * 00316 * @see POOL_invalidate () 00317 * ============================================================================ 00318 */ 00319 EXPORT_API 00320 DSP_STATUS 00321 POOL_writeback (IN PoolId poolId, IN Pvoid buf, IN Uint32 size) ; 00322 00323 00324 /** ============================================================================ 00325 * @func POOL_invalidate 00326 * 00327 * @brief This function invalidates the content of the buffer. 00328 * 00329 * @param poolId 00330 * Pool Identification number. 00331 * @param buf 00332 * Pointer to the buffer to be invalidated. 00333 * @param size 00334 * Size of buffer to be freed. 00335 * 00336 * @return DSP_SOK 00337 * Operation completed successfully. 00338 * DSP_EINVALIDARG 00339 * Invalid argument. 00340 * DSP_EMEMORY 00341 * Memory error. 00342 * DSP_EFAIL 00343 * General failure. 00344 * 00345 * @pre Pool ID must be less than maximum allowed value. 00346 * buf must be a valid pointer. 00347 * size must be greater than 0. 00348 * 00349 * @post None. 00350 * 00351 * @see POOL_writeback () 00352 * ============================================================================ 00353 */ 00354 EXPORT_API 00355 DSP_STATUS 00356 POOL_invalidate (IN PoolId poolId, IN Pvoid buf, IN Uint32 size) ; 00357 00358 00359 /** ============================================================================ 00360 * @deprecated The deprecated API POOL_Open has been replaced 00361 * with POOL_open. 00362 * This has been done to follow DSP/BIOS codinf guidelines and 00363 * have a uniform naming convention for the API's on both GPP 00364 * as well as DSP. 00365 * 00366 * ============================================================================ 00367 */ 00368 #define POOL_Open POOL_open 00369 00370 /** ============================================================================ 00371 * @deprecated The deprecated API POOL_Close has been replaced 00372 * with POOL_close. 00373 * This has been done to follow DSP/BIOS codinf guidelines and 00374 * have a uniform naming convention for the API's on both GPP 00375 * as well as DSP. 00376 * 00377 * ============================================================================ 00378 */ 00379 #define POOL_Close POOL_close 00380 00381 /** ============================================================================ 00382 * @deprecated The deprecated API POOL_Alloc has been replaced 00383 * with POOL_alloc. 00384 * This has been done to follow DSP/BIOS codinf guidelines and 00385 * have a uniform naming convention for the API's on both GPP 00386 * as well as DSP. 00387 * 00388 * ============================================================================ 00389 */ 00390 #define POOL_Alloc POOL_alloc 00391 00392 /** ============================================================================ 00393 * @deprecated The deprecated API POOL_Free has been replaced 00394 * with POOL_free. 00395 * This has been done to follow DSP/BIOS codinf guidelines and 00396 * have a uniform naming convention for the API's on both GPP 00397 * as well as DSP. 00398 * 00399 * ============================================================================ 00400 */ 00401 #define POOL_Free POOL_free 00402 00403 /** ============================================================================ 00404 * @deprecated The deprecated API POOL_TranslateAddr has been replaced 00405 * with POOL_translateAddr. 00406 * This has been done to follow DSP/BIOS codinf guidelines and 00407 * have a uniform naming convention for the API's on both GPP 00408 * as well as DSP. 00409 * 00410 * ============================================================================ 00411 */ 00412 #define POOL_TranslateAddr POOL_translateAddr 00413 00414 00415 #if defined (__cplusplus) 00416 } 00417 #endif 00418 00419 00420 #endif /* !defined (POOL_H) */