00001 /** ============================================================================ 00002 * @file ringio.h 00003 * 00004 * @path $(DSPLINK)/dsp/inc/ 00005 * 00006 * @brief Defines the interfaces and data structures for the API sub-component 00007 * RING IO. 00008 * 00009 * @ver 1.65.00.03 00010 * ============================================================================ 00011 * @copyright Copyright (C) 2002-2009, Texas Instruments Incorporated - 00012 * http://www.ti.com/ 00013 * 00014 * Redistribution and use in source and binary forms, with or without 00015 * modification, are permitted provided that the following conditions 00016 * are met: 00017 * 00018 * * Redistributions of source code must retain the above copyright 00019 * notice, this list of conditions and the following disclaimer. 00020 * 00021 * * Redistributions in binary form must reproduce the above copyright 00022 * notice, this list of conditions and the following disclaimer in the 00023 * documentation and/or other materials provided with the distribution. 00024 * 00025 * * Neither the name of Texas Instruments Incorporated nor the names of 00026 * its contributors may be used to endorse or promote products derived 00027 * from this software without specific prior written permission. 00028 * 00029 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00030 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 00031 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00032 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 00033 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00034 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00035 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 00036 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 00037 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 00038 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00039 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00040 * ============================================================================ 00041 */ 00042 00043 00044 #if !defined (RINGIO_H) 00045 #define RINGIO_H 00046 00047 00048 /* ----------------------------------- DSP/BIOS LINK Headers */ 00049 #include <dsplink.h> 00050 #include <ringiodefs.h> 00051 00052 00053 #if defined (__cplusplus) 00054 extern "C" { 00055 #endif /* defined (__cplusplus) */ 00056 00057 00058 /** ============================================================================ 00059 * @func RingIO_getValidSize 00060 * 00061 * @brief Returns the current valid data size 00062 * 00063 * @param handle 00064 * Handle to the RingIO Client. 00065 * 00066 * @return <current valid data size> 00067 * 00068 * @pre client must be a valid pointer 00069 * 00070 * @post None. 00071 * 00072 * @see None. 00073 * ============================================================================ 00074 */ 00075 Uint32 00076 RingIO_getValidSize (IN RingIO_Handle handle ); 00077 00078 /** ============================================================================ 00079 * @func RingIO_getEmptySize 00080 * 00081 * @brief Returns the current empty buffer size 00082 * 00083 * @param handle 00084 * Handle to the RingIO Client. 00085 * 00086 * @return <current empty buffer size> 00087 * 00088 * @pre client must be a valid pointer(i.e valid RingIO Handle) 00089 * 00090 * @post None. 00091 * 00092 * @see None. 00093 * ============================================================================ 00094 */ 00095 Uint32 00096 RingIO_getEmptySize (IN RingIO_Handle handle ); 00097 /** ============================================================================ 00098 * @func RingIO_getValidAttrSize 00099 * 00100 * @brief Returns the current valid attribute size 00101 * 00102 * @param handle 00103 * Handle to the RingIO Client. 00104 * 00105 * @return <current valid attribute size> 00106 * 00107 * @pre client must be a valid pointer(i.e valid RingIO Handle) 00108 * 00109 * @post None. 00110 * 00111 * @see None. 00112 * ============================================================================ 00113 */ 00114 Uint32 00115 RingIO_getValidAttrSize (IN RingIO_Handle handle ); 00116 00117 /** ============================================================================ 00118 * @func RingIO_getEmptyAttrSize 00119 * 00120 * @brief Returns the current empty attribute buffer size 00121 * 00122 * @param handle 00123 * Handle to the RingIO Client. 00124 * 00125 * @return <current empty attribute buffer size> 00126 * 00127 * @pre client must be a valid pointer(i.e valid RingIO Handle) 00128 * 00129 * @post None. 00130 * 00131 * @see None. 00132 * ============================================================================ 00133 */ 00134 Uint32 00135 RingIO_getEmptyAttrSize (IN RingIO_Handle handle ); 00136 00137 /** ============================================================================ 00138 * @func RingIO_getAcquiredOffset 00139 * 00140 * @brief Returns the current acquire offset for the client 00141 * 00142 * @param handle 00143 * Handle to the RingIO Client. 00144 * 00145 * @return <client's current acquired offset> 00146 * 00147 * @pre client must be a valid pointer(i.e valid RingIO Handle) 00148 * 00149 * @post None. 00150 * 00151 * @see None. 00152 * ============================================================================ 00153 */ 00154 #define RingIO_getAcquiredOffset(client) \ 00155 (((RingIO_Client *) client)->acqStart) 00156 00157 /** ============================================================================ 00158 * @func RingIO_getAcquiredSize 00159 * 00160 * @brief Returns the size of buffer currently acquired 00161 * 00162 * @param handle 00163 * Handle to the RingIO Client. 00164 * 00165 * @return <current acquired buffer size> 00166 * 00167 * @pre client must be a valid pointer(i.e valid RingIO Handle) 00168 * 00169 * @post None. 00170 * 00171 * @see None. 00172 * ============================================================================ 00173 */ 00174 #define RingIO_getAcquiredSize(client) \ 00175 (((RingIO_Client *) client)->acqSize) 00176 00177 /** ============================================================================ 00178 * @func RingIO_getWatermark 00179 * 00180 * @brief Returns the current watermark level specified by the client 00181 * 00182 * @param handle 00183 * Handle to the RingIO Client. 00184 * 00185 * @return <current watermark level set by the client> 00186 * 00187 * @pre client must be a valid pointer(i.e valid RingIO Handle) 00188 * 00189 * @post None. 00190 * 00191 * @see None. 00192 * ============================================================================ 00193 */ 00194 #define RingIO_getWatermark(client) \ 00195 (((RingIO_Client *) client)->notifyWaterMark) 00196 00197 00198 /** ============================================================================ 00199 * @func RingIO_create 00200 * 00201 * @brief This function creates a RingIO instance in Shared memory using the 00202 * creation params specified. 00203 * 00204 * @param procId 00205 * Processor Identifier (Not available in legacy suuport) 00206 * @param name 00207 * Unique name identifying the RingIO instance. 00208 * @param attrs 00209 * Pointer to the RingIO creation attributes. 00210 * 00211 * @return RINGIO_SUCCESS 00212 * Operation successfully completed. 00213 * RINGIO_EFAILURE 00214 * General failure. 00215 * 00216 * @pre None. 00217 * 00218 * @post None. 00219 * 00220 * @see None. 00221 * ============================================================================ 00222 */ 00223 Int 00224 #if defined (DSPLINK_LEGACY_SUPPORT) 00225 RingIO_create (IN Char * name, IN RingIO_Attrs * attrs) ; 00226 #else 00227 RingIO_create (IN Uint32 procId, IN Char * name, IN RingIO_Attrs * attrs) ; 00228 #endif /* if defined (DSPLINK_LEGACY_SUPPORT) */ 00229 00230 00231 /** ============================================================================ 00232 * @func RingIO_delete 00233 * 00234 * @brief This function deletes a RingIO channel. 00235 * 00236 * @param procId 00237 * Processor Identifier (Not available in legacy suuport) 00238 * @param name 00239 * Name of the RingIO channel to be deleted. 00240 * 00241 * @return RINGIO_SUCCESS 00242 * Operation successfully completed. 00243 * RINGIO_EFAILURE 00244 * General failure. 00245 * 00246 * @pre None. 00247 * 00248 * @post None. 00249 * 00250 * @see None. 00251 * ============================================================================ 00252 */ 00253 Int 00254 #if defined (DSPLINK_LEGACY_SUPPORT) 00255 RingIO_delete (IN Char * name) ; 00256 #else 00257 RingIO_delete (IN Uint32 procId, IN Char * name) ; 00258 #endif /* if defined (DSPLINK_LEGACY_SUPPORT) */ 00259 00260 00261 /** ============================================================================ 00262 * @func RingIO_open 00263 * 00264 * @brief This function opens a RingIO. 00265 * This function is used to open an RingIO Channel either for reading 00266 * or writing. Only one reader and one writer can be opened on a RingIO 00267 * 00268 * @param name 00269 * Name of the RingIO channel to be opened. 00270 * @param openMode 00271 * Mode with which the RingIO channel is to be opened 00272 * (Reader/Writer). 00273 * @param flags 00274 * Cache usage and other notifification flags. 00275 * 00276 * @return Handle to the RingIO client structure. 00277 * Operation successfully completed. 00278 * NULL 00279 * General failure, name not found. 00280 * 00281 * @pre None. 00282 * 00283 * @post None. 00284 * 00285 * @see None. 00286 * ============================================================================ 00287 */ 00288 RingIO_Handle 00289 RingIO_open (IN Char * name, IN RingIO_OpenMode openMode, IN Uint32 flags) ; 00290 00291 00292 /** ============================================================================ 00293 * @func RingIO_close 00294 * 00295 * @brief This function closes a RingIO instance. 00296 * 00297 * @param handle 00298 * Handle to the RingIO Client. 00299 * 00300 * @return RINGIO_SUCCESS 00301 * Operation successfully completed. 00302 * RINGIO_EFAILURE 00303 * General failure. 00304 * 00305 * @pre None. 00306 * 00307 * @post None. 00308 * 00309 * @see None. 00310 * ============================================================================ 00311 */ 00312 Int 00313 RingIO_close (IN RingIO_Handle handle) ; 00314 00315 00316 /** ============================================================================ 00317 * @func RingIO_acquire 00318 * 00319 * @brief This function acquire a data buffer from RingIO. 00320 * This function is used to open an RingIO Channel either for reading 00321 * or writing. Only one reader and one writer can be opened on a RingIO 00322 * Channel. 00323 * 00324 * @param handle 00325 * Handle to the RingIO Client. 00326 * @param pData 00327 * Location to store the pointer to the acquired data buffer. 00328 * @param pSize 00329 * Pointer to the size of data buffer acquired. Holds the size of 00330 * buffer to be acquired. Returns the size of buffer actually 00331 * acquired. 00332 * 00333 * @return RINGIO_SUCCESS 00334 * Operation successfully completed. 00335 * RINGIO_SPENDINGATTRIBUTE 00336 * No data buffer could be acquired because an attribute was 00337 * present at the current read offset. 00338 * RINGIO_EBUFWRAP 00339 * Requested size of data buffer could not be returned. A smaller 00340 * sized buffer may have been returned, if available. 00341 * RINGIO_ENOTCONTIGUOUSDATA 00342 * Valid data is present in the buffer but is not contiguous as 00343 * data has been copied from top to footer area. 00344 * RINGIO_EFAILURE 00345 * General failure. 00346 * 00347 * @pre None. 00348 * 00349 * @post None. 00350 * 00351 * @see None. 00352 * ============================================================================ 00353 */ 00354 Int 00355 RingIO_acquire (IN RingIO_Handle handle, 00356 OUT RingIO_BufPtr * pData, 00357 IN OUT Uint32 * pSize) ; 00358 00359 00360 /** ============================================================================ 00361 * @func RingIO_release 00362 * 00363 * @brief This function releases a data buffer to RingIO. 00364 * This function releases an acquired buffer or part of it. 00365 * 00366 * @param handle 00367 * Handle to the RingIO Client. 00368 * @param size 00369 * Size of data buffer to be released. 00370 * 00371 * @return RINGIO_SUCCESS 00372 * Operation successfully completed. 00373 * RINGIO_EFAILURE 00374 * General failure. 00375 * 00376 * @pre None. 00377 * 00378 * @post None. 00379 * 00380 * @see None. 00381 * ============================================================================ 00382 */ 00383 Int 00384 RingIO_release (IN RingIO_Handle handle, IN Uint32 size) ; 00385 00386 00387 /** ============================================================================ 00388 * @func RingIO_cancel 00389 * 00390 * @brief Cancel the previous acquire. 00391 * 00392 * @param handle 00393 * Handle to the RingIO Client. 00394 * 00395 * @return RINGIO_SUCCESS 00396 * Operation successfully completed. 00397 * RINGIO_EFAILURE 00398 * General failure. 00399 * 00400 * @pre None. 00401 * 00402 * @post None. 00403 * 00404 * @see None. 00405 * ============================================================================ 00406 */ 00407 Int 00408 RingIO_cancel (IN RingIO_Handle handle) ; 00409 00410 /** ============================================================================ 00411 * @func RingIO_getvAttribute 00412 * 00413 * @brief This function gets an attribute with a variable-sized payload from 00414 * the attribute buffer. 00415 * If an attribute is present, the attribute type, the optional 00416 * parameter, a pointer to the optional payload and the payload size 00417 * are returned. 00418 * 00419 * @param handle 00420 * Handle to the RingIO Client. 00421 * @param type 00422 * Location to receive the user-defined type of attribute. 00423 * @param param 00424 * Location to receive an optional parameter which depends on the 00425 * attribute type. 00426 * @param vptr 00427 * Pointer to buffer to receive the optional payload. 00428 * @param pSize 00429 * Location with the size of the variable attribute. On return, 00430 * this stores the actual size of the payload. 00431 * 00432 * @return RINGIO_SUCCESS 00433 * Operation successfully completed. 00434 * RINGIO_SPENDINGATTRIBUTE 00435 * Additional attributes are present at the current read offset. 00436 * RINGIO_EVARIABLEATTRIBUTE 00437 * No buffer has been provided to receive the variable attribute 00438 * payload. 00439 * RINGIO_EPENDINGDATA 00440 * More data must be read before reading the attribute. 00441 * RINGIO_EFAILURE 00442 * No valid attributes are present, or general failure. 00443 * 00444 * @pre None. 00445 * 00446 * @post None. 00447 * 00448 * @see RingIO_getAttribute () 00449 * ============================================================================ 00450 */ 00451 Int 00452 RingIO_getvAttribute (IN RingIO_Handle handle, 00453 OUT Uint16 * type, 00454 OUT Uint32 * param, 00455 IN RingIO_BufPtr vptr, 00456 IN OUT Uint32 * pSize) ; 00457 00458 00459 /** ============================================================================ 00460 * @func RingIO_setvAttribute 00461 * 00462 * @brief This function sets an attribute with a variable sized payload at the 00463 * offset provided in the acquired data buffer. 00464 * If the offset is not in the range of the acquired data buffer, the 00465 * attribute is not set, and an error is returned. One exception to 00466 * this rule is when no data buffer has been acquired. In this case an 00467 * attribute is set at the next data buffer offset that can be acquired 00468 * 00469 * @param handle 00470 * Handle to the RingIO Client. 00471 * @param offset 00472 * Offset in the acquired data buffer to which the attribute 00473 * corresponds 00474 * @param type 00475 * User-defined type of attribute. 00476 * @param param 00477 * Optional parameter which depends on the attribute type. 00478 * @param pdata 00479 * Pointer to attribute payload buffer. 00480 * @param size 00481 * Size of the attribute payload. 00482 * 00483 * @return RINGIO_SUCCESS 00484 * Operation successfully completed. 00485 * RINGIO_EFAILURE 00486 * General failure. 00487 * RINGIO_EWRONGSTATE 00488 * Failure to set attribute when data buffer is full with valid 00489 * data and buffer is wrapped around. 00490 * 00491 * @pre None. 00492 * 00493 * @post None. 00494 * 00495 * @see RingIO_setAttribute (), RingIO_getvAttribute () 00496 * ============================================================================ 00497 */ 00498 Int 00499 RingIO_setvAttribute (IN RingIO_Handle handle, 00500 IN Uint32 offset, 00501 IN Uint16 type, 00502 IN Uint32 param, 00503 IN RingIO_BufPtr pdata, 00504 IN Uint32 size) ; 00505 00506 00507 /** ============================================================================ 00508 * @func RingIO_getAttribute 00509 * 00510 * @brief This function gets a fixed-size attribute from the attribute buffer. 00511 * If an attribute is present, the attribute type and a related 00512 * parameter are returned. 00513 * 00514 * @param handle 00515 * Handle to the RingIO Client. 00516 * @param type 00517 * Location to receive the user-defined type of attribute. 00518 * @param param 00519 * Location to receive an optional parameter which depends on the 00520 * attribute type. 00521 * 00522 * @return RINGIO_SUCCESS 00523 * Operation successfully completed. 00524 * RINGIO_SPENDINGATTRIBUTE 00525 * Additional attributes are present at the current read offset. 00526 * RINGIO_EVARIABLEATTRIBUTE 00527 * A variable atrtibute exists. The application must call 00528 * RingIO_getvAttribute () to get the variable attribute. 00529 * RINGIO_EPENDINGDATA 00530 * More data must be read before reading the attribute. 00531 * RINGIO_EFAILURE 00532 * No valid attributes are present, or general failure. 00533 * 00534 * @pre None. 00535 * 00536 * @post None. 00537 * 00538 * @see RingIO_getvAttribute () 00539 * ============================================================================ 00540 */ 00541 static 00542 inline 00543 Int 00544 RingIO_getAttribute (IN RingIO_Handle handle, 00545 OUT Uint16 * type, 00546 OUT Uint32 * param) 00547 { 00548 return (RingIO_getvAttribute (handle, type, param, NULL, NULL)) ; 00549 } 00550 00551 00552 /** ============================================================================ 00553 * @func RingIO_setAttribute 00554 * 00555 * @brief This function sets a fixed-size attribute at the offset provided in 00556 * the acquired data buffer. 00557 * If the offset is not in the range of the acquired data buffer, the 00558 * attribute is not set, and an error is returned. One exception to 00559 * this rule is when no data buffer has been acquired. In this case an 00560 * attribute is set at the next data buffer offset that can be acquired 00561 * 00562 * @param handle 00563 * Handle to the RingIO Client. 00564 * @param offset 00565 * Offset in the acquired data buffer to which the attribute 00566 * corresponds 00567 * @param type 00568 * User-defined type of attribute. 00569 * @param param 00570 * Optional parameter which depends on the attribute type. 00571 * 00572 * @return RINGIO_SUCCESS 00573 * Operation successfully completed. 00574 * RINGIO_EFAILURE 00575 * General failure. 00576 * 00577 * @pre None. 00578 * 00579 * @post None. 00580 * 00581 * @see RingIO_setvAttribute (), RingIO_getAttribute () 00582 * ============================================================================ 00583 */ 00584 static 00585 inline 00586 Int 00587 RingIO_setAttribute (IN RingIO_Handle handle, 00588 IN Uint32 offset, 00589 IN Uint16 type, 00590 IN Uint32 param) 00591 { 00592 return RingIO_setvAttribute (handle, offset, type, param, NULL, 0) ; 00593 } 00594 00595 00596 /** ============================================================================ 00597 * @func RingIO_flush 00598 * 00599 * @brief This function flushes the data buffer. 00600 * This function is used to flush the data from the RingIO. 00601 * Behavior of this function depends on the value of hardFlush argument 00602 * When hardFlush is false: 00603 * If function is called for the writer, all the valid data in buffer 00604 * after the first attribute location will be discarded. In case there 00605 * are no attributes, no data will be cleared from the buffer. Note 00606 * that this does not include the data that has been already acquired 00607 * by the reader. Note that the attribute will also be cleared from the 00608 * attribute buffer. 00609 * For the reader, all the data till the next attribute location will 00610 * be discarded. And if there is no attribute in the buffer, all valid 00611 * data will get discarded. Note that the attribute will remain the 00612 * attribute buffer. This is different from the behavior mentioned for 00613 * the writer. 00614 * When hardFlush is true: 00615 * If function is called from the writer, all committed data and 00616 * attributes that is not acquired by reader are removed from 00617 * the RingIO instance. The writer pointer is moved to point to 00618 * reader's head pointer 00619 * If function is called from the reader, all data and attributes 00620 * that can be subsequently acquired from the reader are removed. 00621 * 00622 * @param handle 00623 * Handle to the RingIO Client. 00624 * @param hardFlush 00625 * Mode in which the flush operation discards committed data 00626 * and attributes 00627 * @param type 00628 * Location to receive the User-defined type of attribute. 00629 * @param param 00630 * Location to receive an optional parameter which depends on the 00631 * attribute type. 00632 * @param bytesFlushed 00633 * Location to recieve the size of the buffer flushed. 00634 * 00635 * @return RINGIO_SUCCESS 00636 * Operation successfully completed. 00637 * RINGIO_EFAILURE 00638 * General failure. 00639 * 00640 * @pre None. 00641 * 00642 * @post None. 00643 * 00644 * @see None. 00645 * ============================================================================ 00646 */ 00647 Int 00648 RingIO_flush (IN RingIO_Handle handle, 00649 IN Bool hardFlush, 00650 OUT Uint16 * type, 00651 OUT Uint32 * param, 00652 OUT Uint32 * bytesFlushed) ; 00653 00654 00655 /** ============================================================================ 00656 * @func RingIO_setNotifier 00657 * 00658 * @brief This function sets Notification parameters for the RingIO Client. 00659 * Both the reader and writer can set their notification mechanism 00660 * using this function 00661 * 00662 * @param handle 00663 * Handle to the RingIO client. 00664 * @param notifyType 00665 * Type of notification. 00666 * @param notifyWatermark 00667 * Watermark for notification 00668 * @param notifyFunc 00669 * Function to call when notification is required 00670 * @param pNotifyParam 00671 * Pointer to the notification parameter. The type of the pointer 00672 * and its size depends on the notification function 00673 * 00674 * @return RINGIO_SUCCESS 00675 * Operation successfully completed. 00676 * RINGIO_EFAILURE 00677 * General failure. 00678 * 00679 * @pre RingIO_open for both reader and writer has been successful. 00680 * No DSP/BIOS Link API should be called from a callback function 00681 * registered through the RingIO or NOTIFY module. On DSP-side or 00682 * on operating systems such as PrOS, the callback functions are 00683 * run from ISR context and must not perform any operations that 00684 * may take a lock or block, which is done by most DSPLink APIs. 00685 * Minimum functionality must be used in the callback functions, 00686 * most often limited to posting a semaphore on which application 00687 * is waiting, posting SWI etc. 00688 * 00689 * @post None. 00690 * 00691 * @see RingIO_NotifyType, RingIO_NotifyFunc, RingIO_NotifyParam 00692 * ============================================================================ 00693 */ 00694 Int 00695 RingIO_setNotifier (IN RingIO_Handle handle, 00696 IN RingIO_NotifyType notifyType, 00697 IN Uint32 notifyWatermark, 00698 IN RingIO_NotifyFunc notifyFunc, 00699 IN RingIO_NotifyParam pNotifyParam) ; 00700 00701 00702 /** ============================================================================ 00703 * @func RingIO_sendNotify 00704 * 00705 * @brief Send a notification to the other client manually 00706 * 00707 * @param handle 00708 * Handle to the RingIO Client. 00709 * arg msg 00710 * Message to be sent along with notification. 00711 * 00712 * @return RINGIO_SUCCESS 00713 * Operation successfully completed. 00714 * RINGIO_EFAILURE 00715 * General failure. 00716 * 00717 * @pre None. 00718 * 00719 * @post None. 00720 * 00721 * @see None. 00722 * ============================================================================ 00723 */ 00724 Int 00725 RingIO_sendNotify (IN RingIO_Handle handle, 00726 IN RingIO_NotifyMsg msg) ; 00727 00728 00729 00730 #if defined (__cplusplus) 00731 } 00732 #endif /* defined (__cplusplus) */ 00733 00734 00735 #endif /* !defined (RINGIO_H) */