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

dsp/inc/mplist.h

Go to the documentation of this file.
00001 /** ============================================================================
00002  *  @file   mplist.h
00003  *
00004  *  @path   $(DSPLINK)/dsp/inc/
00005  *
00006  *  @brief  Declarations of MPLIST management control structures and definitions
00007  *          of inline MPLIST management functions for lists present in shared
00008  *          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 name
00074  *              Name of the list to be created.
00075  *  @param mpcsObj
00076  *              Pointer to the shared MPLIST object.
00077  *              If memory for the MPLIST object is provided by the user, the
00078  *              MPLIST object handle is not NULL.
00079  *              Otherwise, if the memory is to be allocated by the MPLIST
00080  *              component, the MPLIST object handle can be specified as
00081  *              NULL.
00082  *  @param attrs
00083  *              Attributes of the list to be created.
00084  *
00085  *  @return SYS_OK
00086  *              Operation successfully completed.
00087  *          SYS_EINVAL
00088  *              Invalid Parameters.
00089  *          SYS_EALLOC
00090  *              Operation failed due to a memory error.
00091  *          SYS_EBUSY
00092  *              The specified MPLIST name already exists.
00093  *          SYS_ENOTFOUND
00094  *              All MPLIST entries are currently in use.
00095  *          SYS_EDEAD
00096  *              The MPLIST component has not been initialized.
00097  *
00098  *  @pre    name must be a valid pointer.
00099  *          attr must be a valid pointer.
00100  *
00101  *  @post   None
00102  *
00103  *  @see    None
00104  *  ============================================================================
00105  */
00106 Int
00107 MPLIST_create (IN     Uint16         procId,
00108                IN     Char *         name,
00109                IN     MPLIST_List  * mplistObj,
00110                IN     MPLIST_Attrs * attrs) ;
00111 
00112 
00113 /** ============================================================================
00114  *  @func   MPLIST_delete
00115  *
00116  *  @brief  Removes a list by freeing its control structure's memory space.
00117  *          Must ONLY be used for empty lists, because it does not walk the
00118  *          chain of list elements.  Calling this function on a non-empty list
00119  *          will cause a memory leak.
00120  *
00121  *  @param procId
00122  *              Processor id of the processor making this delete call.
00123  *  @param name
00124  *              Name of the list to be deleted.
00125  *
00126  *  @return SYS_OK
00127  *              Operation successfully completed.
00128  *          SYS_EINVAL
00129  *              Invalid Parameters.
00130  *          SYS_EFREE
00131  *              Operation failed due to a memory error.
00132  *          SYS_ENOTFOUND
00133  *              Specified MPLIST object name does not exist.
00134  *          SYS_EDEAD
00135  *              The MPLIST component has not been initialized.
00136  *
00137  *  @pre    name must be a valid pointer.
00138  *
00139  *  @post   None
00140  *
00141  *  @see    MPLIST_create
00142  *  ============================================================================
00143  */
00144 Int
00145 MPLIST_delete (IN  Uint16    procId,
00146                IN  Char *    name) ;
00147 
00148 
00149 /** ============================================================================
00150  *  @func   MPLIST_open
00151  *
00152  *  @brief  This function opens an MPLIST object specified by its name and gets
00153  *          a handle to the object.
00154  *          Every process that needs to use the MPLIST object must get a handle
00155  *          to the object by calling this API.
00156  *
00157  *  @param procId
00158  *              Processor id of the processor making this open call.
00159  *  @param name
00160  *              Name of the list to be opened.
00161  *  @param mplistHandle
00162  *              Handle of list which has to be opened.
00163  *
00164  *  @return SYS_SOK
00165  *              Operation successfully completed.
00166  *          SYS_EINVAL
00167  *              Invalid Parameters.
00168  *          SYS_EALLOC
00169  *              Operation failed due to a memory error.
00170  *          SYS_ENOTFOUND
00171  *              Specified MPLIST object name does not exist.
00172  *          SYS_EDEAD
00173  *              The MPLIST component has not been initialized.
00174  *
00175  *  @pre    mplistHandle must be a valid pointer .
00176  *          name must be a valid pointer.
00177  *
00178  *  @post   None
00179  *
00180  *  @see    MPLIST_close
00181  *  ============================================================================
00182  */
00183 Int
00184 MPLIST_open (IN     Uint16          procId,
00185              IN     Char *          name,
00186              OUT    MPLIST_Handle * mplistHandle) ;
00187 
00188 
00189 /** ============================================================================
00190  *  @func   MPLIST_close
00191  *
00192  *  @brief  This function closes an MPLIST instance.
00193  *
00194  *  @param mplistHandle
00195  *              Handle for list operations.
00196  *
00197  *  @return SYS_EOK
00198  *              Operation successfully completed.
00199  *          SYS_EFAIL
00200  *              General Failure.
00201  *          SYS_EFREE
00202  *              Operation failed due to a memory error.
00203  *          SYS_ENOTFOUND
00204  *              Specified MPLIST object name does not exist.
00205  *          SYS_EDEAD
00206  *              The MPLIST component has not been initialized.
00207  *
00208  *  @pre    mplistHandle must be a valid pointer.
00209  *
00210  *  @post   None
00211  *
00212  *  @see    MPLIST_open_
00213  *  ============================================================================
00214  */
00215 Int
00216 MPLIST_close (IN  MPLIST_Handle mplistHandle) ;
00217 
00218 /** ============================================================================
00219  *  @func   MPLIST_isEmpty
00220  *
00221  *  @brief  Check for an empty list.
00222  *
00223  *  @param mplistHandle
00224  *              List handle for list operations.
00225  *
00226  *  @return TRUE
00227  *              List is empty.
00228  *          FALSE
00229  *              List is not empty.
00230  *
00231  *  @pre    mplistHandle must be a valid pointer.
00232  *
00233  *  @post   None
00234  *
00235  *  @see    None
00236  *  ============================================================================
00237  */
00238 Bool
00239 MPLIST_isEmpty (IN  MPLIST_Handle mplistHandle) ;
00240 
00241 
00242 /** ============================================================================
00243  *  @func   MPLIST_insertBefore
00244  *
00245  *  @brief  Inserts the element before the existing element.
00246  *
00247  *  @param mplistHandle
00248  *              List handle for list operations.
00249  *  @param insertElement
00250  *              Pointer to element in list to insert.
00251  *  @param existingElement
00252  *              Pointer to existing list element.
00253  *
00254  *  @return SYS_OK
00255  *              Operation successfully completed.
00256  *          SYS_EINVAL
00257  *              Invalid Parameters.
00258  *
00259  *  @pre    mplistHandle must be a valid pointer.
00260  *          insertElement must be a valid pointer.
00261  *          existingElement must be a valid pointer.
00262  *
00263  *  @post   None
00264  *
00265  *  @see    MPLIST_create, MPLIST_putTail
00266  *  ============================================================================
00267  */
00268 Int
00269 MPLIST_insertBefore (IN  MPLIST_Handle mplistHandle,
00270                      IN  MPLIST_Elem   insertElement,
00271                      IN  MPLIST_Elem   existingElement) ;
00272 
00273 
00274 /** ============================================================================
00275  *  @func   MPLIST_putTail
00276  *
00277  *  @brief  Adds the specified element to the tail of the list.
00278  *
00279  *  @param mplistHandle
00280  *              List handle for list operations.
00281  *  @param element
00282  *              Pointer to list element to be added.
00283  *
00284  *  @return SYS_OK
00285  *              Operation successfully completed.
00286  *          SYS_EINVAL
00287  *              Invalid Parameters.
00288  *
00289  *  @pre    mplistHandle must be a valid pointer.
00290  *          element must be a valid pointer.
00291  *
00292  *  @post   None
00293  *
00294  *  @see    MPLIST_insertBefore
00295  *  ============================================================================
00296  */
00297 Int
00298 MPLIST_putTail (IN  MPLIST_Handle mplistHandle, IN  MPLIST_Elem element) ;
00299 
00300 
00301 /** ============================================================================
00302  *  @func   MPLIST_removeElement
00303  *
00304  *  @brief  Removes (unlinks) the given element from the list, if the list is
00305  *          not empty.  Does not free the list element.
00306  *
00307  *  @param mplistHandle
00308  *              List handle for list operations.
00309  *  @param element
00310  *              Pointer to element in list to remove.
00311  *
00312  *  @return SYS_OK
00313  *              Operation successfully completed.
00314  *          SYS_EINVAL
00315  *              Invalid Parameters.
00316  *
00317  *  @pre    mplistHandle must be a valid pointer.
00318  *          Element must be a valid pointer.
00319  *
00320  *  @post   None
00321  *
00322  *  @see    MPLIST_insertBefore, MPLIST_create, MPLIST_putTail
00323  *  ============================================================================
00324  */
00325 Int
00326 MPLIST_removeElement (IN  MPLIST_Handle   mplistHandle,
00327                       IN  MPLIST_Elem     element) ;
00328 
00329 
00330 /** ============================================================================
00331  *  @func   MPLIST_first
00332  *
00333  *  @brief  Returns a pointer to the first element of the list, or NULL if
00334  *          the list is empty.
00335  *
00336  *  @param mplistHandle
00337  *              List handle for list operations.
00338  *  @param element
00339  *              parameter for holding the first element.
00340  *
00341  *  @return SYS_OK
00342  *              Operation successfully completed.
00343  *          SYS_EINVAL
00344  *              Invalid Parameters.
00345  *
00346  *  @pre    mplistHandle must be a valid pointer.
00347  *          Element must be a valid pointer.
00348  *
00349  *  @post   None
00350  *
00351  *  @see    MPLIST_create, MPLIST_putTail, MPLIST_insertBefore
00352  *  ============================================================================
00353  */
00354 Int
00355 MPLIST_first (IN  MPLIST_Handle mplistHandle,
00356               OUT MPLIST_Elem * element) ;
00357 
00358 
00359 /** ============================================================================
00360  *  @func   MPLIST_getHead
00361  *
00362  *  @brief  Pops the head off the list and returns a pointer to it.
00363  *          If the list is empty, returns NULL.
00364  *
00365  *  @param mplistHandle
00366  *              List handle for list operations.
00367  *  @param headElement
00368  *              Parameter to hold the head element.
00369  *
00370  *  @return SYS_OK
00371  *              Operation successfully completed.
00372  *          SYS_EINVAL
00373  *              Invalid Parameters.
00374  *
00375  *  @pre    List handle must be a valid pointer.
00376  *          Head element must be a valid pointer.
00377  *
00378  *  @post   None
00379  *
00380  *  @see    MPLIST_putTail, MPLIST_insertBefore
00381  *  ============================================================================
00382  */
00383 Int
00384 MPLIST_getHead (IN  MPLIST_Handle  mplistHandle,
00385                 OUT MPLIST_Elem *  element) ;
00386 
00387 
00388 /** ============================================================================
00389  *  @func   MPLIST_next
00390  *
00391  *  @brief  Returns a pointer to the next element of the list, or NULL if
00392  *          the next element is the head of the list or the list is empty.
00393  *
00394  *  @param mplistHandle
00395  *              List handle for list operations.
00396  *  @param currentElement
00397  *              Pointer to element in list to remove.
00398  *  @param nextElement
00399  *              Pointer to next element.
00400  *
00401  *  @return SYS_OK
00402  *              Operation successfully completed.
00403  *          SYS_EINVAL
00404  *              Invalid Parameters.
00405  *
00406  *  @pre    List handle must be a valid pointer.
00407  *          currentElement must be a valid pointer.
00408  *          nextElement must be a valid pointer.
00409  *
00410  *  @post   None
00411  *
00412  *  @see    MPLIST_insertBefore, MPLIST_putTail
00413  *  ============================================================================
00414  */
00415 Int
00416 MPLIST_next (IN  MPLIST_Handle   mplistHandle,
00417              IN  MPLIST_Elem     currentElement,
00418              OUT MPLIST_Elem *   nextElement) ;
00419 
00420 
00421 #if defined (__cplusplus)
00422 }
00423 #endif /* defined (__cplusplus) */
00424 
00425 
00426 #endif /* !defined (MPLIST_H) */
00427 

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