00001 /** ============================================================================ 00002 * @file ringio.h 00003 * 00004 * @path $(DSPLINK)/gpp/inc/usr/ 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 */ 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(i.e valid RingIO Handle). 00069 * 00070 * @post None. 00071 * 00072 * @see None. 00073 * ============================================================================ 00074 */ 00075 EXPORT_API 00076 Uint32 00077 RingIO_getValidSize (IN RingIO_Handle handle ); 00078 00079 /** ============================================================================ 00080 * @func RingIO_getEmptySize 00081 * 00082 * @brief Returns the current empty buffer size 00083 * 00084 * @param handle 00085 * Handle to the RingIO Client. 00086 * 00087 * @return <current empty buffer size> 00088 * 00089 * @pre client must be a valid pointer(i.e valid RingIO Handle). 00090 * 00091 * @post None. 00092 * 00093 * @see None. 00094 * ============================================================================ 00095 */ 00096 EXPORT_API 00097 Uint32 00098 RingIO_getEmptySize (IN RingIO_Handle handle ); 00099 00100 /** ============================================================================ 00101 * @func RingIO_getValidAttrSize 00102 * 00103 * @brief Returns the current valid attribute size 00104 * 00105 * @param handle 00106 * Handle to the RingIO Client. 00107 * 00108 * @return <current valid attribute size> 00109 * 00110 * @pre client must be a valid pointer(i.e valid RingIO Handle). 00111 * 00112 * @post None. 00113 * 00114 * @see None. 00115 * ============================================================================ 00116 */ 00117 EXPORT_API 00118 Uint32 00119 RingIO_getValidAttrSize (IN RingIO_Handle handle ); 00120 00121 /** ============================================================================ 00122 * @func RingIO_getEmptyAttrSize 00123 * 00124 * @brief Returns the current empty attribute buffer size 00125 * 00126 * @param handle 00127 * Handle to the RingIO Client. 00128 * 00129 * @return <current empty attribute buffer size> 00130 * 00131 * @pre client must be a valid pointer(i.e valid RingIO Handle). 00132 * 00133 * @post None. 00134 * 00135 * @see None. 00136 * ============================================================================ 00137 */ 00138 EXPORT_API 00139 Uint32 00140 RingIO_getEmptyAttrSize (IN RingIO_Handle handle ); 00141 00142 /** ============================================================================ 00143 * @func RingIO_getAcquiredOffset 00144 * 00145 * @brief Returns the current acquire offset for the client 00146 * 00147 * @param handle 00148 * Handle to the RingIO Client. 00149 * 00150 * @return <client's current acquired offset> 00151 * 00152 * @pre client must be a valid pointer(i.e valid RingIO Handle). 00153 * 00154 * @post None. 00155 * 00156 * @see None. 00157 * ============================================================================ 00158 */ 00159 #define RingIO_getAcquiredOffset(client) \ 00160 (((RingIO_Client *) client)->acqStart) 00161 00162 /** ============================================================================ 00163 * @func RingIO_getAcquiredSize 00164 * 00165 * @brief Returns the size of buffer currently acquired 00166 * 00167 * @param handle 00168 * Handle to the RingIO Client. 00169 * 00170 * @return <current acquired buffer size> 00171 * 00172 * @pre client must be a valid pointer(i.e valid RingIO Handle). 00173 * 00174 * @post None. 00175 * 00176 * @see None. 00177 * ============================================================================ 00178 */ 00179 #define RingIO_getAcquiredSize(client) \ 00180 (((RingIO_Client *) client)->acqSize) 00181 00182 /** ============================================================================ 00183 * @func RingIO_getWatermark 00184 * 00185 * @brief Returns the current watermark level specified by the client 00186 * 00187 * @param handle 00188 * Handle to the RingIO Client. 00189 * 00190 * @return <current watermark level set by the client> 00191 * 00192 * @pre client must be a valid pointer(i.e valid RingIO Handle) 00193 * 00194 * @post None. 00195 * 00196 * @see None. 00197 * ============================================================================ 00198 */ 00199 #define RingIO_getWatermark(client) \ 00200 (((RingIO_Client *) client)->notifyWaterMark) 00201 00202 00203 /** ============================================================================ 00204 * @deprecated RingIO_init 00205 * 00206 * @brief This function initializes the RingIO component. 00207 * This function has been deprecated and is provided for backward 00208 * compatibility. 00209 * 00210 * @param procId 00211 * Processor Id 00212 * 00213 * @return RINGIO_SUCCESS 00214 * Operation successfully completed. 00215 * 00216 * @pre None. 00217 * 00218 * @post None. 00219 * 00220 * @see None. 00221 * ============================================================================ 00222 */ 00223 #define RingIO_init(procId) RINGIO_SUCCESS 00224 00225 00226 /** ============================================================================ 00227 * @deprecated RingIO_exit 00228 * 00229 * @brief This function finalizes the RingIO component. 00230 * This function has been deprecated and is provided for backward 00231 * compatibility. 00232 * 00233 * @param procId 00234 * Processor Id 00235 * 00236 * @return RINGIO_SUCCESS 00237 * Operation successfully completed. 00238 * 00239 * @pre None. 00240 * 00241 * @post None. 00242 * 00243 * @see None. 00244 * ============================================================================ 00245 */ 00246 #define RingIO_exit(procId) RINGIO_SUCCESS 00247 00248 00249 /** ============================================================================ 00250 * @func RingIO_create 00251 * 00252 * @brief This function creates a RingIO instance in Shared memory using the 00253 * creation params specified. 00254 * 00255 * @param procId 00256 * Processor Identifier (Not available in legacy suuport) 00257 * @param name 00258 * Unique name identifying the RingIO instance. 00259 * @param attrs 00260 * Pointer to the RingIO creation attributes. 00261 * 00262 * @return RINGIO_SUCCESS 00263 * Operation successfully completed. 00264 * RINGIO_EFAILURE 00265 * General failure. 00266 * DSP_EINVALIDARG 00267 * Invalid arguments. 00268 * DSP_EACCESSDENIED 00269 * The RINGIO component has not been initialized. 00270 * DSP_EMEMORY 00271 * Operation failed due to a memory error. 00272 * RINGIO_EALREADYEXISTS 00273 * The specified RINGIO name is already in use. 00274 * DSP_EFAIL 00275 * General failure. 00276 * 00277 * @pre RINGIO name must be valid. 00278 * RINGIO creation attributes must be a valid. 00279 * PROC_attach has been successful. 00280 * Application specific POOL configuration is complete. 00281 * 00282 * 00283 * @post None. 00284 * 00285 * @see RINGIO_delete. 00286 * ============================================================================ 00287 */ 00288 EXPORT_API 00289 DSP_STATUS 00290 #if defined (DSPLINK_LEGACY_SUPPORT) 00291 RingIO_create (IN Char8 * name, 00292 IN RingIO_Attrs * attrs) ; 00293 #else 00294 RingIO_create (IN ProcessorId procId, 00295 IN Char8 * name, 00296 IN RingIO_Attrs * attrs) ; 00297 #endif /* if defined (DSPLINK_LEGACY_SUPPORT) */ 00298 00299 00300 /** ============================================================================ 00301 * @func RingIO_delete 00302 * 00303 * @brief This function deletes a RingIO channel. 00304 * 00305 * @param procId 00306 * Processor Identifier (Not available in legacy suuport) 00307 * @param name 00308 * Name of the RingIO channel to be deleted. 00309 * 00310 * @return RINGIO_SUCCESS 00311 * Operation successfully completed. 00312 * RINGIO_EFAILURE 00313 * General failure. 00314 * DSP_EALREADYEXISTS 00315 * The specified RINGIO name is already in use. 00316 * DSP_EACCESSDENIED 00317 * The RINGIO component has not been initialized. 00318 * DSP_EFAIL 00319 * General failure. 00320 * 00321 * @pre RINGIO name must be valid. 00322 * All RINGIO operations are complete. 00323 * 00324 * @post None. 00325 * 00326 * @see RINGIO_create. 00327 * ============================================================================ 00328 */ 00329 EXPORT_API 00330 DSP_STATUS 00331 #if defined (DSPLINK_LEGACY_SUPPORT) 00332 RingIO_delete (IN Char8 * name) ; 00333 #else 00334 RingIO_delete (IN ProcessorId procId, IN Char8 * name) ; 00335 #endif /* if defined (DSPLINK_LEGACY_SUPPORT) */ 00336 00337 00338 /** ============================================================================ 00339 * @func RingIO_open 00340 * 00341 * @brief This function opens a RingIO channel. 00342 * This function is used to open an RingIO Channel either for reading 00343 * or writing. Only one reader and one writer can be opened on a RingIO 00344 * 00345 * @param name 00346 * Name of the RingIO channel to be opened. 00347 * @param openMode 00348 * Mode with which the RingIO channel is to be opened 00349 * (Reader/Writer). 00350 * @param flags 00351 * Cache usage and other notifification flags. 00352 * 00353 * @return Handle to the RingIO client structure. 00354 * Operation successfully completed. 00355 * NULL 00356 * General failure, name not found. 00357 * 00358 * @pre RINGIO name must be valid. 00359 * openMode must be either RINGIO_MODE_READ or RINGIO_MODE_WRITE 00360 * RINGIO_create has been successful. 00361 * 00362 * @post None. 00363 * 00364 * @see None. 00365 * ============================================================================ 00366 */ 00367 EXPORT_API 00368 RingIO_Handle 00369 RingIO_open (IN Char8 * name, 00370 IN RingIO_OpenMode openMode, 00371 IN Uint32 flags) ; 00372 00373 00374 /** ============================================================================ 00375 * @func RingIO_close 00376 * 00377 * @brief This function closes a RingIO instance. 00378 * 00379 * @param handle 00380 * Handle to the RingIO Client. 00381 * 00382 * @return RINGIO_SUCCESS 00383 * Operation successfully completed. 00384 * RINGIO_EFAILURE 00385 * General failure. 00386 * DSP_EINVALIDARG 00387 * Invalid arguments. 00388 * DSP_EACCESSDENIED 00389 * The RINGIO component has not been initialized. 00390 * DSP_EFAIL 00391 * General failure. 00392 * 00393 * @pre handle must be valid. 00394 * All RINGIO operations are complete. 00395 * 00396 * @post None. 00397 * 00398 * @see None. 00399 * ============================================================================ 00400 */ 00401 EXPORT_API 00402 DSP_STATUS 00403 RingIO_close (IN RingIO_Handle handle) ; 00404 00405 00406 /** ============================================================================ 00407 * @func RingIO_acquire 00408 * 00409 * @brief This function acquires a data buffer from RingIO for reading or 00410 * writing, depending on the mode in which the client (represented 00411 * by the handle) has been opened. 00412 * 00413 * @param handle 00414 * Handle to the RingIO Client. 00415 * @param dataBuf 00416 * Location to store the pointer to the acquired data buffer. 00417 * @param size 00418 * Pointer to the size of data buffer acquired. Holds the size of 00419 * buffer to be acquired. Returns the size of buffer actually 00420 * acquired. 00421 * 00422 * @return RINGIO_SUCCESS 00423 * Operation successfully completed. 00424 * RINGIO_SPENDINGATTRIBUTE 00425 * No data buffer could be acquired because an attribute was 00426 * present at the current read offset. 00427 * RINGIO_EBUFFULL 00428 * Requested size of data buffer could not be returned because 00429 * the total available size is less than requested size. A smaller 00430 * sized buffer may have been returned, if available. 00431 * RINGIO_EBUFWRAP 00432 * Requested size of data buffer could not be returned because the 00433 * available contiguous size till end of buffer is less than 00434 * requested size. A smaller sized buffer may have been returned, 00435 * if available. 00436 * RINGIO_EFAILURE 00437 * General failure. 00438 * RINGIO_ENOTCONTIGUOUSDATA 00439 * Valid data is present but is not contiguous because the data 00440 * has been acquired using the foot buffer. 00441 * 00442 * @pre handle must be valid. 00443 * dataBuf must be a valid pointer. 00444 * size must be a valid pointer. 00445 * RINGIO_open (for reading/writing) has been successful. 00446 * 00447 * 00448 * @post None. 00449 * 00450 * @see None. 00451 * ============================================================================ 00452 */ 00453 EXPORT_API 00454 DSP_STATUS 00455 RingIO_acquire (IN RingIO_Handle handle, 00456 OUT RingIO_BufPtr * dataBuf, 00457 IN OUT Uint32 * size) ; 00458 00459 00460 /** ============================================================================ 00461 * @func RingIO_release 00462 * 00463 * @brief This function releases a data buffer to RingIO. 00464 * This function releases an acquired buffer or part of it. 00465 * 00466 * @param handle 00467 * Handle to the RingIO Client. 00468 * @param size 00469 * Size of data buffer to be released. 00470 * 00471 * @return RINGIO_SUCCESS 00472 * Operation successfully completed. 00473 * RINGIO_EFAILURE 00474 * General failure. 00475 * DSP_EINVALIDARG 00476 * Invalid arguments. 00477 * 00478 * @pre RINGIO_acquire has been successful. 00479 * 00480 * @post None. 00481 * 00482 * @see None. 00483 * ============================================================================ 00484 */ 00485 EXPORT_API 00486 DSP_STATUS 00487 RingIO_release (IN RingIO_Handle handle, IN Uint32 size) ; 00488 00489 00490 /** ============================================================================ 00491 * @func RingIO_cancel 00492 * 00493 * @brief This function cancels any data buffers acquired by reader or writer. 00494 * In the case of writer, all attributes that are set since the first 00495 * acquire are removed. In the case of reader, all attributes that were 00496 * obtained since the first acquired are re-instated in the RingIO 00497 * instance. 00498 * 00499 * @param handle 00500 * Handle to the RingIO Client. 00501 * 00502 * @return RINGIO_SUCCESS 00503 * Operation successfully completed. 00504 * RINGIO_EFAILURE 00505 * General failure. 00506 * 00507 * @pre handle must be valid. 00508 * RINGIO_acquire has been successful. 00509 * 00510 * @post None. 00511 * 00512 * @see None. 00513 * ============================================================================ 00514 */ 00515 EXPORT_API 00516 DSP_STATUS 00517 RingIO_cancel (IN RingIO_Handle handle) ; 00518 00519 00520 /** ============================================================================ 00521 * @func RingIO_getvAttribute 00522 * 00523 * @brief This function gets an attribute with a variable-sized payload from 00524 * the attribute buffer. 00525 * If an attribute is present, the attribute type, the optional 00526 * parameter, a pointer to the optional payload and the payload size 00527 * are returned. 00528 * 00529 * @param handle 00530 * Handle to the RingIO Client. 00531 * @param type 00532 * Location to receive the user-defined type of attribute. 00533 * @param param 00534 * Location to receive an optional parameter which depends on the 00535 * attribute type. 00536 * @param vptr 00537 * Pointer to buffer to receive the optional payload. 00538 * @param size 00539 * Location with the size of the variable attribute. On return, 00540 * this stores the actual size of the payload. 00541 * 00542 * @return RINGIO_SUCCESS 00543 * Operation successfully completed. 00544 * RINGIO_SPENDINGATTRIBUTE 00545 * Additional attributes are present at the current read offset. 00546 * RINGIO_EVARIABLEATTRIBUTE 00547 * No buffer has been provided to receive the variable attribute 00548 * payload. 00549 * RINGIO_EPENDINGDATA 00550 * More data must be read before reading the attribute. 00551 * RINGIO_EFAILURE 00552 * No valid attributes are present, or general failure. 00553 * DSP_EINVALIDARG 00554 * Invalid arguments. 00555 * 00556 * @pre handle must be a valid pointer. 00557 * type must be valid. 00558 * param must be valid. 00559 * RingIO_setvAttribute has been successful. 00560 * 00561 * @post None. 00562 * 00563 * @see RingIO_getAttribute () 00564 * ============================================================================ 00565 */ 00566 EXPORT_API 00567 DSP_STATUS 00568 RingIO_getvAttribute (IN RingIO_Handle handle, 00569 OUT Uint16 * type, 00570 OUT Uint32 * param, 00571 IN RingIO_BufPtr vptr, 00572 IN OUT Uint32 * size) ; 00573 00574 00575 /** ============================================================================ 00576 * @func RingIO_setvAttribute 00577 * 00578 * @brief This function sets an attribute with a variable sized payload at the 00579 * offset provided in the acquired data buffer. 00580 * If the offset is not in the range of the acquired data buffer, the 00581 * attribute is not set, and an error is returned. One exception to 00582 * this rule is when no data buffer has been acquired. In this case an 00583 * attribute is set at the next data buffer offset that can be acquired 00584 * 00585 * @param handle 00586 * Handle to the RingIO Client. 00587 * @param offset 00588 * Offset in the acquired data buffer to which the attribute 00589 * corresponds 00590 * @param type 00591 * User-defined type of attribute. 00592 * @param param 00593 * Optional parameter which depends on the attribute type. 00594 * @param pdata 00595 * Pointer to attribute payload buffer. 00596 * @param size 00597 * Size of the attribute payload. 00598 * 00599 * @return RINGIO_SUCCESS 00600 * Operation successfully completed. 00601 * RINGIO_EFAILURE 00602 * General failure. 00603 * DSP_EINVALIDARG 00604 * Invalid arguments. 00605 * RINGIO_EWRONGSTATE 00606 * Failure to set attribute when data buffer is full with valid 00607 * data and buffer is wrapped around. 00608 * 00609 * @pre handle must be a valid pointer. 00610 * 00611 * @post None. 00612 * 00613 * @see RingIO_setAttribute (), RingIO_getvAttribute () 00614 * ============================================================================ 00615 */ 00616 EXPORT_API 00617 DSP_STATUS 00618 RingIO_setvAttribute (IN RingIO_Handle handle, 00619 IN Uint32 offset, 00620 IN Uint16 type, 00621 IN Uint32 param, 00622 IN RingIO_BufPtr pdata, 00623 IN Uint32 size) ; 00624 00625 00626 /** ============================================================================ 00627 * @func RingIO_getAttribute 00628 * 00629 * @brief This function gets a fixed-size attribute from the attribute buffer. 00630 * If an attribute is present, the attribute type and a related 00631 * parameter are returned. 00632 * 00633 * @param handle 00634 * Handle to the RingIO Client. 00635 * @param type 00636 * Location to receive the user-defined type of attribute. 00637 * @param param 00638 * Location to receive an optional parameter which depends on the 00639 * attribute type. 00640 * 00641 * @return RINGIO_SUCCESS 00642 * Operation successfully completed. 00643 * RINGIO_SPENDINGATTRIBUTE 00644 * Additional attributes are present at the current read offset. 00645 * RINGIO_EVARIABLEATTRIBUTE 00646 * A variable atrtibute exists. The application must call 00647 * RingIO_getvAttribute () to get the variable attribute. 00648 * RINGIO_EPENDINGDATA 00649 * More data must be read before reading the attribute. 00650 * RINGIO_EFAILURE 00651 * No valid attributes are present, or general failure. 00652 * 00653 * @pre handle must be a valid pointer. 00654 * type must be valid. 00655 * param must be valid. 00656 * RingIO_setAttribute has been successful. 00657 * 00658 * @post None. 00659 * 00660 * @see RingIO_getvAttribute () 00661 * ============================================================================ 00662 */ 00663 EXPORT_API 00664 DSP_STATUS 00665 RingIO_getAttribute (IN RingIO_Handle handle, 00666 OUT Uint16 * type, 00667 OUT Uint32* param) ; 00668 00669 00670 /** ============================================================================ 00671 * @func RingIO_setAttribute 00672 * 00673 * @brief This function sets a fixed-size attribute at the offset provided in 00674 * the acquired data buffer. 00675 * If the offset is not in the range of the acquired data buffer, the 00676 * attribute is not set, and an error is returned. One exception to 00677 * this rule is when no data buffer has been acquired. In this case an 00678 * attribute is set at the next data buffer offset that can be acquired 00679 * 00680 * @param handle 00681 * Handle to the RingIO Client. 00682 * @param offset 00683 * Offset in the acquired data buffer to which the attribute 00684 * corresponds 00685 * @param type 00686 * User-defined type of attribute. 00687 * @param param 00688 * Optional parameter which depends on the attribute type. 00689 * 00690 * @return RINGIO_SUCCESS 00691 * Operation successfully completed. 00692 * RINGIO_EFAILURE 00693 * General failure. 00694 * DSP_EINVALIDARG 00695 * Invalid arguments. 00696 * 00697 * @pre handle must be valid. 00698 * 00699 * @post None. 00700 * 00701 * @see RingIO_setvAttribute (), RingIO_getAttribute () 00702 * ============================================================================ 00703 */ 00704 EXPORT_API 00705 DSP_STATUS 00706 RingIO_setAttribute (IN RingIO_Handle handle, 00707 IN Uint32 offset, 00708 IN Uint16 type, 00709 IN Uint32 param) ; 00710 00711 00712 /** ============================================================================ 00713 * @func RingIO_flush 00714 * 00715 * @brief This function flushes the data buffer. 00716 * This function is used to flush the data from the RingIO. 00717 * Behavior of this function depends on the value of hardFlush argument 00718 * When hardFlush is false: 00719 * If function is called for the writer, all the valid data in buffer 00720 * after the first attribute location will be discarded. In case there 00721 * are no attributes, no data will be cleared from the buffer. Note 00722 * that this does not include the data that has been already acquired 00723 * by the reader. Note that the attribute will also be cleared from the 00724 * attribute buffer. 00725 * For the reader, all the data till the next attribute location will 00726 * be discarded. And if there is no attribute in the buffer, all valid 00727 * data will get discarded. Note that the attribute will remain the 00728 * attribute buffer. This is different from the behavior mentioned for 00729 * the writer. 00730 * When hardFlush is true: 00731 * If function is called from the writer, all committed data and 00732 * attributes that is not acquired by reader are removed from 00733 * the RingIO instance. The writer pointer is moved to point to 00734 * reader's head pointer 00735 * If function is called from the reader, all data and attributes 00736 * that can be subsequently acquired from the reader are removed. 00737 * 00738 * @param handle 00739 * Handle to the RingIO Client. 00740 * @param hardFlush 00741 * Mode in which the flush operation discards committed data 00742 * and attributes 00743 * @param type 00744 * Location to receive the User-defined type of attribute. 00745 * @param param 00746 * Location to receive an optional parameter which depends on the 00747 * attribute type. 00748 * @param bytesFlushed 00749 * Location to recieve the size of the buffer flushed. 00750 * 00751 * @return RINGIO_SUCCESS 00752 * Operation successfully completed. 00753 * RINGIO_EFAILURE 00754 * General failure. 00755 * DSP_EINVALIDARG 00756 * Invalid arguments. 00757 * 00758 * @pre handle must be a valid pointer. 00759 * type must be valid. 00760 * param must be valid. 00761 * 00762 * @post None. 00763 * 00764 * @see None. 00765 * ============================================================================ 00766 */ 00767 EXPORT_API 00768 DSP_STATUS 00769 RingIO_flush (IN RingIO_Handle handle, 00770 IN Bool hardFlush, 00771 OUT Uint16 * type, 00772 OUT Uint32 * param, 00773 OUT Uint32 * bytesFlushed) ; 00774 00775 00776 /** ============================================================================ 00777 * @func RingIO_setNotifier 00778 * 00779 * @brief This function sets Notification parameters for the RingIO Client. 00780 * Both the reader and writer can set their notification mechanism 00781 * using this function 00782 * 00783 * @param handle 00784 * Handle to the RingIO client. 00785 * @param notifyType 00786 * Type of notification. 00787 * @param notifyWatermark 00788 * Watermark for notification 00789 * @param notifyFunc 00790 * Function to call when notification is required 00791 * @param notifyParam 00792 * Pointer to the notification parameter. The type of the pointer 00793 * and its size depends on the notification function 00794 * 00795 * @return RINGIO_SUCCESS 00796 * Operation successfully completed. 00797 * RINGIO_EFAILURE 00798 * General failure. 00799 * DSP_EINVALIDARG 00800 * Invalid arguments. 00801 * 00802 * @pre RingIO_open for both reader and writer has been successful. 00803 * No DSP/BIOS Link API should be called from a callback function 00804 * registered through the RingIO or NOTIFY module. On DSP-side or 00805 * on operating systems such as PrOS, the callback functions are 00806 * run from ISR context and must not perform any operations that 00807 * may take a lock or block, which is done by most DSPLink APIs. 00808 * Minimum functionality must be used in the callback functions, 00809 * most often limited to posting a semaphore on which application 00810 * is waiting, posting SWI etc. 00811 * 00812 * @post None. 00813 * 00814 * @see RingIO_NotifyType, RingIO_NotifyFunc, RingIO_NotifyParam 00815 * ============================================================================ 00816 */ 00817 EXPORT_API 00818 DSP_STATUS 00819 RingIO_setNotifier (IN RingIO_Handle handle, 00820 IN RingIO_NotifyType notifyType, 00821 IN Uint32 notifyWatermark, 00822 IN RingIO_NotifyFunc notifyFunc, 00823 IN RingIO_NotifyParam notifyParam) ; 00824 00825 /** ============================================================================ 00826 * @func RingIO_sendNotify 00827 * 00828 * @brief Send a notification to the other client manually 00829 * 00830 * @param handle 00831 * Handle to the RingIO Client. 00832 * arg msg 00833 * Message to be sent along with notification. 00834 * 00835 * @return RINGIO_SUCCESS 00836 * Operation successfully completed. 00837 * RINGIO_EFAILURE 00838 * General failure. 00839 * 00840 * @pre None. 00841 * 00842 * @post None. 00843 * 00844 * @see None. 00845 * ============================================================================ 00846 */ 00847 EXPORT_API 00848 DSP_STATUS 00849 RingIO_sendNotify (IN RingIO_Handle handle, IN RingIO_NotifyMsg msg) ; 00850 00851 #if defined (__cplusplus) 00852 } 00853 #endif /* defined (__cplusplus) */ 00854 00855 00856 #endif /* !defined (RINGIO_H) */