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

gpp/inc/mplist.h

Go to the documentation of this file.
00001 /** ============================================================================
00002  *  @file   mplist.h
00003  *
00004  *  @path   $(DSPLINK)/gpp/inc/usr/
00005  *
00006  *  @brief  Declarations of Multi-processor list management control structures
00007  *          and definitions of list management functions for lists present in
00008  *          shared memory.
00009  *
00010  *  @ver    1.65.00.03
00011  *  ============================================================================
00012  *  @copyright Copyright (C) 2002-2009, Texas Instruments Incorporated -
00013  *  http://www.ti.com/
00014  *
00015  *  Redistribution and use in source and binary forms, with or without
00016  *  modification, are permitted provided that the following conditions
00017  *  are met:
00018  *  
00019  *  *  Redistributions of source code must retain the above copyright
00020  *     notice, this list of conditions and the following disclaimer.
00021  *  
00022  *  *  Redistributions in binary form must reproduce the above copyright
00023  *     notice, this list of conditions and the following disclaimer in the
00024  *     documentation and/or other materials provided with the distribution.
00025  *  
00026  *  *  Neither the name of Texas Instruments Incorporated nor the names of
00027  *     its contributors may be used to endorse or promote products derived
00028  *     from this software without specific prior written permission.
00029  *  
00030  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00031  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
00032  *  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00033  *  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
00034  *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00035  *  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00036  *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
00037  *  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
00038  *  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
00039  *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00040  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00041  *  ============================================================================
00042  */
00043 
00044 
00045 #if !defined (MPLIST_H)
00046 #define MPLIST_H
00047 
00048 
00049 /*  ----------------------------------- DSP/BIOS LINK Headers       */
00050 #include <dsplink.h>
00051 #include <mplistdefs.h>
00052 
00053 
00054 #if defined (__cplusplus)
00055 extern "C" {
00056 #endif
00057 
00058 
00059 /** ============================================================================
00060  *  @func   MPLIST_create
00061  *
00062  *  @brief  Allocates and initializes a doubly linked circular list in shared
00063  *          memory. The memory for the object may or may not be provided by the
00064  *          user.
00065  *          Uses POOl api to allocate a list object. The list object contains a
00066  *          MPCS object and a single element and initializes that element to
00067  *          indicate that it is the "end of the list" (i.e., the list is empty).
00068  *          An entry is added in the shared memory control structure for the
00069  *          list.
00070  *
00071  *  @param procId
00072  *              Processor id of the processor making this create call.
00073  *  @param mplistObj
00074  *              Pointer to the shared MPLIST object.
00075  *              If memory for the MPLIST object is provided by the user, the
00076  *              MPLIST object handle is not NULL.
00077  *              Otherwise, if the memory is to be allocated by the MPLIST
00078  *              component, the MPLIST object handle can be specified as
00079  *              NULL.
00080  *  @param name
00081  *              Name of the list to be created.
00082  *  @param attrs
00083  *              Attributes of the list to be created.
00084  *
00085  *  @return DSP_SOK
00086  *              Operation successfully completed.
00087  *          DSP_EINVALIDARG
00088  *              Invalid arguments.
00089  *          DSP_EMEMORY
00090  *              Operation failed due to a memory error.
00091  *          DSP_EALREADYEXISTS
00092  *              The specified MPLIST name is already in use.
00093  *          DSP_ERESOURCE
00094  *              All MPLIST entries are currently in use.
00095  *          DSP_EACCESSDENIED
00096  *              The MPLIST component has not been initialized.
00097  *          DSP_ENOTFOUND
00098  *              Information about specified POOL buffer was not available.
00099  *          DSP_EFAIL
00100  *              General failure.
00101  *
00102  *  @pre    Processor id must be valid.
00103  *          MPLIST name must be valid.
00104  *          MPLIST creation attributes must be a valid.
00105  *          PROC_attach has been successful.
00106  *          POOL has been configured according to application specification.
00107  *
00108  *  @post   None
00109  *
00110  *  @see    MPLIST_delete
00111  *  ============================================================================
00112  */
00113 EXPORT_API
00114 DSP_STATUS
00115 MPLIST_create (IN     ProcessorId    procId,
00116                IN     Char8 *        name,
00117                IN     MPLIST_List *  mplistObj,
00118                IN     MPLIST_Attrs * attrs) ;
00119 
00120 
00121 /** ============================================================================
00122  *  @func   MPLIST_delete
00123  *
00124  *  @brief  Removes a list by freeing its control structure's memory space.
00125  *          Must ONLY be used for empty lists, because it does not delete the
00126  *          list elements.  Calling this function on a non-empty list will cause
00127  *          a memory leak.
00128  *
00129  *  @param procId
00130  *              Processor id of the processor making this delete call.
00131  *  @param name
00132  *              Name of the list to be deleted.
00133  *
00134  *  @return DSP_SOK
00135  *              Operation successfully completed.
00136  *          DSP_EINVALIDARG
00137  *              Invalid arguments.
00138  *          DSP_EACCESSDENIED
00139  *              The MPLIST component has not been initialized.
00140  *          DSP_ENOTFOUND
00141  *              The MPLIST to be deleted is not present.
00142  *              Information about specified POOL buffer was not available.
00143  *          DSP_EFAIL
00144  *              General Failure.
00145  *
00146  *  @pre    Processor Id must be valid.
00147  *          MPLIST name must be valid.
00148  *          All MPLIST operations on that MP_LIST are complete.
00149  *
00150  *  @post   None
00151  *
00152  *  @see    MPLIST_create
00153  *  ============================================================================
00154  */
00155 EXPORT_API
00156 DSP_STATUS
00157 MPLIST_delete (IN ProcessorId procId,
00158                IN Char8 *     name) ;
00159 
00160 
00161 /** ============================================================================
00162  *  @func   MPLIST_open
00163  *
00164  *  @brief  This function opens an MPLIST object specified by its name and gets
00165  *          a handle to the object.
00166  *          Every process that needs to use the MPLIST object must get a handle
00167  *          to the object by calling this API.
00168  *
00169  *  @param procId
00170  *              Processor id of the processor making the open call.
00171  *  @param name
00172  *              Name of the list to be opened.
00173  *  @param mplistHandle
00174  *              Handle of list which has been opened.
00175  *
00176  *  @return DSP_SOK
00177  *              Operation successfully completed.
00178  *          DSP_EINVALIDARG
00179  *              Invalid arguments.
00180  *          DSP_EFAIL
00181  *              General Failure.
00182  *          DSP_EACCESSDENIED
00183  *              The MPLIST component has not been initialized.
00184  *          DSP_ENOTFOUND
00185  *              The MPLIST to be deleted is not present.
00186  *              Information about specified POOL buffer was not available.
00187  *          DSP_EACCESSDENIED
00188  *              The MPLIST component has not been initialized.
00189  *
00190  *  @pre    mplistHandle must be a valid pointer.
00191  *          name must be a valid pointer.
00192  *          MPLIST_create has been successful.
00193  *
00194  *  @post   None
00195  *
00196  *  @see    MPLIST_close
00197  *  ============================================================================
00198  */
00199 EXPORT_API
00200 DSP_STATUS
00201 MPLIST_open (IN     ProcessorId     procId,
00202              IN     Char8 *         name,
00203              OUT    MPLIST_Handle * mplistHandle) ;
00204 
00205 
00206 /** ============================================================================
00207  *  @func   MPLIST_close
00208  *
00209  *  @brief  This function closes an MPLIST instance.
00210  *
00211  *  @param mplistHandle
00212  *              Handle for list operations.
00213  *
00214  *  @return DSP_SOK
00215  *              Operation successfully completed.
00216  *          DSP_SFREE
00217  *              Resource has been freed successfully.
00218  *          DSP_EINVALIDARG
00219  *              Invalid arguments.
00220  *          DSP_EACCESSDENIED
00221  *              The MPLIST component has not been initialized.
00222  *          DSP_EFAIL
00223  *              General Failure.
00224  *
00225  *  @pre    mplistHandle must be a valid pointer.
00226  *          All MPLIST operations are successful.
00227  *
00228  *  @post   None
00229  *
00230  *  @see    MPLIST_open
00231  *
00232  *  @modif  None
00233  *  ============================================================================
00234  */
00235 EXPORT_API
00236 DSP_STATUS
00237 MPLIST_close (IN MPLIST_Handle mplistHandle) ;
00238 
00239 
00240 /** ============================================================================
00241  *  @func   MPLIST_isEmpty
00242  *
00243  *  @brief  Check for an empty list.
00244  *
00245  *  @param mplistHandle
00246  *              Handle for list operations.
00247  *
00248  *  @return TRUE
00249  *              List is empty.
00250  *          FALSE
00251  *              List is not empty.
00252  *
00253  *  @pre    mplistHandle must be a valid pointer.
00254  *          MPLIST_create has been successful.
00255  *
00256  *  @post   None
00257  *
00258  *  @see    None
00259  *  ============================================================================
00260  */
00261 EXPORT_API
00262 Bool
00263 MPLIST_isEmpty (IN  MPLIST_Handle mplistHandle) ;
00264 
00265 
00266 /** ============================================================================
00267  *  @func   MPLIST_insertBefore
00268  *
00269  *  @brief  Inserts the element before the existing element.
00270  *
00271  *  @param mplistHandle
00272  *              Handle for list operations.
00273  *  @param insertElement
00274  *              Pointer to element in list to insert.
00275  *  @param existingElement
00276  *              Pointer to existing list element.
00277  *
00278  *  @return DSP_SOK
00279  *              Operation successfully completed.
00280  *          DSP_EINVALIDARG
00281  *              Invalid arguments.
00282  *          DSP_ENOTFOUND
00283  *              Information about specified POOL buffer was not available.
00284  *          DSP_EFAIL
00285  *              General Failure.
00286  *
00287  *  @pre    mplistHandle must be a valid pointer.
00288  *          insertElement must be a valid pointer.
00289  *          existingElement must be a valid pointer.
00290  *          MPLIST_open has been successful.
00291  *
00292  *  @post   None
00293  *
00294  *  @see    MPLIST_create, MPLIST_putTail
00295  *  ============================================================================
00296  */
00297 EXPORT_API
00298 DSP_STATUS
00299 MPLIST_insertBefore (IN  MPLIST_Handle mplistHandle,
00300                      IN  MPLIST_Elem   insertElement,
00301                      IN  MPLIST_Elem   existingElement) ;
00302 
00303 
00304 /** ============================================================================
00305  *  @func   MPLIST_putTail
00306  *
00307  *  @brief  Adds the specified element to the tail of the list.
00308  *
00309  *  @param mplistHandle
00310  *              Handle for list operations.
00311  *  @param element
00312  *              Pointer to list element to be added.
00313  *
00314  *  @return DSP_SOK
00315  *              Operation successfully completed.
00316  *          DSP_EINVALIDARG
00317  *              Invalid arguments.
00318  *          DSP_ENOTFOUND
00319  *              Information about specified POOL buffer was not available.
00320  *          DSP_EFAIL
00321  *              General Failure.
00322  *
00323  *  @pre    mplistHandle must be a valid pointer.
00324  *          element must be a valid pointer.
00325  *          MPLIST_open has been successful.
00326  *
00327  *  @post   None
00328  *
00329  *  @see    MPLIST_insertBefore
00330  *  ============================================================================
00331  */
00332 EXPORT_API
00333 DSP_STATUS
00334 MPLIST_putTail (IN MPLIST_Handle mplistHandle,
00335                 IN MPLIST_Elem element) ;
00336 
00337 
00338 /** ============================================================================
00339  *  @func   MPLIST_removeElement
00340  *
00341  *  @brief  Removes (unlinks) the given element from the list, if the list is
00342  *          not empty.  Does not free the list element.
00343  *
00344  *  @param mplistHandle
00345  *              Handle for list operations.
00346  *  @param element
00347  *              Pointer to element in list to remove.
00348  *
00349  *  @return DSP_SOK
00350  *              Operation successfully completed.
00351  *          DSP_EINVALIDARG
00352  *              Invalid arguments.
00353  *          DSP_EFAIL
00354  *              General Failure.
00355  *
00356  *  @pre    mplistHandle must be a valid pointer.
00357  *          element be a valid pointer.
00358  *          MPLIST_open has been successful.
00359  *
00360  *  @post   None
00361  *
00362  *  @see    MPLIST_insertBefore, MPLIST_create, MPLIST_putTail
00363  *  ============================================================================
00364  */
00365 EXPORT_API
00366 DSP_STATUS
00367 MPLIST_removeElement (IN MPLIST_Handle mplistHandle,
00368                       IN MPLIST_Elem   element) ;
00369 
00370 
00371 /** ============================================================================
00372  *  @func   MPLIST_first
00373  *
00374  *  @brief  Returns a pointer to the first element of the list, or NULL if
00375  *          the list is empty.
00376  *
00377  *  @param mplistHandle
00378  *              Handle for list operations.
00379  *  @param element
00380  *              OUT parameter for holding the first element.
00381  *
00382  *  @return DSP_SOK
00383  *              Operation successfully completed.
00384  *          DSP_EINVALIDARG
00385  *              Invalid arguments.
00386  *          DSP_EFAIL
00387  *              General Failure.
00388  *
00389  *  @pre    mplistHandle must be a valid pointer.
00390  *          element be a valid pointer.
00391  *          MPLIST_open has been successful.
00392  *
00393  *  @post   None
00394  *
00395  *  @see    MPLIST_create, MPLIST_puttail, MPLIST_insertbefore
00396  *  ============================================================================
00397  */
00398 EXPORT_API
00399 DSP_STATUS
00400 MPLIST_first (IN MPLIST_Handle   mplistHandle,
00401               OUT MPLIST_Elem *  element) ;
00402 
00403 
00404 /** ============================================================================
00405  *  @func   MPLIST_next
00406  *
00407  *  @brief  Returns a pointer to the next element of the list, or NULL if
00408  *          the next element is the head of the list or the list is empty.
00409  *
00410  *  @param mplistHandle
00411  *              Handle for list operations.
00412  *  @param currentElement
00413  *              Pointer to element in list to remove.
00414  *  @param nextElement
00415  *              OUT parameter to hold the next element.
00416  *
00417  *  @return DSP_SOK
00418  *              Operation successfully completed.
00419  *          DSP_EINVALIDARG
00420  *              Invalid arguments.
00421  *          DSP_EFAIL
00422  *              General Failure.
00423  *
00424  *  @pre    mplistHandle must be a valid pointer.
00425  *          currentElement be a valid pointer.
00426  *          nextElement be a valid pointer.
00427  *          MPLIST_open has been successful.
00428  *
00429  *  @post   None
00430  *
00431  *  @see    MPLIST_insertBefore, MPLIST_putTail
00432  *  ============================================================================
00433  */
00434 EXPORT_API
00435 DSP_STATUS
00436 MPLIST_next (IN  MPLIST_Handle   mplistHandle,
00437              IN  MPLIST_Elem     currentElement,
00438              OUT MPLIST_Elem *   nextElement) ;
00439 
00440 
00441 /** ============================================================================
00442  *  @func   MPLIST_getHead
00443  *
00444  *  @brief  Pops the head off the list and returns a pointer to it.
00445  *          If the list is empty, returns NULL.
00446  *
00447  *  @param mplistHandle
00448  *              Handle for list operations.
00449  *  @param element
00450  *              OUT Parameter to hold the head element.
00451  *
00452  *  @return DSP_SOK
00453  *              Operation successfully completed.
00454  *          DSP_EINVALIDARG
00455  *              Invalid arguments.
00456  *          DSP_ENOTFOUND
00457  *              Information about specified POOL buffer was not available.
00458  *          DSP_EFAIL
00459  *              General Failure.
00460  *
00461  *  @pre    mplistHandle must be a valid pointer.
00462  *          element be a valid pointer.
00463  *          MPLIST_open has been successful.
00464  *
00465  *  @post   None
00466  *
00467  *  @see    MPLIST_puttail, MPLIST_insertbefore
00468  *  ============================================================================
00469  */
00470 EXPORT_API
00471 DSP_STATUS
00472 MPLIST_getHead (IN MPLIST_Handle mplistHandle, OUT MPLIST_Elem * element) ;
00473 
00474 
00475 #if defined (__cplusplus)
00476 }
00477 #endif /* defined (__cplusplus) */
00478 
00479 
00480 #endif /* !defined (MPLIST_H) */
00481 

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