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