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

dsp.h

Go to the documentation of this file.
00001 /** ============================================================================
00002  *  @file   dsp.h
00003  *
00004  *  @path   $(DSPLINK)/gpp/inc/sys/arch/
00005  *
00006  *  @brief  Defines interface exposed by DSP sub-component.
00007  *
00008  *  @ver    1.65.00.03
00009  *  ============================================================================
00010  *  @copyright Copyright (C) 2002-2009, Texas Instruments Incorporated -
00011  *  http://www.ti.com/
00012  *
00013  *  Redistribution and use in source and binary forms, with or without
00014  *  modification, are permitted provided that the following conditions
00015  *  are met:
00016  *  
00017  *  *  Redistributions of source code must retain the above copyright
00018  *     notice, this list of conditions and the following disclaimer.
00019  *  
00020  *  *  Redistributions in binary form must reproduce the above copyright
00021  *     notice, this list of conditions and the following disclaimer in the
00022  *     documentation and/or other materials provided with the distribution.
00023  *  
00024  *  *  Neither the name of Texas Instruments Incorporated nor the names of
00025  *     its contributors may be used to endorse or promote products derived
00026  *     from this software without specific prior written permission.
00027  *  
00028  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00029  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
00030  *  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00031  *  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
00032  *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00033  *  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00034  *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
00035  *  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
00036  *  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
00037  *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00038  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00039  *  ============================================================================
00040  */
00041 
00042 
00043 #if !defined (DSP_H)
00044 #define DSP_H
00045 
00046 
00047 /*  ----------------------------------- DSP/BIOS Link                   */
00048 #include <dsplink.h>
00049 #include <_dspdefs.h>
00050 
00051 #if defined (DDSP_PROFILE)
00052 #include <profile.h>
00053 #endif /* #if defined (DDSP_PROFILE) */
00054 
00055 
00056 #if defined (__cplusplus)
00057 extern "C" {
00058 #endif /* defined (__cplusplus) */
00059 
00060 
00061 /** ============================================================================
00062  *  @func   DSP_moduleInit
00063  *
00064  *  @brief  Initializes the DSP module.
00065  *
00066  *  @return None.
00067  *
00068  *  @pre    dspId must be a valid DSP identifier.
00069  *
00070  *  @post   None.
00071  *
00072  *  @see    DSP_init
00073  *  ============================================================================
00074  */
00075 NORMAL_API
00076 Void
00077 DSP_moduleInit (Void) ;
00078 
00079 
00080 /** ============================================================================
00081  *  @func   DSP_moduleExit
00082  *
00083  *  @brief  Finalizes the DSP module.
00084  *
00085  *  @return None.
00086  *
00087  *  @pre    dspId must be a valid DSP identifier.
00088  *
00089  *  @post   None.
00090  *
00091  *  @see    DSP_init
00092  *  ============================================================================
00093  */
00094 NORMAL_API
00095 Void
00096 DSP_moduleExit (Void) ;
00097 
00098 
00099 /** ============================================================================
00100  *  @func   DSP_init
00101  *
00102  *  @brief  Resets the DSP and initializes the components required by DSP.
00103  *          Puts the DSP in RESET state.
00104  *
00105  *  @param dspId
00106  *              Processor Id.
00107  *  @param interface
00108  *              Interface to DSP/DEVICE APIs.
00109  *
00110  *  @return DSP_SOK
00111  *              Operation successfully completed.
00112  *          DSP_EINVALIDARG
00113  *              Invalid argument.
00114  *          DSP_EVALUE
00115  *              Invalid DSP MMU endianism configuration.
00116  *          DSP_EFAIL
00117  *              DSP_setup function wasn't called before calling this function.
00118  *
00119  *  @pre    DSP_setup must be called before calling this function.
00120  *          dspId must be a valid DSP identifier.
00121  *
00122  *  @post   None.
00123  *
00124  *  @see    DSP_exit
00125  *  ============================================================================
00126  */
00127 NORMAL_API
00128 DSP_STATUS
00129 DSP_init (IN ProcessorId  dspId, IN DSP_Interface * interface) ;
00130 
00131 
00132 /** ============================================================================
00133  *  @func   DSP_exit
00134  *
00135  *  @brief  Resets the DSP and puts it into IDLE Mode.
00136  *
00137  *  @param dspId
00138  *              Processor Id.
00139  *
00140  *  @return DSP_SOK
00141  *              Operation successfully completed.
00142  *          DSP_EINVALIDARG
00143  *              Invalid argument..
00144  *          DSP_EFAIL
00145  *              DSP_setup function wasn't called before calling this function.
00146  *
00147  *  @pre    DSP_setup must be called before calling this function.
00148  *          dspId must be a valid DSP identifier.
00149  *
00150  *  @post   None.
00151  *
00152  *  @see    DSP_init
00153  *  ============================================================================
00154  */
00155 NORMAL_API
00156 DSP_STATUS
00157 DSP_exit (IN ProcessorId dspId) ;
00158 
00159 
00160 /** ============================================================================
00161  *  @func   DSP_start
00162  *
00163  *  @brief  Causes DSP to start execution from the given DSP address.
00164  *          DSP is put to STARTED state after successful completion.
00165  *
00166  *  @param dspId
00167  *              Processor Id.
00168  *  @param dspAddr
00169  *              Address to start execution from.
00170  *
00171  *  @return DSP_SOK
00172  *              Operation successfully completed.
00173  *          DSP_EINVALIDARG
00174  *              Invalid argument..
00175  *          DSP_EFAIL
00176  *              DSP_setup function wasn't called before calling this function.
00177  *
00178  *  @pre    DSP_setup must be called before calling this function.
00179  *          dspId must be a valid DSP identifier.
00180  *
00181  *  @post   None.
00182  *
00183  *  @see    DSP_stop
00184  *  ============================================================================
00185  */
00186 NORMAL_API
00187 DSP_STATUS
00188 DSP_start (IN ProcessorId dspId, IN Uint32 dspAddr) ;
00189 
00190 
00191 /** ============================================================================
00192  *  @func   DSP_stop
00193  *
00194  *  @brief  Stops execution on DSP.
00195  *          DSP is put to STOPPED state after successful completion.
00196  *
00197  *  @param dspId
00198  *              Processor Id.
00199  *
00200  *  @return DSP_SOK
00201  *              Operation successfully completed.
00202  *          DSP_EINVALIDARG
00203  *              Invalid argument..
00204  *          DSP_EFAIL
00205  *              DSP_setup function wasn't called before calling this function.
00206  *
00207  *  @pre    DSP_setup must be called before calling this function.
00208  *          dspId must be a valid DSP identifier.
00209  *
00210  *  @post   None.
00211  *
00212  *  @see    DSP_start
00213  *  ============================================================================
00214  */
00215 NORMAL_API
00216 DSP_STATUS
00217 DSP_stop (IN ProcessorId dspId) ;
00218 
00219 
00220 /** ============================================================================
00221  *  @func   DSP_idle
00222  *
00223  *  @brief  Idles the DSP.
00224  *          DSP is put to IDLE state after successful completion.
00225  *
00226  *  @param dspId
00227  *              Processor Id.
00228  *
00229  *  @return DSP_SOK
00230  *              Operation successfully completed.
00231  *          DSP_EINVALIDARG
00232  *              Invalid argument..
00233  *          DSP_EFAIL
00234  *              DSP_setup function wasn't called before calling this function.
00235  *
00236  *  @pre    DSP_setup must be called before calling this function.
00237  *          dspId must be a valid DSP identifier.
00238  *
00239  *  @post   None.
00240  *
00241  *  @see    DSP_start
00242  *  ============================================================================
00243  */
00244 NORMAL_API
00245 DSP_STATUS
00246 DSP_idle (IN ProcessorId dspId) ;
00247 
00248 
00249 /** ============================================================================
00250  *  @func   DSP_intCtrl
00251  *
00252  *  @brief  Perform the specified DSP interrupt control activity.
00253  *
00254  *  @param dspId
00255  *              Processor ID.
00256  *  @param intId
00257  *              Interrupt ID.
00258  *  @param cmd
00259  *              Interrupt control command to be performed.
00260  *  @param arg
00261  *              Optional input/output argument specific to each control command.
00262  *
00263  *  @return DSP_SOK
00264  *              Operation successfully completed.
00265  *          DSP_EINVALIDARG
00266  *              Invalid argument.
00267  *          DSP_EFAIL
00268  *              DSP_setup function wasn't called before calling this function.
00269  *
00270  *  @pre    DSP_setup must be called before calling this function.
00271  *          dspId must be a valid DSP identifier.
00272  *          isrObj must be a valid pointer.
00273  *
00274  *  @post   None.
00275  *
00276  *  @see    DSP_start
00277  *  ============================================================================
00278  */
00279 NORMAL_API
00280 DSP_STATUS
00281 DSP_intCtrl (IN         ProcessorId       dspId,
00282              IN         Uint32            intId,
00283              IN         DSP_IntCtrlCmd    cmd,
00284              IN OUT     Pvoid             arg) ;
00285 
00286 
00287 /** ============================================================================
00288  *  @func   DSP_read
00289  *
00290  *  @brief  Reads data from DSP.
00291  *
00292  *  @param dspId
00293  *              Processor ID.
00294  *  @param dspAddr
00295  *              DSP address to read from.
00296  *  @param endianInfo
00297  *              endianness of data - indicates whether swap is required or not.
00298  *  @param numBytes
00299  *              Number of bytes to read.
00300  *  @param buffer
00301  *              Buffer to hold the read data.
00302  *
00303  *  @return DSP_SOK
00304  *              Operation successfully completed.
00305  *          DSP_EINVALIDARG
00306  *              Invalid argument..
00307  *          DSP_EFAIL
00308  *              DSP_setup function wasn't called before calling this function.
00309  *
00310  *  @pre    DSP_setup must be called before calling this function.
00311  *          dspId must be a valid DSP identifier.
00312  *          numBytes must be a valid pointer.
00313  *          buffer must be a valid pointer.
00314  *
00315  *  @post   On successful completion, holds the number of bytes read.
00316  *
00317  *  @see    None.
00318  *  ============================================================================
00319  */
00320 NORMAL_API
00321 DSP_STATUS
00322 DSP_read (IN  ProcessorId  dspId,
00323           IN  Uint32       dspAddr,
00324           IN  Endianism    endianInfo,
00325           IN  Uint32       numBytes,
00326           OUT Uint8 *      buffer) ;
00327 
00328 
00329 /** ============================================================================
00330  *  @func   DSP_write
00331  *
00332  *  @brief  Writes data to DSP.
00333  *
00334  *  @param dspId
00335  *              Processor ID.
00336  *  @param dspAddr
00337  *              DSP address to write to.
00338  *  @param endianInfo
00339  *              endianness of data - indicates whether swap is required or not.
00340  *  @param numBytes
00341  *              Number of bytes to write.
00342  *  @param buffer
00343  *              Buffer containing data to be written.
00344  *
00345  *  @return DSP_SOK
00346  *              Operation successfully completed.
00347  *          DSP_EINVALIDARG
00348  *              Invalid argument..
00349  *          DSP_EFAIL
00350  *              DSP_setup function wasn't called before calling this function.
00351  *
00352  *  @pre    DSP_setup must be called before calling this function.
00353  *          dspId must be a valid DSP identifier.
00354  *          buffer must be a valid pointer.
00355  *
00356  *  @post   None.
00357  *
00358  *  @see    None.
00359  *  ============================================================================
00360  */
00361 NORMAL_API
00362 DSP_STATUS
00363 DSP_write (IN ProcessorId dspId,
00364            IN Uint32      dspAddr,
00365            IN Endianism   endianInfo,
00366            IN Uint32      numBytes,
00367            IN Uint8 *     buffer) ;
00368 
00369 
00370 /** ============================================================================
00371  *  @func   DSP_addrConvert
00372  *
00373  *  @brief  Convert address between GPP and DSP address space.
00374  *
00375  *  @param dspId
00376  *              Processor Id.
00377  *  @param addr
00378  *              Address to be converted. If DSP address, the addr parameter
00379  *              reflects the DSP MADU address.
00380  *  @param type
00381  *              Type of address conversion.
00382  *
00383  *  @return Converted address.
00384  *              Operation successfully completed.
00385  *          ADDRMAP_INVALID.
00386  *              Specified address is not in mapped range.
00387  *
00388  *  @pre    DSP_setup must be called before calling this function.
00389  *          dspId must be a valid DSP identifier.
00390  *
00391  *  @post   None.
00392  *
00393  *  @see    DSP_AddrConvType
00394  *  ============================================================================
00395  */
00396 NORMAL_API
00397 Uint32
00398 DSP_addrConvert (IN  ProcessorId        dspId,
00399                  IN  Uint32             addr,
00400                  IN  DSP_AddrConvType    type) ;
00401 
00402 
00403 /** ============================================================================
00404  *  @func   DSP_control
00405  *
00406  *  @brief  Hook for performing device dependent control operation.
00407  *
00408  *  @param dspId
00409  *              Processor ID.
00410  *  @param cmd
00411  *              Command id.
00412  *  @param arg
00413  *              Optional argument for the specified command.
00414  *
00415  *  @return DSP_SOK
00416  *              Operation successfully completed.
00417  *          DSP_EINVALIDARG
00418  *              Invalid arguments specified.
00419  *
00420  *  @pre    DSP_setup must be called before calling this function.
00421  *          dspId must be a valid DSP identifier.
00422  *
00423  *  @post   None.
00424  *
00425  *  @see    None.
00426  *  ============================================================================
00427  */
00428 NORMAL_API
00429 DSP_STATUS
00430 DSP_control (IN  ProcessorId dspId,
00431              IN  Int32       cmd,
00432                  Pvoid       arg) ;
00433 
00434 
00435 #if defined (DDSP_PROFILE)
00436 /** ============================================================================
00437  *  @func   DSP_instrument
00438  *
00439  *  @brief  Gets the instrumentation information related to the specified
00440  *          DSP object.
00441  *
00442  *  @param dspId
00443  *              Processor ID.
00444  *  @param retVal
00445  *              Placeholder to return the instrumentation information.
00446  *
00447  *  @return DSP_SOK
00448  *              Operation successfully completed.
00449  *          DSP_EINVALIDARG
00450  *              Invalid argument(s).
00451  *
00452  *  @pre    dspId must be a valid DSP identifier.
00453  *          retVal must be valid.
00454  *
00455  *  @post   None.
00456  *
00457  *  @see    DspObject
00458  *  ============================================================================
00459  */
00460 NORMAL_API
00461 DSP_STATUS
00462 DSP_instrument (IN  ProcessorId dspId, OUT DSP_Stats * retVal) ;
00463 
00464 #endif /* if defined (DDSP_PROFILE) */
00465 
00466 
00467 #if defined (DDSP_DEBUG)
00468 /** ============================================================================
00469  *  @func   DSP_debug
00470  *
00471  *  @brief  Prints debug information of the specified DSP object.
00472  *
00473  *  @param dspId
00474  *              Processor ID.
00475  *
00476  *  @return DSP_SOK
00477  *              Operation successfully completed.
00478  *          DSP_EINVALIDARG
00479  *              Invalid argument.
00480  *
00481  *  @pre    dspId must be a valid DSP identifier.
00482  *
00483  *  @post   None.
00484  *
00485  *  @see    None.
00486  *  ============================================================================
00487  */
00488 NORMAL_API
00489 Void
00490 DSP_debug (IN  ProcessorId dspId) ;
00491 #endif /* if defined (DDSP_DEBUG) */
00492 
00493 
00494 #if defined (__cplusplus)
00495 }
00496 #endif /* defined (__cplusplus) */
00497 
00498 
00499 #endif /* !defined (DSP_H) */

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