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

chnl.h

Go to the documentation of this file.
00001 /** ============================================================================
00002  *  @file   chnl.h
00003  *
00004  *  @path   $(DSPLINK)/gpp/inc/usr/
00005  *
00006  *  @brief  Defines the interfaces and data structures for the API sub-component
00007  *          CHNL.
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 (CHNL_H)
00045 #define  CHNL_H
00046 
00047 
00048 /*  ----------------------------------- DSP/BIOS Link                   */
00049 #include <dsplink.h>
00050 #include <chnldefs.h>
00051 
00052 /*  ----------------------------------- Profiling                       */
00053 #if defined (DDSP_PROFILE)
00054 #include <profile.h>
00055 #endif /* #if defined (DDSP_PROFILE) */
00056 
00057 
00058 #if defined (__cplusplus)
00059 extern "C" {
00060 #endif /* defined (__cplusplus) */
00061 
00062 
00063 /** ============================================================================
00064  *  @func   CHNL_create
00065  *
00066  *  @brief  Creates resources used for transferring data between GPP and DSP.
00067  *
00068  *  @param procId
00069  *              Processor Identifier.
00070  *  @param chnlId
00071  *              Channel Id to open.
00072  *  @param attrs
00073  *              Channel attributes - if NULL, default attributes are applied.
00074  *
00075  *  @return DSP_SOK
00076  *              Operation successfully completed.
00077  *          DSP_EFAIL
00078  *              General failure.
00079  *          DSP_EMEMORY
00080  *              Operation failed due to memory error.
00081  *          DSP_EINVALIDARG
00082  *              Invalid Parameter passed.
00083  *
00084  *  @pre    Channels for specified processors must be initialized.
00085  *          Processor and  channel ids must be valid.
00086  *          Attributes must be valid.
00087  *          PROC_load  has been successful.
00088  *          POOL_open i.e. POOL configuration has been successful.
00089  *
00090  *  @post   None
00091  *
00092  *  @see    None
00093  *  ============================================================================
00094  */
00095 EXPORT_API
00096 DSP_STATUS
00097 CHNL_create (IN ProcessorId      procId,
00098              IN ChannelId        chnlId,
00099              IN ChannelAttrs *   attrs) ;
00100 
00101 
00102 /** ============================================================================
00103  *  @func   CHNL_delete
00104  *
00105  *  @brief  Releases channel resources used for transferring data between GPP
00106  *          and DSP.
00107  *
00108  *  @param procId
00109  *              Processor Identifier.
00110  *  @param chnlId
00111  *              Channel Identifier.
00112  *
00113  *  @return DSP_SOK
00114  *              Operation successfully completed.
00115  *          DSP_EFAIL
00116  *              General failure.
00117  *          DSP_EMEMORY
00118  *              Operation failed due to memory error.
00119  *          DSP_EINVALIDARG
00120  *              Invalid Parameter passed.
00121  *
00122  *  @pre    Channels for specified processors should have been initialized.
00123  *          Processor and  channel ids should be valid.
00124  *          All CHNL operations are complete.
00125  *
00126  *  @post   None
00127  *
00128  *  @see    CHNL_create
00129  *  ============================================================================
00130  */
00131 EXPORT_API
00132 DSP_STATUS
00133 CHNL_delete (IN ProcessorId    procId,
00134              IN ChannelId      chnlId) ;
00135 
00136 
00137 /** ============================================================================
00138  *  @func   CHNL_allocateBuffer
00139  *
00140  *  @brief  Allocates an array of buffers of specified size and returns them
00141  *          to the client.
00142  *
00143  *  @param procId
00144  *              Processor Identifier.
00145  *  @param chnlId
00146  *              Channel Identifier.
00147  *  @param size
00148  *              Size of each buffer.
00149  *  @param bufArray
00150  *              Pointer to receive array of allocated buffers.
00151  *  @param numBufs
00152  *              Number of buffers to allocate.
00153  *
00154  *  @return DSP_SOK
00155  *              Operation successfully completed.
00156  *          DSP_EFAIL
00157  *              General failure.
00158  *          DSP_EMEMORY
00159  *              Operation failed due to memory error.
00160  *          DSP_EINVALIDARG
00161  *              Invalid parameter passed.
00162  *
00163  *  @pre    Channels for specified processors must be initialized.
00164  *          Processor and  channel ids must be valid.
00165  *          bufArray must be valid.
00166  *          size must not be zero.
00167  *          numBufs must be less than/equal to MAX_ALLOC_BUFFERS.
00168  *          CHNL_create has been successful.
00169  *          POOL_open i.e. POOL configuration has been successful.
00170  *
00171  *  @post   None
00172  *
00173  *  @see    CHNL_create, CHNL_freeBuffer
00174  *  ============================================================================
00175  */
00176 EXPORT_API
00177 DSP_STATUS
00178 CHNL_allocateBuffer (IN  ProcessorId procId,
00179                      IN  ChannelId   chnlId,
00180                      OUT Char8 **    bufArray,
00181                      IN  Uint32      size,
00182                      IN  Uint32      numBufs) ;
00183 
00184 
00185 /** ============================================================================
00186  *  @func   CHNL_freeBuffer
00187  *
00188  *  @brief  Frees buffer(s) allocated by CHNL_allocateBuffer.
00189  *
00190  *  @param procId
00191  *              Processor Identifier.
00192  *  @param chnlId
00193  *              Channel Identifier.
00194  *  @param bufArray
00195  *              Pointer to the array of buffers to freed.
00196  *  @param numBufs
00197  *              Number of buffers to be freed.
00198  *
00199  *  @return DSP_SOK
00200  *              Operation successfully completed.
00201  *          DSP_EFAIL
00202  *              General failure.
00203  *          DSP_EMEMORY
00204  *              Operation failed due to memory error.
00205  *          DSP_EINVALIDARG
00206  *              Invalid parameter passed.
00207  *
00208  *  @pre    Channels for specified processors must be initialized.
00209  *          Processor and  channel ids must be valid.
00210  *          bufArray must be valid.
00211  *          numBufs must be less than/equal to MAX_ALLOC_BUFFERS.
00212  *          All data transfer to DSP using CHNL is complete.
00213  *
00214  *  @post   None
00215  *
00216  *  @see    CHNL_create, CHNL_allocateBuffer
00217  *  ============================================================================
00218  */
00219 EXPORT_API
00220 DSP_STATUS
00221 CHNL_freeBuffer (IN ProcessorId procId,
00222                  IN ChannelId   chnlId,
00223                  IN Char8 **    bufArray,
00224                  IN Uint32      numBufs) ;
00225 
00226 
00227 /** ============================================================================
00228  *  @func   CHNL_issue
00229  *
00230  *  @brief  Issues an input or output request on a specified channel.
00231  *
00232  *  @param procId
00233  *              Processor Identifier.
00234  *  @param chnlId
00235  *              Channel Identifier.
00236  *  @param ioReq
00237  *              Information regarding IO.
00238  *
00239  *  @return DSP_SOK
00240  *              Operation successfully completed.
00241  *          DSP_EFAIL
00242  *              General failure.
00243  *          DSP_EMEMORY
00244  *              Operation failed due to memory error.
00245  *          DSP_EINVALIDARG
00246  *              Invalid parameter passed.
00247  *
00248  *  @pre    Channels for specified processors must be initialized.
00249  *          Processor and  channel ids must be valid.
00250  *          ioReq must be valid.
00251  *          CHNL_create, CHNL_allocateBuffer has been successful.
00252  *          Corresponding data stream on dsp side has been created.
00253  *          Data buffer is prime'd for data transfer
00254  *
00255  *  @post   Corresponding data reclaim on gpp/dsp side is done.
00256  *
00257  *  @see    CHNL_reclaim
00258  *  ============================================================================
00259  */
00260 EXPORT_API
00261 DSP_STATUS
00262 CHNL_issue (IN ProcessorId      procId,
00263             IN ChannelId        chnlId,
00264             IN ChannelIOInfo *  ioReq) ;
00265 
00266 
00267 /** ============================================================================
00268  *  @func   CHNL_reclaim
00269  *
00270  *  @brief  Gets the buffer back that has been issued to this channel.
00271  *          This call blocks for specified timeout value ranging from NO_WAIT
00272  *          to WAIT_FOREVER.
00273  *
00274  *  @param procId
00275  *              Processor Identifier.
00276  *  @param chnlId
00277  *              Channel Identifier.
00278  *  @param timeout
00279  *              Timeout value for this operation.
00280  *              Unit of timeout is OS dependent.
00281  *  @param ioReq
00282  *              Information needed for doing reclaim.
00283  *
00284  *  @return DSP_SOK
00285  *              Operation successfully completed.
00286  *          DSP_EFAIL
00287  *              General failure.
00288  *          DSP_EMEMORY
00289  *              Operation failed due to memory error.
00290  *          DSP_EINVALIDARG
00291  *              Invalid parameter passed.
00292  *          CHNL_E_NOIOC
00293  *              Timeout parameter was "NO_WAIT", yet no I/O completions were
00294  *              queued.
00295  *
00296  *  @pre    Channels for specified processors must be initialized.
00297  *          Processor and  channel ids must be valid.
00298  *          CCHNL_issue has been successful.
00299  *
00300  *  @post   None
00301  *
00302  *  @see    CHNL_issue
00303  *  ============================================================================
00304  */
00305 EXPORT_API
00306 DSP_STATUS
00307 CHNL_reclaim (IN     ProcessorId       procId,
00308               IN     ChannelId         chnlId,
00309               IN     Uint32            timeout,
00310               IN OUT ChannelIOInfo *   ioReq) ;
00311 
00312 
00313 /** ============================================================================
00314  *  @func   CHNL_idle
00315  *
00316  *  @brief  In the input mode channel, this function resets the channel
00317  *          and causes any currently buffered input data to be discarded.
00318  *
00319  *          In the output mode channel, this function causes any currently
00320  *          queued buffers to be transferred through the channel. It causes
00321  *          the client to wait for as long as it takes for the data to be
00322  *          transferred through the channel.
00323  *
00324  *  @param procId
00325  *              Processor Identifier.
00326  *  @param chnlId
00327  *              Channel Identifier.
00328  *
00329  *  @return DSP_SOK
00330  *              Operation successfully completed.
00331  *          DSP_EFAIL
00332  *              General failure.
00333  *          DSP_EMEMORY
00334  *              Operation failed due to memory error.
00335  *          DSP_EINVALIDARG
00336  *              Invalid parameter passed.
00337  *
00338  *  @pre    Channels for specified processor must be initialized.
00339  *          Processor and  channel ids must be valid.
00340  *          CHNL_create, CHNL_allocateBuffer, CHNL_open has been successful.
00341  *
00342  *  @post   None
00343  *
00344  *  @see    CHNL_create
00345  *  ============================================================================
00346  */
00347 EXPORT_API
00348 DSP_STATUS
00349 CHNL_idle (IN ProcessorId  procId,
00350            IN ChannelId    chnlId) ;
00351 
00352 
00353 /** ============================================================================
00354  *  @func   CHNL_flush
00355  *
00356  *  @brief  Discards all the requested buffers that are pending for transfer
00357  *          both in case of input mode channel as well as output mode channel.
00358  *          One must still have to call the CHNL_reclaim to get back the
00359  *          discarded buffers.
00360  *
00361  *  @param procId
00362  *              Processor Identifier.
00363  *  @param chnlId
00364  *              Channel Identifier.
00365  *
00366  *  @return DSP_SOK
00367  *              Operation successfully completed.
00368  *          DSP_EFAIL
00369  *              General failure.
00370  *          DSP_EMEMORY
00371  *              Operation failed due to memory error.
00372  *          DSP_EINVALIDARG
00373  *              Invalid parameter passed.
00374  *
00375  *  @pre    Channels for specified processor must be initialized.
00376  *          Processor and  channel ids must be valid.
00377  *          CHNL_issue has been successful.
00378  *
00379  *  @post   None
00380  *
00381  *  @see    CHNL_create, CHNL_issue
00382  *  ============================================================================
00383  */
00384 EXPORT_API
00385 DSP_STATUS
00386 CHNL_flush (IN ProcessorId         procId,
00387             IN ChannelId           chnlId) ;
00388 
00389 
00390 /** ============================================================================
00391  *  @func   CHNL_control
00392  *
00393  *  @brief  Provides a hook to perform device dependent control operations
00394  *          on channels.
00395  *
00396  *  @param procId
00397  *              Processor Identifier.
00398  *  @param chnlId
00399  *              Channel Identifier.
00400  *  @param cmd
00401  *              Command id.
00402  *  @param arg
00403  *              Optional argument for the specified command.
00404  *
00405  *  @return DSP_SOK
00406  *              Operation successfully completed.
00407  *          DSP_EFAIL
00408  *              General failure.
00409  *          DSP_EMEMORY
00410  *              Operation failed due to memory error.
00411  *          DSP_EINVALIDARG
00412  *              Invalid parameter passed.
00413  *
00414  *  @pre    Channels for specified processor must be initialized.
00415  *          Processor and  channel ids must be valid.
00416  *          CHNL_create, CHNL_allocateBuffer has been successful.
00417  *
00418  *  @post   None
00419  *
00420  *  @see    None
00421  *  ============================================================================
00422  */
00423 EXPORT_API
00424 DSP_STATUS
00425 CHNL_control (IN  ProcessorId    procId,
00426               IN  ChannelId      chnlId,
00427               IN  Int32          cmd,
00428                   Pvoid          arg) ;
00429 
00430 
00431 #if defined (DDSP_PROFILE)
00432 /** ============================================================================
00433  *  @func   CHNL_instrument
00434  *
00435  *  @brief  Gets the instrumentation information related to CHNL's
00436  *
00437  *  @param procId
00438  *              Identifier for processor.
00439  *  @param chnlId
00440  *              Identifier for channel for which instrumentation information
00441  *              is to be obtained.
00442  *  @param retVal
00443  *              OUT argument to contain the instrumentation information.
00444  *
00445  *  @return DSP_SOK
00446  *              Operation successfully completed.
00447  *          DSP_EINVALIDARG
00448  *              retVal is invalid.
00449  *
00450  *  @pre    Channels for specified processor must be initialized.
00451  *          Processor and  channel ids must be valid.
00452  *          retVal must be a valid pointer.
00453  *          CHNL_create has been successful.
00454  *          Profiling has been selected in the configuration.
00455  *
00456  *  @post   None
00457  *
00458  *  @see    None
00459  *  ============================================================================
00460  */
00461 EXPORT_API
00462 DSP_STATUS
00463 CHNL_instrument (IN  ProcessorId       procId,
00464                  IN  ChannelId         chnlId,
00465                  OUT CHNL_Instrument * retVal) ;
00466 #endif /* #if defined (DDSP_PROFILE) */
00467 
00468 
00469 #if defined (DDSP_DEBUG)
00470 /** ============================================================================
00471  *  @func   CHNL_debug
00472  *
00473  *  @brief  Prints the current status of CHNL subcomponent.
00474  *
00475  *  @param procId
00476  *              Identifier for processor.
00477  *  @param chnlId
00478  *              Identifier for channel.
00479  *
00480  *  @return None
00481  *
00482  *  @pre    Channels for specified processor must be initialized.
00483  *          Processor and  channel ids must be valid.
00484  *          CHNL_create has been successful.
00485  *
00486  *  @post   None
00487  *
00488  *  @see    None
00489  *  ============================================================================
00490  */
00491 EXPORT_API
00492 Void
00493 CHNL_debug (IN ProcessorId procId,
00494             IN ChannelId   chnlId) ;
00495 #endif /* defined (DDSP_DEBUG) */
00496 
00497 
00498 /** ============================================================================
00499  *  @deprecated The deprecated API CHNL_Create has been replaced
00500  *              with CHNL_create.
00501  *              This has been done to follow DSP/BIOS coding guidelines and
00502  *              have a uniform naming convention for the API's on both GPP
00503  *              as well as DSP.
00504  *
00505  *  ============================================================================
00506  */
00507 #define CHNL_Create                CHNL_create
00508 
00509 /** ============================================================================
00510  *  @deprecated The deprecated API CHNL_Delete has been replaced
00511  *              with CHNL_delete.
00512  *              This has been done to follow DSP/BIOS coding guidelines and
00513  *              have a uniform naming convention for the API's on both GPP
00514  *              as well as DSP.
00515  *
00516  *  ============================================================================
00517  */
00518 #define CHNL_Delete                CHNL_delete
00519 
00520 /** ============================================================================
00521  *  @deprecated The deprecated API CHNL_AllocateBuffer has been replaced
00522  *              with CHNL_allocateBuffer.
00523  *              This has been done to follow DSP/BIOS coding guidelines and
00524  *              have a uniform naming convention for the API's on both GPP
00525  *              as well as DSP.
00526  *
00527  *  ============================================================================
00528  */
00529 #define CHNL_AllocateBuffer        CHNL_allocateBuffer
00530 
00531 /** ============================================================================
00532  *  @deprecated The deprecated API CHNL_FreeBuffer has been replaced
00533  *              with CHNL_freeBuffer.
00534  *              This has been done to follow DSP/BIOS coding guidelines and
00535  *              have a uniform naming convention for the API's on both GPP
00536  *              as well as DSP.
00537  *
00538  *  ============================================================================
00539  */
00540 #define CHNL_FreeBuffer            CHNL_freeBuffer
00541 
00542 /** ============================================================================
00543  *  @deprecated The deprecated API CHNL_Issue has been replaced
00544  *              with CHNL_issue.
00545  *              This has been done to follow DSP/BIOS coding guidelines and
00546  *              have a uniform naming convention for the API's on both GPP
00547  *              as well as DSP.
00548  *
00549  *  ============================================================================
00550  */
00551 #define CHNL_Issue                 CHNL_issue
00552 
00553 /** ============================================================================
00554  *  @deprecated The deprecated API CHNL_Reclaim has been replaced
00555  *              with CHNL_reclaim.
00556  *              This has been done to follow DSP/BIOS coding guidelines and
00557  *              have a uniform naming convention for the API's on both GPP
00558  *              as well as DSP.
00559  *
00560  *  ============================================================================
00561  */
00562 #define CHNL_Reclaim               CHNL_reclaim
00563 
00564 /** ============================================================================
00565  *  @deprecated The deprecated API CHNL_Idle has been replaced
00566  *              with CHNL_idle.
00567  *              This has been done to follow DSP/BIOS coding guidelines and
00568  *              have a uniform naming convention for the API's on both GPP
00569  *              as well as DSP.
00570  *
00571  *  ============================================================================
00572  */
00573 #define CHNL_Idle                  CHNL_idle
00574 
00575 /** ============================================================================
00576  *  @deprecated The deprecated API CHNL_Flush has been replaced
00577  *              with CHNL_flush.
00578  *              This has been done to follow DSP/BIOS coding guidelines and
00579  *              have a uniform naming convention for the API's on both GPP
00580  *              as well as DSP.
00581  *
00582  *  ============================================================================
00583  */
00584 #define CHNL_Flush                 CHNL_flush
00585 
00586 /** ============================================================================
00587  *  @deprecated The deprecated API CHNL_Control has been replaced
00588  *              with CHNL_control.
00589  *              This has been done to follow DSP/BIOS coding guidelines and
00590  *              have a uniform naming convention for the API's on both GPP
00591  *              as well as DSP.
00592  *
00593  *  ============================================================================
00594  */
00595 #define CHNL_Control               CHNL_control
00596 
00597 #if defined (DDSP_DEBUG)
00598 /** ============================================================================
00599  *  @deprecated The deprecated API CHNL_Debug has been replaced
00600  *              with CHNL_debug.
00601  *              This has been done to follow DSP/BIOS coding guidelines and
00602  *              have a uniform naming convention for the API's on both GPP
00603  *              as well as DSP.
00604  *
00605  *  ============================================================================
00606  */
00607 #define CHNL_Debug                 CHNL_debug
00608 #endif /* defined (DDSP_DEBUG) */
00609 
00610 
00611 #if defined (__cplusplus)
00612 }
00613 #endif /* defined (__cplusplus) */
00614 
00615 
00616 #endif /* !defined (CHNL_H) */

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