1    /* --COPYRIGHT--,BSD
     2     * Copyright (c) $(CPYYEAR), Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * --/COPYRIGHT--*/
    32    
    33    /*
    34     * ======== UIAPacket.xdc ========
    35     */
    36    package ti.uia.runtime;
    37    
    38    import ti.uia.runtime.IUIATransfer;
    39    
    40    /*!
    41     * ======== UIAPacket ========
    42     * Packet format communications between instrumentation clients
    43     * and instrumentation endpoints
    44     */
    45    @CustomHeader
    46    module UIAPacket {
    47    
    48        /*!
    49         * ======== Hdr ========
    50         *  UIAPacket Header
    51         *
    52         *  The following is a breakdown of the packet header based on type packet.
    53         *
    54         *  The packet header is always sent in network byte (big endian) order.
    55         *
    56         *  The top 4 leftmost bits of word1 denote what type of packet this is:
    57         *  HdrType_Msg or HdrType_EventPkt. The contents of the packet depends on
    58         *  this type.
    59         *
    60         *  @p(code)
    61         *
    62         *  HdrType_Msg word1
    63         *   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
    64         *   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
    65         *  |---------------------------------------------------------------|
    66         *  |H H H H|E|L L L L L L L L L L L|T T T T|S S S S S S S S S S S S|
    67         *  |---------------------------------------------------------------|
    68         *
    69         *  H = HdrType         (4-bits)
    70         *  E = Payload endian  (1-bit)
    71         *  L = Message Length  (11-bits)
    72         *  T = Message Type    (4-bits)
    73         *  S = Service Id      (12-bits)
    74         *
    75         *  HdrType_Msg word2
    76         *   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
    77         *   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
    78         *  |---------------------------------------------------------------|
    79         *  |S S S S S S S S S S S S S S S S|C C C C C C C C C C C C C C C C|
    80         *  |---------------------------------------------------------------|
    81         *
    82         *  S = Sequence Number (16-bits)
    83         *  C = Command Id      (16-bits)
    84         *
    85         *  HdrType_Msg word3
    86         *   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
    87         *   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
    88         *  |---------------------------------------------------------------|
    89         *  |T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T|
    90         *  |---------------------------------------------------------------|
    91         *
    92         *  T - Tag             (32-bits)
    93         *
    94         *  HdrType_Msg word4
    95         *   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
    96         *   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
    97         *  |---------------------------------------------------------------|
    98         *  |D D D D D D D D D D D D D D D D|S S S S S S S S S S S S S S S S|
    99         *  |---------------------------------------------------------------|
   100         *
   101         *  D - Destination Address (16-bits)
   102         *  S - Source Address      (16-bits)
   103         *
   104         *  HdrType_EventPkt word1
   105         *   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
   106         *   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
   107         *  |---------------------------------------------------------------|
   108         *  |H H H H|E|L L L L L L L L L L L L L L L L L L L L L L L L L L L|
   109         *  |---------------------------------------------------------------|
   110         *
   111         *  H = HdrType         (4-bits)
   112         *  E = Payload endian   (1-bit)
   113         *  L = Event Length   (27-bits)
   114         *
   115         *  HdrType_EventPkt word2
   116         *   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
   117         *   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
   118         *  |---------------------------------------------------------------|
   119         *  |S S S S S S S S S S S S S S S S|R R R R R R R R R R R R R R|P P|
   120         *  |---------------------------------------------------------------|
   121         *
   122         *  S = Sequence Number              (16-bits)
   123         *  R = Reserved                     (14-bits)
   124         *  P = Priority: Normal=0, High > 0 (2-bits)
   125         *
   126         *  HdrType_EventPkt word3
   127         *   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
   128         *   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
   129         *  |---------------------------------------------------------------|
   130         *  |D I I I I I I I I I I I I I I I M M M M M M M M M M M M M M M M|
   131         *  |---------------------------------------------------------------|
   132         *
   133         *  D ? wasLoggerDynamicallyCreated  (1-bit:  0 = statically created, 
   134         *                                            1 = dynamically created )
   135         *  I - Logger Instance ID           (15-bits)
   136         *  M - Logger Module ID             (16-bits)
   137         *
   138         *  HdrType_EventPkt word4
   139         *   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
   140         *   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
   141         *  |---------------------------------------------------------------|
   142         *  |D D D D D D D D D D D D D D D D|S S S S S S S S S S S S S S S S|
   143         *  |---------------------------------------------------------------|
   144         *
   145         *  D - Destination Address (16-bits)
   146         *  S - Source Address      (16-bits)
   147         *
   148         *  @p
   149         *
   150         */
   151        struct Hdr {
   152            Bits32 word1;
   153            Bits32 word2;
   154            Bits32 word3;
   155            Bits32 word4;
   156        };
   157    
   158        /*!
   159         * ======== HdrType ========
   160         * Enumeration of the various types of packet
   161         * headers.  Stored in a 4 bit bitfield (b31-b28) of the first word in the 
   162         * packet.
   163         */
   164        enum HdrType {
   165            HdrType_Reserved0 = 0, /*! reserved for future use */
   166            HdrType_Reserved1 = 1, /*! reserved for future use */
   167            HdrType_Reserved2 = 2, /*! reserved for future use  */
   168            HdrType_Reserved3 = 3, /*! reserved for future use */
   169            HdrType_Reserved4 = 4, /*! reserved for future use  */
   170            HdrType_Reserved5 = 5, /*! reserved for future use */
   171            HdrType_Reserved6 = 6, /*! reserved for future use */
   172            HdrType_Reserved7 = 7, /*! reserved for future use */
   173            HdrType_ChannelizedData = 8, /*! Channelized data stream */
   174            HdrType_Msg = 9, /*! Message  (4 words header, 1 word footer) */
   175            HdrType_EventPkt = 10, /*! Event rec. containing multiple events: 
   176                                      (4 word hdr, 1 word footer) */
   177            HdrType_CPUTrace = 11, /*! CPU Trace ETB data 
   178                                       (4 word hdr, 1 word footer) */
   179            HdrType_STMTrace = 12, /*! STM Trace ETB data 
   180                                       (4 word hdr, 1 word footer) */
   181            HdrType_USER1 = 13, /*! User defined header type 1 */
   182            HdrType_USER2 = 14, /*! User defined header type 2 */
   183            HdrType_USER3 = 15  /*! User defined header type 3 */
   184        };
   185        
   186        /*!
   187         * ======== PayloadEndian ========
   188         * Enumeration of payload endianness
   189         */
   190        enum PayloadEndian {
   191            PayloadEndian_LITTLE = 0, 
   192            PayloadEndian_BIG = 1
   193        };
   194        
   195        /*!
   196         * ======== Footer ========
   197         * Packet Footer
   198         *
   199         * The packet footer is always in network byte order
   200         * i.e. big-endian byte ordering
   201         */
   202        struct Footer
   203        {
   204                Int32 word1;        /*! 16 MSBs contain msg length in Bytes, 
   205                                        16 LSBs contain 0x7777 */
   206        }
   207    
   208        /*!
   209         * ======== MsgType ========
   210         * Message Types
   211         *
   212         * Enumeration of the various types of packets.
   213         * Stored in a 4 bit bitfield.
   214         *
   215         * MsgType_ACK:
   216         * Each packet of type CMD or DATA is immediately acknowledged by
   217         * sending either an ACK reply (if the packet can be processed),
   218         * a RESULT or PARTIALRESULT reply (if requested data can be provided
   219         * immediately) or a NACK reply (if the packet cannot be processed).
   220         * The Service that receives the command is responsible for sending
   221         * the ACK or NACK.  If the requested service is not available, the
   222         * Endpoint is responsible for sending the NACK packet.
   223         *
   224         * MsgType_CMD:
   225         * CMD packets are typically sent from the host to the target.
   226         * The receiving endpoint routes the command to the service
   227         * identified in the Service Id field.
   228         *
   229         * MsgType_RESULT:
   230         * RESULT replies are sent along with any requested data.
   231         * If the Service cannot reply with the requested data immediately,
   232         * it should return with an ACK packet and send a RESULT packet
   233         * that echoes the header info of the original command.
   234         *
   235         * MsgType_PARTIALRESULT:
   236         * PARTIALRESULT replies are sent along with any requested data when the
   237         * requested action can only be partly fulfilled.  Examples are when the
   238         * service is reporting on some ongoing operation or has been requested
   239         * to periodically poll some data value.
   240         *
   241         * MsgType_EVENT:
   242         * EVENT packets are sent to all interested parties in order to notify them
   243         * about state changes.   They can, for example, be used to report an error
   244         * that has occurred which may impact the ability of the target to continue
   245         * operating normally.
   246         *
   247         * MsgType_FLOWCTRL
   248         * FLOWCTRL packets are provided for TCF compliance.  They are used to avoid
   249         * flooding of communication links.  In response, endpoints can either 
   250         * increase or decrease rate of packets sent, although this is only loosely 
   251         * defined. TCF services are not directly concerned with flow control.
   252         * The data passed with FLOWCTRL packets reports the traffic congestion level
   253         * as an integer between -100 and 100, where 0 = "optimal load"
   254         *
   255         * MsgType_DATA
   256         * DATA packets are used for sending event log data and other streams of data.
   257         * Details about how this will be used are being worked out to ensure alignment
   258         * with BIOS RTA Log Servers.
   259         *
   260         * MsgType_NACK_BAD_DATA:
   261         * Negative Acknowledge due to bad data.  Sent in response to a command that 
   262         * had invalid data in the body of the packet.  The original data is echoed 
   263         * in the NACK response.
   264         *
   265         * MsgType_NACK_WITH_ERROR_CODE
   266         * Negative Acknowledge with Error Code. Sent along with an error code in 
   267         * the first word of the body of the reply that describes the error that was
   268         * encountered
   269         */
   270        enum MsgType {
   271            MsgType_ACK=0, /*! Reply acknowledging receipt of CMD or DATA packet */
   272            MsgType_CMD=1, /*! Command packets              */
   273            MsgType_RESULT=2, /*! Result reply                */
   274            MsgType_PARTIALRESULT=3, /*! Partial result reply */
   275            MsgType_NOTIFY=4, /*! Notify messaage (equiv. to the EVENT packet in TCF) */
   276            MsgType_FLOWCTRL=5, /*! Flow control packet      */
   277            MsgType_DATA=6, /*! Data packet (used for streaming data to host) */
   278            MsgType_RESERVED7,
   279            MsgType_RESERVED8,
   280            MsgType_RESERVED9,
   281            MsgType_RESERVED10,
   282            MsgType_RESERVED11,
   283            MsgType_RESERVED12,
   284            MsgType_RESERVED13,
   285            MsgType_NACK_BAD_DATA=14, /*! Negative Acknowledge due to bad data */
   286            MsgType_NACK_WITH_ERROR_CODE=15 /*! Negative Acknowledge -
   287                                                error code in msg body */
   288        };
   289    
   290        /*!
   291         * ======== NACKErrorCode ========
   292         * Message Negative Acknowledge Error Codes
   293         *
   294         * Stored in the first 32b word of the data body of the packet
   295         * in Network Byte Order
   296         */
   297        enum NACKErrorCode {
   298            NACKErrorCode_NO_REASON_SPECIFIED=0, /*! Use this when none of the 
   299                                                     defined NACK error codes are 
   300                                                     appropriate */
   301            NACKErrorCode_SERVICE_NOT_SUPPORTED=1, /*! A module that handles the 
   302                                                       requested Service Id could 
   303                                                       not be found */
   304            NACKErrorCode_CMD_NOT_SUPPORTED=2, /*! The service does not support the 
   305                                                   specified Command Id */
   306            NACKErrorCode_QUEUE_FULL=3, /*! Cmd couldn't be passed on to dest. end
   307                                            point due to a queue full condition */
   308            NACKErrorCode_BAD_ENDPOINT_ADDRESS=4, /*! The destination end point 
   309                                                      address does not exists */
   310            NACKErrorCode_BAD_MESSAGE_LENGTH=5 /*! packet lenght > endpoint max. 
   311                                                   msg length or not what is 
   312                                                   required to service the cmd  */
   313        };
   314        
   315        /*!
   316         *  ======== HOST ========
   317         *  The address of the host
   318         *
   319         *  The host address is always 0xFFFF. 
   320         */
   321        const UInt16 HOST = 0xFFFF;
   322        
   323        /*!
   324         *  ======== BROADCAST ========
   325         *  Used to denote a broadcast message
   326         *
   327         *  The broadcast address is always 0xFFFE. 
   328         */
   329        const UInt16 BROADCAST = 0xFFFE;
   330    
   331        /*!
   332         * ========= maxPktLengthInBytes =========
   333         * maximum number of bytes a packet can contain
   334         *
   335         * used to limit the amount of memory needed by the
   336         * packet factories in order to handle a new packet
   337         */
   338        config Int maxPktLengthInBytes = 128;
   339    
   340        /*
   341         * See section 8.2.2 of spru187n.pdf for info on bitfield packing and 
   342         * endianness. For big-endian mode, bit fields are packed into registers 
   343         * from most significant bit (MSB) to least significant bit (LSB) in the 
   344         * order in which they are defined. Bit fields are packed in memory from 
   345         * most significant byte (MSbyte) to least significant byte (LSbyte). 
   346         * For little-endian mode, bit fields are packed into registers from
   347         * the LSB to the MSB in the order in which they are defined, and packed 
   348         * in memory from LSbyte to MSbyte.
   349         *
   350         * In general, different compilers will handle bitfields in different \
   351         * (i.e. incompatible)ways.  To overcome this, the header is treated as 
   352         * an array of 32b words, and the bitfields are accessed via macros that 
   353         * handle the masking and shifting operations needed to insert or extract 
   354         * the information from the relevant bitfields
   355         */
   356    
   357         /*!
   358          * ======== swizzle ========
   359          * returns the value in big endian format
   360          */
   361        @Macro Bits32 swizzle(Bits32 value);
   362    
   363         /*!
   364          * ======== swizzle ========
   365          * returns the value in big endian format
   366          */
   367        @Macro Bits16 swizzle16(Bits16 value);
   368    
   369        /*!
   370         *  ======== getHdrType ========
   371         *  gets the packet header type from the packet header
   372         *
   373         *  Message header is always layed out as big endian (network order).
   374         *  This macro is designed to work on both little endian and
   375         *  big endian targets, since 32b long words are consistently
   376         *  handled for both endianness - it is only when converting
   377         *  from bytes to longs that bit orders get swapped.
   378         *  #ifdef xdc_target__bigEndian can be used if necessary.
   379         *
   380         *  @param(Hdr* msgHdr)   pointer to the packet header
   381         */
   382        @Macro HdrType getHdrType(Hdr *pHdr);
   383    
   384        /*!
   385         *  ======== setHdrType ========
   386         *  sets the header type in the packet header
   387         *
   388         *  Message header is always layed out as big endian (network order).
   389         *  This macro is designed to work on both little endian and
   390         *  big endian targets, since 32b long words are consistently
   391         *  handled for both endianness - it is only when converting
   392         *  from bytes to longs that bit orders get swapped.
   393         *  #ifdef xdc_target__bigEndian can be used if necessary.
   394         *
   395         *  @param(Hdr* msgHdr)   pointer to the packet header
   396         *  @param(HdrType hdrType) the new header type
   397         */
   398        @Macro Void setHdrType(Hdr *pHdr, HdrType hdrType);
   399    
   400        /*!
   401         *  ======== getPayloadEndianness ========
   402         *  gets the payload endianness bit from the packet header
   403         *
   404         *  Message header is always layed out as big endian (network order).
   405         *  This macro is designed to work on both little endian and
   406         *  big endian targets, since 32b long words are consistently
   407         *  handled for both endianness - it is only when converting
   408         *  from bytes to longs that bit orders get swapped.
   409         *  #ifdef xdc_target__bigEndian can be used if necessary.
   410         *
   411         *  @param(Hdr* msgHdr)   pointer to the packet header
   412         */
   413        @Macro Bits32 getPayloadEndianness(Hdr *pHdr);
   414        
   415        /*!
   416         *  ======== setPayloadEndianness ========
   417         *  sets the payload endianness bit from the packet header
   418         *
   419         *  Message header is always layed out as big endian (network order).
   420         *  This macro is designed to work on both little endian and
   421         *  big endian targets, since 32b long words are consistently
   422         *  handled for both endianness - it is only when converting
   423         *  from bytes to longs that bit orders get swapped.
   424         *  #ifdef xdc_target__bigEndian can be used if necessary.
   425         *
   426         *  @param(Hdr* msgHdr)   pointer to the packet header
   427         *  @param(Hdr* msgHdr)   Endianness of the payload
   428         */
   429        @Macro Bits32 setPayloadEndianness(Hdr *pHdr, PayloadEndian endianess);
   430    
   431        /*!
   432         *  ======== getMsgLength ========
   433         *  gets the packet length (in bytes) from the packet header
   434         *
   435         *  Message header is always layed out as big endian (network order).
   436         *  This macro is designed to work on both little endian and
   437         *  big endian targets, since 32b long words are consistently
   438         *  handled for both endianness - it is only when converting
   439         *  from bytes to longs that bit orders get swapped.
   440         *  #ifdef xdc_target__bigEndian can be used if necessary.
   441         *
   442         *  @param(Hdr* msgHdr)   pointer to the packet header
   443         */
   444        @Macro Int32 getMsgLength(Hdr *pHdr);
   445    
   446        /*!
   447         *  ======== setMsgLength ========
   448         *  sets the packet length (in bytes) from the packet header
   449         *
   450         *  Message header is always layed out as big endian (network order).
   451         *  This macro is designed to work on both little endian and
   452         *  big endian targets, since 32b long words are consistently
   453         *  handled for both endianness - it is only when converting
   454         *  from bytes to longs that bit orders get swapped.
   455         *  #ifdef xdc_target__bigEndian can be used if necessary.
   456         *
   457         *  @param(Hdr* msgHdr)   pointer to the packet header
   458         *  @param(pktLength) the new packet length
   459         *
   460         */
   461        @Macro Void setMsgLength(Hdr *pHdr, UInt16 pktLength);
   462    
   463        /*!
   464         *  ======== getEventLength ========
   465         *  Gets the packet length (in bytes) from the packet header
   466         *
   467         *  Includes the packet header
   468         *
   469         *  @param(Hdr* msgHdr)   pointer to the packet header
   470         */
   471        @Macro Int32 getEventLength(Hdr *pHdr);
   472    
   473        /*!
   474         *  ======== setEventLength ========
   475         *  Sets the packet length (in bytes) from the packet header
   476         *
   477         *  Includes the packet header
   478         *
   479         *  @param(Hdr* msgHdr)   pointer to the packet header
   480         *  @param(pktLength) the new packet length
   481         *
   482         */
   483        @Macro Void setEventLength(Hdr *pHdr, Bits32 pktLength);
   484    
   485        /*!
   486         *  ======== getLength ========
   487         *  Gets the packet length (in bytes) from the packet header
   488         *
   489         *  Includes the packet header
   490         *
   491         *  @param(Hdr* msgHdr)   pointer to the packet header
   492         */
   493        Int32 getLength(Hdr *pHdr);
   494    
   495        /*!
   496         *  ======== getSequenceCount ========
   497         *  gets the sequence count from the packet header
   498         *
   499         *  Message header is always layed out as big endian (network order).
   500         *  This macro is designed to work on both little endian and
   501         *  big endian targets, since 32b long words are consistently
   502         *  handled for both endianness - it is only when converting
   503         *  from bytes to longs that bit orders get swapped.
   504         *  #ifdef xdc_target__bigEndian can be used if necessary.
   505         *
   506         *  @param(Hdr* msgHdr)   pointer to the packet header
   507         */
   508        @Macro UInt16 getSequenceCount(Hdr *pHdr);
   509    
   510        /*!
   511         *  ======== setSequenceCount ========
   512         *  sets the sequence count in the packet header
   513         *
   514         *  Message header is always layed out as big endian (network order).
   515         *  This macro is designed to work on both little endian and
   516         *  big endian targets, since 32b long words are consistently
   517         *  handled for both endianness - it is only when converting
   518         *  from bytes to longs that bit orders get swapped.
   519         *  #ifdef xdc_target__bigEndian can be used if necessary.
   520         *
   521         *  @param(Hdr* msgHdr)   pointer to the packet header
   522         *  @param(seqCount) the new packet sequence count
   523         */
   524        @Macro Void setSequenceCount(Hdr *pHdr, Bits16 seqCount);
   525    
   526        /*! @_nodoc
   527         *  ======== getLoggerPriority ========
   528         *  gets the logger priority field from the event packet header
   529         *
   530         *  Message header is always layed out as big endian (network order).
   531         *  This macro is designed to work on both little endian and
   532         *  big endian targets, since 32b long words are consistently
   533         *  handled for both endianness - it is only when converting
   534         *  from bytes to longs that bit orders get swapped.
   535         *  #ifdef xdc_target__bigEndian can be used if necessary.
   536         *
   537         *  @param(Hdr* msgHdr)   pointer to the packet header
   538         *  @a(return) the priority of the logger that logged the events
   539         *  @see IUIATransfer#Priority
   540         */
   541        @Macro IUIATransfer.Priority getLoggerPriority(Hdr *pHdr);
   542    
   543        /*! @_nodoc
   544         *  ======== setLoggerPriority ========
   545         *  sets the logger priority field in the event packet header
   546         *
   547         *  Message header is always layed out as big endian (network order).
   548         *  This macro is designed to work on both little endian and
   549         *  big endian targets, since 32b long words are consistently
   550         *  handled for both endianness - it is only when converting
   551         *  from bytes to longs that bit orders get swapped.
   552         *  #ifdef xdc_target__bigEndian can be used if necessary.
   553         *
   554         *  @param(Hdr* msgHdr)   pointer to the packet header
   555         *  @param(priority) the logger priority ( @see IUIATransfer#Priority )
   556         */
   557        @Macro Void setLoggerPriority(Hdr *pHdr, IUIATransfer.Priority priority);
   558        /*!
   559         *  ======== getLoggerModuleId ========
   560         *  gets the logger ID from the event packet header
   561         *
   562         *  Message header is always layed out as big endian (network order).
   563         *  This macro is designed to work on both little endian and
   564         *  big endian targets, since 32b long words are consistently
   565         *  handled for both endianness - it is only when converting
   566         *  from bytes to longs that bit orders get swapped.
   567         *  #ifdef xdc_target__bigEndian can be used if necessary.
   568         *
   569         *  @param(Hdr* msgHdr)   pointer to the packet header
   570         */
   571        @Macro Bits16 getLoggerModuleId(Hdr *pHdr);
   572    
   573        /*!
   574         *  ======== setLoggerModuleId ========
   575         *  sets the module ID in the event packet header
   576         *
   577         *  Message header is always layed out as big endian (network order).
   578         *  This macro is designed to work on both little endian and
   579         *  big endian targets, since 32b long words are consistently
   580         *  handled for both endianness - it is only when converting
   581         *  from bytes to longs that bit orders get swapped.
   582         *  #ifdef xdc_target__bigEndian can be used if necessary.
   583         *
   584         *  @param(Hdr* msgHdr)   pointer to the packet header
   585         *  @param(loggerModuleId) the moduleID of the logger that logged the events 
   586         */
   587        @Macro Void setLoggerModuleId(Hdr *pHdr, Bits16 loggerModuleId);
   588    
   589        /*!
   590         *  ======== getLoggerInstanceId ========
   591         *  gets the logger instance ID from the event packet header
   592         *
   593         *  Message header is always layed out as big endian (network order).
   594         *  This macro is designed to work on both little endian and
   595         *  big endian targets, since 32b long words are consistently
   596         *  handled for both endianness - it is only when converting
   597         *  from bytes to longs that bit orders get swapped.
   598         *  #ifdef xdc_target__bigEndian can be used if necessary.
   599         *
   600         *  @param(Hdr* msgHdr)   pointer to the packet header
   601         */
   602        @Macro Bits16 getLoggerInstanceId(Hdr *pHdr);
   603    
   604        /*!
   605         *  ======== setLoggerInstanceId ========
   606         *  sets the sequence count in the packet header
   607         *
   608         *  Message header is always layed out as big endian (network order).
   609         *  This macro is designed to work on both little endian and
   610         *  big endian targets, since 32b long words are consistently
   611         *  handled for both endianness - it is only when converting
   612         *  from bytes to longs that bit orders get swapped.
   613         *  #ifdef xdc_target__bigEndian can be used if necessary.
   614         *
   615         *  @param(Hdr* msgHdr)   pointer to the packet header
   616         *  @param(seqCount) the new packet sequence count
   617         */
   618        @Macro Void setLoggerInstanceId(Hdr *pHdr, Bits16 loggerInstanceId);
   619        
   620        /*!
   621         *  ======== getMsgType ========
   622         *  gets the packet type from the packet header
   623         *
   624         *  Message header is always layed out as big endian (network order).
   625         *  This macro is designed to work on both little endian and
   626         *  big endian targets, since 32b long words are consistently
   627         *  handled for both endianness - it is only when converting
   628         *  from bytes to longs that bit orders get swapped.
   629         *  #ifdef xdc_target__bigEndian can be used if necessary.
   630         *
   631         *  @param(Hdr* pHdr)   pointer to the packet header
   632         */
   633        @Macro MsgType getMsgType(Hdr *pHdr);
   634    
   635        /*!
   636         *  ======== setMsgType ========
   637         *  sets the packet type in the packet header
   638         *
   639         *  Message header is always layed out as big endian (network order).
   640         *  This macro is designed to work on both little endian and
   641         *  big endian targets, since 32b long words are consistently
   642         *  handled for both endianness - it is only when converting
   643         *  from bytes to longs that bit orders get swapped.
   644         *  #ifdef xdc_target__bigEndian can be used if necessary.
   645         *
   646         *  @param(Hdr* msgHdr)   pointer to the packet header
   647         *  @param(msgType) the new packet type
   648         */
   649        @Macro Void setMsgType(Hdr *pHdr, MsgType msgType);
   650    
   651        /*!
   652         *  ======== getCmdId ========
   653         *  gets the packet type from the packet header
   654         *
   655         *  Message header is always layed out as big endian (network order).
   656         *  This macro is designed to work on both little endian and
   657         *  big endian targets, since 32b long words are consistently
   658         *  handled for both endianness - it is only when converting
   659         *  from bytes to longs that bit orders get swapped.
   660         *  #ifdef xdc_target__bigEndian can be used if necessary.
   661         *
   662         *  @param(Hdr* msgHdr)   pointer to the packet header
   663         */
   664        @Macro UInt16 getCmdId(Hdr *pHdr);
   665    
   666        /*!
   667         *  ======== setCmdId ========
   668         *  sets the command Id in the packet header
   669         *
   670         *  Message header is always layed out as big endian (network order).
   671         *  This macro is designed to work on both little endian and
   672         *  big endian targets, since 32b long words are consistently
   673         *  handled for both endianness - it is only when converting
   674         *  from bytes to longs that bit orders get swapped.
   675         *  #ifdef xdc_target__bigEndian can be used if necessary.
   676         *
   677         *  @param(Hdr* msgHdr)   pointer to the packet header
   678         *  @param(cmdId) the new command Id
   679         */
   680        @Macro Void setCmdId(Hdr *pHdr, UInt16 cmdId);
   681    
   682        /*!
   683         *  ======== getServiceId ========
   684         *  gets the packet type from the packet header
   685         *
   686         *  Message header is always layed out as big endian (network order).
   687         *  This macro is designed to work on both little endian and
   688         *  big endian targets, since 32b long words are consistently
   689         *  handled for both endianness - it is only when converting
   690         *  from bytes to longs that bit orders get swapped.
   691         *  #ifdef xdc_target__bigEndian can be used if necessary.
   692         *
   693         *  @param(Hdr* msgHdr)   pointer to the packet header
   694         */
   695        @Macro UInt16 getServiceId(Hdr *pHdr);
   696        /*!
   697         *  ======== setServiceId ========
   698         *  sets the packet type in the packet header
   699         *
   700         *  Message header is always layed out as big endian (network order).
   701         *  This macro is designed to work on both little endian and
   702         *  big endian targets, since 32b long words are consistently
   703         *  handled for both endianness - it is only when converting
   704         *  from bytes to longs that bit orders get swapped.
   705         *  #ifdef xdc_target__bigEndian can be used if necessary.
   706         *
   707         *  @param(Hdr* msgHdr)   pointer to the packet header
   708         *  @param(serviceId) the new service Id
   709         */
   710        @Macro Void setServiceId(Hdr *pHdr, UInt16 serviceId);
   711    
   712        /*!
   713         * ======== getTag =========
   714         * gets the 32b tag field from the packet header
   715         *
   716         *  @param(Hdr* msgHdr)   pointer to the packet header
   717         */
   718        @Macro Bits32 getTag(Hdr *pHdr);
   719    
   720        /*!
   721         * ======== setTag =========
   722         * sets the 32b tag field in the packet header
   723         *
   724         *  @param(Hdr* msgHdr)   pointer to the packet header
   725         *  @param(tagValue) the tag value to store in the header
   726         */
   727        @Macro Void setTag(Hdr *pHdr, Bits32 tagValue);
   728    
   729        /*!
   730         *  ======== getDestAdrs ========
   731         *  gets the packet destination address from the packet header
   732         *
   733         *  Message header is always layed out as big endian (network order).
   734         *  This macro is designed to work on both little endian and
   735         *  big endian targets, since 32b long words are consistently
   736         *  handled for both endianness - it is only when converting
   737         *  from bytes to longs that bit orders get swapped.
   738         *  #ifdef xdc_target__bigEndian can be used if necessary.
   739         *
   740         *  Example1 :
   741         *   Void example1(UIAPacket_Object *obj){
   742         *      Int16 destAdrs = UIAPacket_getDestAdrs(&obj->hdr);
   743         *      ...
   744         *   }
   745         *  Example2 :
   746         *    Void example2(UIAPacket_Hdr *pHdr){
   747         *      Int16 destAdrs = UIAPacket_getDestAdrs(pHdr);
   748         *      ...
   749         *    }
   750         *
   751         *  @param(Hdr* msgHdr)   pointer to the packet header
   752         */
   753        @Macro UInt16 getDestAdrs(Hdr *pHdr);
   754    
   755        /*!
   756         *  ======== setDestAdrs ========
   757         *  sets the packet destination address in the packet header
   758         *
   759         *  The destination address identifies which endpoint (i.e. which
   760         *  CPU or process) the packet should be sent to.
   761         *  0 is used to broadcast the packet.
   762         *  1 is used for point-to-point connections.
   763         *  Replies to a packet always use the sender address in the
   764         *  originating packet as the destination address.
   765         *  Destination addresses other than the above can be determined
   766         *  via a discovery process.
   767         *
   768         *  Message header is always layed out as big endian (network order).
   769         *  This macro is designed to work on both little endian and
   770         *  big endian targets, since 32b long words are consistently
   771         *  handled for both endianness - it is only when converting
   772         *  from bytes to longs that bit orders get swapped.
   773         *  #ifdef xdc_target__bigEndian can be used if necessary.
   774         *
   775         *  @param(Hdr* msgHdr)   pointer to the packet header
   776         *  @param(destAdrs) the new destination address
   777         */
   778        @Macro Void setDestAdrs(Hdr *pHdr, UInt16 destAdrs);
   779    
   780        /*!
   781         *  ======== getSenderAdrs ========
   782         *  gets the packet sender address from the packet header
   783         *
   784         *  Message header is always layed out as big endian (network order).
   785         *  This macro is designed to work on both little endian and
   786         *  big endian targets, since 32b long words are consistently
   787         *  handled for both endianness - it is only when converting
   788         *  from bytes to longs that bit orders get swapped.
   789         *  #ifdef xdc_target__bigEndian can be used if necessary.
   790         *
   791         *  @param(Hdr* msgHdr)   pointer to the packet header
   792         */
   793        @Macro UInt16 getSenderAdrs(Hdr *pHdr);
   794    
   795        /*!
   796         *  ======== setSenderAdrs ========
   797         *  sets the packet sender address in the packet header
   798         *
   799         *  The sender address identifies which endpoint (i.e. which
   800         *  CPU or process) the packet is coming from
   801         *  1 is used by default.
   802         *  Sender addresses other than 1 can be set via configuration
   803         *  (e.g. to identify which CPU core a packet originated from).
   804         *
   805         *  Message header is always layed out as big endian (network order).
   806         *  This macro is designed to work on both little endian and
   807         *  big endian targets, since 32b long words are consistently
   808         *  handled for both endianness - it is only when converting
   809         *  from bytes to longs that bit orders get swapped.
   810         *  #ifdef xdc_target__bigEndian can be used if necessary.
   811         *
   812         *  @param(Hdr* msgHdr)   pointer to the packet header
   813         *  @param(senderAdrs) the new destination address
   814         */
   815        @Macro Void setSenderAdrs(Hdr *pHdr, UInt16 senderAdrs);
   816    
   817        /*!
   818         * ======== initMsgHdr ========
   819         * initializes all bitfields in the message header
   820         *
   821         *  @param(Hdr* msgHdr)   pointer to the packet header
   822         *  @param(endianness) endianness of the payload
   823         *  @param(msgType) the packet type
   824         *  @param(msgLength) the number of Bytes in the packet, including the 
   825         *     header and footer
   826         *  @param(serviceId) the service Id
   827         *  @param(seqCount) the sequence number for the packet
   828         *  @param(cmdId) the command Id
   829         *  @param(tag) the tag value to store in the header
   830         *  @param(destAdrs) the destination address
   831         *  @param(senderAdrs) the sender address
   832         */
   833        @Macro Void initMsgHdr(Hdr *pHdr, PayloadEndian endianness,
   834                               MsgType msgType, UInt16 msgLength, 
   835                               UInt16 serviceId, UInt16 seqCount,
   836                               UInt16 cmdId,  UInt32 tag,
   837                               UInt16 destAdrs, UInt16 senderAdrs);
   838        
   839        /*!
   840         * ======== initEventRecHdr ========
   841         * initializes all bitfields in the message header
   842         *
   843         *  @param(Hdr* msgHdr)   pointer to the packet header
   844         *  @param(endianness) endianness of the payload
   845         *  @param(eventLength) the number of Bytes in the packet, including 
   846         *     the header and footer
   847         *  @param(seqCount) the sequence number for the packet
   848         *  @param(priority) the logger's priority
   849         *  @param(moduleId) the logger's module Id
   850         *  @param(instanceId) the logger's instanceId
   851         *  @param(destAdrs) the destination address
   852         *  @param(senderAdrs) the sender address
   853         */
   854        @Macro Void initEventRecHdr(Hdr *pHdr, PayloadEndian endianness,
   855                                    UInt32 eventLength, UInt16 seqCount,
   856                                    IUIATransfer.Priority priority, UInt16 moduleId,  
   857                                    UInt16 instanceId, UInt16 destAdrs, 
   858                                    UInt16 senderAdrs);
   859                                    
   860        /*!
   861         * ======== getFooter ========
   862         * returns the integer to use as the packet footer
   863         *
   864         *  @param(Hdr* pHdr)   pointer to the packet header
   865         */
   866        @Macro Int32 getFooter(Hdr *pHdr);
   867    }
   868    
   869    /*
   870     *! Revision History
   871     *! ================
   872     *! 23-Jun-2010 toddm Started revision history
   873     */