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

gpp/inc/ringio.h

Go to the documentation of this file.
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) */

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