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