Main Page | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

pool.h

Go to the documentation of this file.
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) */

Generated on Fri Jul 16 14:34:03 2010 for DSP/BIOSLink by  doxygen 1.4.4