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) */