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