00001 /** ============================================================================ 00002 * @file msgqdefs.h 00003 * 00004 * @path $(DSPLINK)/gpp/inc/usr/ 00005 * 00006 * @brief Defines data types and structures used by DSP/BIOS(tm) Link for 00007 * MSGQ. 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 (MSGQDEFS_H) 00045 #define MSGQDEFS_H 00046 00047 00048 /* ----------------------------------- DSP/BIOS Link */ 00049 #include <gpptypes.h> 00050 #include <errbase.h> 00051 00052 00053 #if defined (__cplusplus) 00054 extern "C" { 00055 #endif 00056 00057 00058 /** ============================================================================ 00059 * @name MSGQ_MqtError 00060 * 00061 * @brief This type is used for identifying types of MQT async error messages. 00062 * ============================================================================ 00063 */ 00064 typedef Int16 MSGQ_MqtError ; 00065 00066 /** ============================================================================ 00067 * @name MSGQ_Id 00068 * 00069 * @brief This type is used for identifying a message queue on a specific 00070 * processor. 00071 * ============================================================================ 00072 */ 00073 typedef Uint16 MSGQ_Id ; 00074 00075 /** ============================================================================ 00076 * @name MSGQ_Queue 00077 * 00078 * @brief This type is used for identifying a message queue across processors. 00079 * ============================================================================ 00080 */ 00081 typedef Uint32 MSGQ_Queue ; 00082 00083 00084 /** ============================================================================ 00085 * @const MSGQ_INVALIDMSGQ 00086 * 00087 * @brief This constant denotes an invalid message queue. 00088 * ============================================================================ 00089 */ 00090 #define MSGQ_INVALIDMSGQ (Uint16) 0xFFFFu 00091 00092 /** ============================================================================ 00093 * @const MSGQ_INVALIDPROCID 00094 * 00095 * @brief This constant denotes an invalid processor ID. 00096 * ============================================================================ 00097 */ 00098 #define MSGQ_INVALIDPROCID (Uint16) 0xFFFFu 00099 00100 /** ============================================================================ 00101 * @const MSGQ_INTERNAL_ID_START 00102 * 00103 * @brief This constant defines the start of internal MSGQ message ID range. 00104 * ============================================================================ 00105 */ 00106 #define MSGQ_INTERNALIDSSTART (Uint16) 0xFF00u 00107 00108 /** ============================================================================ 00109 * @const MSGQ_ASYNCLOCATEMSGID 00110 * 00111 * @brief This constant defines the asynchronous locate message ID. 00112 * ============================================================================ 00113 */ 00114 #define MSGQ_ASYNCLOCATEMSGID (Uint16) 0xFF00u 00115 00116 /** ============================================================================ 00117 * @const MSGQ_ASYNCERRORMSGID 00118 * 00119 * @brief This constant defines the asynchronous error message ID. 00120 * ============================================================================ 00121 */ 00122 #define MSGQ_ASYNCERRORMSGID (Uint16) 0xFF01u 00123 00124 /** ============================================================================ 00125 * @const MSGQ_INTERNALIDSEND 00126 * 00127 * @brief This constant defines the end of internal MSGQ message ID range. 00128 * ============================================================================ 00129 */ 00130 #define MSGQ_INTERNALIDSEND (Uint16) 0xFF7fu 00131 00132 /** ============================================================================ 00133 * @const MSGQ_MQTMSGIDSSTART 00134 * 00135 * @brief This constant defines the start of transport message ID range. 00136 * ============================================================================ 00137 */ 00138 #define MSGQ_MQTMSGIDSSTART (Uint16) 0xFF80u 00139 00140 /** ============================================================================ 00141 * @const MSGQ_MQTMSGIDSEND 00142 * 00143 * @brief This constant defines the end of transport message ID range. 00144 * ============================================================================ 00145 */ 00146 #define MSGQ_MQTMSGIDSEND (Uint16) 0xFFFEu 00147 00148 /** ============================================================================ 00149 * @const MSGQ_INVALIDMSGID 00150 * 00151 * @brief This constant is used to denote no message ID value. 00152 * ============================================================================ 00153 */ 00154 #define MSGQ_INVALIDMSGID (Uint16) 0xFFFFu 00155 00156 /** ============================================================================ 00157 * @const MSGQ_MQTERROREXIT 00158 * 00159 * @brief In an asynchronous error message, this value as the error type 00160 * indicates that remote MQT has called exit. 00161 * ============================================================================ 00162 */ 00163 #define MSGQ_MQTERROREXIT (MSGQ_MqtError) -1l 00164 00165 /** ============================================================================ 00166 * @const MSGQ_MQTFAILEDPUT 00167 * 00168 * @brief In an asynchronous error message, this value as the error type 00169 * indicates that the transport failed to send a message to the remote 00170 * processor. 00171 * ============================================================================ 00172 */ 00173 #define MSGQ_MQTFAILEDPUT (MSGQ_MqtError) -2l 00174 00175 /** ============================================================================ 00176 * @const MSG_HEADER_RESERVED_SIZE 00177 * 00178 * @brief This macro defines the size of the reserved field of message header. 00179 * ============================================================================ 00180 */ 00181 #define MSG_HEADER_RESERVED_SIZE 2u 00182 00183 /** ============================================================================ 00184 * @macro IS_VALID_MSGQ 00185 * 00186 * @brief Is the MSGQ valid. 00187 * ============================================================================ 00188 */ 00189 #define IS_VALID_MSGQ(msgq) (msgq != MSGQ_INVALIDMSGQ) 00190 00191 00192 /** ============================================================================ 00193 * @name MsgqPend 00194 * 00195 * @brief Defines the types for the pend function. 00196 * 00197 * @param notifyHandle 00198 * Pointer to the notification object for the message queue. 00199 * @param timeout 00200 * Timeout Value. 00201 * 00202 * @return DSP_SOK 00203 * Operation successfully completed. 00204 * SYNC_E_FAIL 00205 * General error from GPP-OS. 00206 * DSP_ETIMEOUT 00207 * Timeout occured while performing operation. 00208 * DSP_EPOINTER 00209 * Invalid pointer passed. 00210 * ============================================================================ 00211 */ 00212 typedef DSP_STATUS (*MsgqPend) (Pvoid notifyHandle, Uint32 timeout) ; 00213 00214 00215 /** ============================================================================ 00216 * @name MsgqPost 00217 * 00218 * @brief Defines the types for the post function. 00219 * 00220 * @param notifyHandle 00221 * Pointer to the notification object for the message queue. 00222 * 00223 * @return DSP_SOK 00224 * Operation successfully completed. 00225 * SYNC_E_FAIL 00226 * General error from GPP-OS. 00227 * DSP_EPOINTER 00228 * Invalid pointer passed. 00229 * DSP_EMEMORY 00230 * Operation failed due to memory error. 00231 * ============================================================================ 00232 */ 00233 typedef DSP_STATUS (*MsgqPost) (Pvoid notifyHandle) ; 00234 00235 00236 /** ============================================================================ 00237 * @name MSGQ_Attrs 00238 * 00239 * @brief This structure defines the attributes required during opening of 00240 * the MSGQ. 00241 * 00242 * @param notifyHandle 00243 * Pointer to the notification object for the message queue. 00244 * @param pend 00245 * Function to be used to wait to receive a message. 00246 * @param post 00247 * Function to be used to indicate arrival of a message. 00248 * ============================================================================ 00249 */ 00250 typedef struct MSGQ_Attrs_tag { 00251 Pvoid notifyHandle ; 00252 MsgqPend pend ; 00253 MsgqPost post ; 00254 } MSGQ_Attrs ; 00255 00256 /** ============================================================================ 00257 * @name PCPYMQT_Attrs 00258 * 00259 * @brief This structure defines the attributes for initialization of the 00260 * PCPY MQT. 00261 * 00262 * @param poolId 00263 * Pool ID used for allocating control messages. 00264 * This pool is also used in case the ID within the message 00265 * received from the DSP is invalid. 00266 * ============================================================================ 00267 */ 00268 typedef struct PCPYMQT_Attrs_tag { 00269 PoolId poolId ; 00270 } PCPYMQT_Attrs ; 00271 00272 /** ============================================================================ 00273 * @name ZCPYMQT_Attrs 00274 * 00275 * @brief This structure defines the attributes for initialization of the 00276 * ZCPY MQT. 00277 * 00278 * @param poolId 00279 * Pool ID used for allocating control messages. 00280 * ============================================================================ 00281 */ 00282 typedef struct ZCPYMQT_Attrs_tag { 00283 PoolId poolId ; 00284 } ZCPYMQT_Attrs ; 00285 00286 /** ============================================================================ 00287 * @name DCPYMQT_Attrs 00288 * 00289 * @brief This structure defines the attributes for initialization of the 00290 * DCPY MQT. 00291 * 00292 * @param poolId 00293 * Pool ID used for allocating control messages. 00294 * ============================================================================ 00295 */ 00296 typedef struct DCPYMQT_Attrs_tag { 00297 PoolId poolId ; 00298 } DCPYMQT_Attrs ; 00299 00300 /** ============================================================================ 00301 * @name MSGQ_LocateAttrs 00302 * 00303 * @brief This structure defines the attributes required during synchronous 00304 * location of a MSGQ. 00305 * 00306 * @param timeout 00307 * Timeout value in milliseconds for the locate calls. 00308 * ============================================================================ 00309 */ 00310 typedef struct MSGQ_LocateAttrs_tag { 00311 Uint32 timeout ; 00312 } MSGQ_LocateAttrs ; 00313 00314 /** ============================================================================ 00315 * @name MSGQ_LocateAsyncAttrs 00316 * 00317 * @brief This structure defines the attributes required during asynchronous 00318 * location of a MSGQ. 00319 * 00320 * @param poolId 00321 * ID of the pool to be used for allocating async locate messages. 00322 * @param arg 00323 * User-defined argument returned with an async locate message. 00324 * ============================================================================ 00325 */ 00326 typedef struct MSGQ_LocateAsyncAttrs_tag { 00327 PoolId poolId ; 00328 Pvoid arg ; 00329 } MSGQ_LocateAsyncAttrs ; 00330 00331 /** ============================================================================ 00332 * @name MSGQ_MsgHeader 00333 * 00334 * @brief This structure defines the format of the message header that must be 00335 * the first field of any message. 00336 * 00337 * @param reserved 00338 * Reserved for use by the MQT. The MQT typically uses them as a 00339 * link for queuing the messages. 00340 * @param srcProcId 00341 * Processor Id for the source message queue 00342 * @param poolId 00343 * ID of the Pool used for allocating this message. 00344 * @param size 00345 * Size of the message including the header. 00346 * @param dstId 00347 * ID of the destination message queue. 00348 * @param srcId 00349 * ID of the source message queue for reply. 00350 * @param msgId 00351 * User-specified message ID. 00352 * ============================================================================ 00353 */ 00354 typedef struct MSGQ_MsgHeader_tag { 00355 Uint32 reserved [MSG_HEADER_RESERVED_SIZE] ; 00356 Uint16 srcProcId ; 00357 Uint16 poolId ; 00358 Uint16 size ; 00359 Uint16 dstId ; 00360 Uint16 srcId ; 00361 Uint16 msgId ; 00362 } MSGQ_MsgHeader ; 00363 00364 /** ============================================================================ 00365 * @name MSGQ_AsyncLocateMsg 00366 * 00367 * @brief This structure defines the asynchronous locate message format. 00368 * 00369 * @param header 00370 * Fixed message header required for all messages. 00371 * @param msgqQueue 00372 * Reply message queue specified during MSGQ_locateAsync (). 00373 * @param arg 00374 * User-defined argument specified as part of the 00375 * MSGQ_LocateAsyncAttrs 00376 * ============================================================================ 00377 */ 00378 typedef struct MSGQ_AsyncLocateMsg_tag { 00379 MSGQ_MsgHeader header ; 00380 MSGQ_Queue msgqQueue ; 00381 Pvoid arg ; 00382 } MSGQ_AsyncLocateMsg ; 00383 00384 /** ============================================================================ 00385 * @name MSGQ_AsyncErrorMsg 00386 * 00387 * @brief This structure defines the asynchronous error message format. 00388 * 00389 * @param header 00390 * Fixed message header required for all messages. 00391 * @param errorType 00392 * Type of error. 00393 * @param arg1 00394 * First argument dependent on the error type. 00395 * MSGQ_MQTERROREXIT : Processor ID of the transport. 00396 * MSGQ_MQTFAILEDPUT : Handle of the destination message queue on 00397 * which the put failed. 00398 * @param arg2 00399 * Second argument dependent on the error type. 00400 * MSGQ_MQTERROREXIT : Not used. 00401 * MSGQ_MQTFAILEDPUT : Status of the MSGQ_put () call that failed. 00402 * ============================================================================ 00403 */ 00404 typedef struct MSGQ_AsyncErrorMsg_tag { 00405 MSGQ_MsgHeader header ; 00406 MSGQ_MqtError errorType ; 00407 Pvoid arg1 ; 00408 Pvoid arg2 ; 00409 } MSGQ_AsyncErrorMsg ; 00410 00411 /** ============================================================================ 00412 * @name MSGQ_Msg 00413 * 00414 * @brief This is the type of any buffer used for messaging. 00415 * ============================================================================ 00416 */ 00417 typedef MSGQ_MsgHeader * MSGQ_Msg ; 00418 00419 /** ============================================================================ 00420 * @name MQT_Interface 00421 * 00422 * @brief Forward declaration of MQT interface table. 00423 * ============================================================================ 00424 */ 00425 typedef struct MQT_Interface_tag MQT_Interface ; 00426 00427 00428 /** ============================================================================ 00429 * @deprecated The deprecated data structure MsgqMqtError has been replaced 00430 * with MSGQ_MqtError 00431 * 00432 * ============================================================================ 00433 */ 00434 #define MsgqMqtError MSGQ_MqtError 00435 00436 /** ============================================================================ 00437 * @deprecated The deprecated data structure MsgqId has been replaced 00438 * with MSGQ_Id 00439 * 00440 * ============================================================================ 00441 */ 00442 #define MsgqId MSGQ_Id 00443 00444 /** ============================================================================ 00445 * @deprecated The deprecated data structure MsgqQueue has been replaced 00446 * with MSGQ_Queue 00447 * 00448 * ============================================================================ 00449 */ 00450 #define MsgqQueue MSGQ_Queue 00451 00452 /** ============================================================================ 00453 * @deprecated The deprecated data structure MsgqAttrs has been replaced 00454 * with MSGQ_Attrs 00455 * 00456 * ============================================================================ 00457 */ 00458 #define MsgqAttrs MSGQ_Attrs 00459 00460 /** ============================================================================ 00461 * @deprecated The deprecated data structure PcpyMqtAttrs has been replaced 00462 * with PCPYMQT_Attrs 00463 * 00464 * ============================================================================ 00465 */ 00466 #define PcpyMqtAttrs PCPYMQT_Attrs 00467 00468 /** ============================================================================ 00469 * @deprecated The deprecated data structure ZcpyMqtAttrs has been replaced 00470 * with ZCPYMQT_Attrs 00471 * 00472 * ============================================================================ 00473 */ 00474 #define ZcpyMqtAttrs ZCPYMQT_Attrs 00475 00476 /** ============================================================================ 00477 * @deprecated The deprecated data structure DcpyMqtAttrs has been replaced 00478 * with DCPYMQT_Attrs 00479 * 00480 * ============================================================================ 00481 */ 00482 #define DcpyMqtAttrs DCPYMQT_Attrs 00483 00484 /** ============================================================================ 00485 * @deprecated The deprecated data structure MSGQ_LocateAttrs has been replaced 00486 * with MSGQ_LocateAttrs 00487 * 00488 * ============================================================================ 00489 */ 00490 #define MsgqLocateAttrs MSGQ_LocateAttrs 00491 00492 /** ============================================================================ 00493 * @deprecated The deprecated data structure MSGQ_LocateAsyncAttrs has been 00494 * replaced with MSGQ_LocateAsyncAttrs 00495 * 00496 * ============================================================================ 00497 */ 00498 #define MsgqLocateAsyncAttrs MSGQ_LocateAsyncAttrs 00499 00500 /** ============================================================================ 00501 * @deprecated The deprecated data structure MsgqMsgHeader has been replaced 00502 * with MSGQ_MsgHeader 00503 * 00504 * ============================================================================ 00505 */ 00506 #define MsgqMsgHeader MSGQ_MsgHeader 00507 00508 /** ============================================================================ 00509 * @deprecated The deprecated data structure MSGQ_AsyncLocateMsg has been 00510 * replaced with MSGQ_AsyncLocateMsg 00511 * 00512 * ============================================================================ 00513 */ 00514 #define MsgqAsyncLocateMsg MSGQ_AsyncLocateMsg 00515 00516 /** ============================================================================ 00517 * @deprecated The deprecated data structure MsgqAsyncErrorMsg has been 00518 * replaced with MSGQ_AsyncErrorMsg 00519 * 00520 * ============================================================================ 00521 */ 00522 #define MsgqAsyncErrorMsg MSGQ_AsyncErrorMsg 00523 00524 /** ============================================================================ 00525 * @deprecated The deprecated data structure MsgqMsg has been replaced 00526 * with MSGQ_Msg 00527 * 00528 * ============================================================================ 00529 */ 00530 #define MsgqMsg MSGQ_Msg 00531 00532 /** ============================================================================ 00533 * @deprecated The deprecated data structure MqtInterface has been replaced 00534 * with MQT_Interface 00535 * 00536 * ============================================================================ 00537 */ 00538 #define MqtInterface MQT_Interface 00539 00540 00541 #if defined (__cplusplus) 00542 } 00543 #endif 00544 00545 00546 #endif /* !defined (MSGQDEFS_H) */