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

msgqdefs.h

Go to the documentation of this file.
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) */

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