1    /*
     2     * Copyright (c) 2012, 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     * */
    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.
   162         *
   163         *  Stored in a 4 bit bitfield (b31-b28) of the first word in the
   164         *  packet.
   165         *
   166         *  The HdrType_InvalidData denotes that following data is invalid.
   167         *  This can used to pad to the end of a buffer. Only the first word
   168         *  of the header is filled in. The length includes the header field.
   169         *
   170         */
   171        enum HdrType {
   172            HdrType_InvalidData = 0, /*! reserved for future use */
   173            HdrType_Reserved1 = 1, /*! reserved for future use */
   174            HdrType_Reserved2 = 2, /*! reserved for future use  */
   175            HdrType_Reserved3 = 3, /*! reserved for future use */
   176            HdrType_Reserved4 = 4, /*! reserved for future use  */
   177            HdrType_Reserved5 = 5, /*! reserved for future use */
   178            HdrType_Reserved6 = 6, /*! reserved for future use */
   179            HdrType_Reserved7 = 7, /*! reserved for future use */
   180            HdrType_ChannelizedData = 8, /*! Channelized data stream */
   181            HdrType_Msg = 9, /*! Message  (4 words header, 1 word footer) */
   182            HdrType_EventPkt = 10, /*! Event rec. containing multiple events:
   183                                      (4 word hdr, 1 word footer) */
   184            HdrType_CPUTrace = 11, /*! CPU Trace ETB data
   185                                       (4 word hdr, 1 word footer) */
   186            HdrType_STMTrace = 12, /*! STM Trace ETB data
   187                                       (4 word hdr, 1 word footer) */
   188            HdrType_USER1 = 13, /*! User defined header type 1 */
   189            HdrType_USER2 = 14, /*! User defined header type 2 */
   190            HdrType_USER3 = 15  /*! User defined header type 3 */
   191        };
   192    
   193        /*!
   194         * ======== PayloadEndian ========
   195         * Enumeration of payload endianness
   196         */
   197        enum PayloadEndian {
   198            PayloadEndian_LITTLE = 0,
   199            PayloadEndian_BIG = 1
   200        };
   201    
   202        /*!
   203         * ======== Footer ========
   204         * Packet Footer
   205         *
   206         * The packet footer is always in network byte order
   207         * i.e. big-endian byte ordering
   208         */
   209        struct Footer
   210        {
   211                Int32 word1;        /*! 16 MSBs contain msg length in Bytes,
   212                                        16 LSBs contain 0x7777 */
   213        }
   214    
   215        /*!
   216         * ======== MsgType ========
   217         * Message Types
   218         *
   219         * Enumeration of the various types of packets.
   220         * Stored in a 4 bit bitfield.
   221         *
   222         * MsgType_ACK:
   223         * Each packet of type CMD or DATA is immediately acknowledged by
   224         * sending either an ACK reply (if the packet can be processed),
   225         * a RESULT or PARTIALRESULT reply (if requested data can be provided
   226         * immediately) or a NACK reply (if the packet cannot be processed).
   227         * The Service that receives the command is responsible for sending
   228         * the ACK or NACK.  If the requested service is not available, the
   229         * Endpoint is responsible for sending the NACK packet.
   230         *
   231         * MsgType_CMD:
   232         * CMD packets are typically sent from the host to the target.
   233         * The receiving endpoint routes the command to the service
   234         * identified in the Service Id field.
   235         *
   236         * MsgType_RESULT:
   237         * RESULT replies are sent along with any requested data.
   238         * If the Service cannot reply with the requested data immediately,
   239         * it should return with an ACK packet and send a RESULT packet
   240         * that echoes the header info of the original command.
   241         *
   242         * MsgType_PARTIALRESULT:
   243         * PARTIALRESULT replies are sent along with any requested data when the
   244         * requested action can only be partly fulfilled.  Examples are when the
   245         * service is reporting on some ongoing operation or has been requested
   246         * to periodically poll some data value.
   247         *
   248         * MsgType_EVENT:
   249         * EVENT packets are sent to all interested parties in order to notify them
   250         * about state changes.   They can, for example, be used to report an error
   251         * that has occurred which may impact the ability of the target to continue
   252         * operating normally.
   253         *
   254         * MsgType_FLOWCTRL
   255         * FLOWCTRL packets are provided for TCF compliance.  They are used to avoid
   256         * flooding of communication links.  In response, endpoints can either
   257         * increase or decrease rate of packets sent, although this is only loosely
   258         * defined. TCF services are not directly concerned with flow control.
   259         * The data passed with FLOWCTRL packets reports the traffic congestion level
   260         * as an integer between -100 and 100, where 0 = "optimal load"
   261         *
   262         * MsgType_DATA
   263         * DATA packets are used for sending event log data and other streams of data.
   264         * Details about how this will be used are being worked out to ensure alignment
   265         * with BIOS RTA Log Servers.
   266         *
   267         * MsgType_NACK_BAD_DATA:
   268         * Negative Acknowledge due to bad data.  Sent in response to a command that
   269         * had invalid data in the body of the packet.  The original data is echoed
   270         * in the NACK response.
   271         *
   272         * MsgType_NACK_WITH_ERROR_CODE
   273         * Negative Acknowledge with Error Code. Sent along with an error code in
   274         * the first word of the body of the reply that describes the error that was
   275         * encountered
   276         */
   277        enum MsgType {
   278            MsgType_ACK=0, /*! Reply acknowledging receipt of CMD or DATA packet */
   279            MsgType_CMD=1, /*! Command packets              */
   280            MsgType_RESULT=2, /*! Result reply                */
   281            MsgType_PARTIALRESULT=3, /*! Partial result reply */
   282            MsgType_NOTIFY=4, /*! Notify messaage (equiv. to the EVENT packet in TCF) */
   283            MsgType_FLOWCTRL=5, /*! Flow control packet      */
   284            MsgType_DATA=6, /*! Data packet (used for streaming data to host) */
   285            MsgType_RESERVED7,
   286            MsgType_RESERVED8,
   287            MsgType_RESERVED9,
   288            MsgType_RESERVED10,
   289            MsgType_RESERVED11,
   290            MsgType_RESERVED12,
   291            MsgType_RESERVED13,
   292            MsgType_NACK_BAD_DATA=14, /*! Negative Acknowledge due to bad data */
   293            MsgType_NACK_WITH_ERROR_CODE=15 /*! Negative Acknowledge -
   294                                                error code in msg body */
   295        };
   296    
   297        /*!
   298         * ======== NACKErrorCode ========
   299         * Message Negative Acknowledge Error Codes
   300         *
   301         * Stored in the first 32b word of the data body of the packet
   302         * in Network Byte Order
   303         */
   304        enum NACKErrorCode {
   305            NACKErrorCode_NO_REASON_SPECIFIED=0, /*! Use this when none of the
   306                                                     defined NACK error codes are
   307                                                     appropriate */
   308            NACKErrorCode_SERVICE_NOT_SUPPORTED=1, /*! A module that handles the
   309                                                       requested Service Id could
   310                                                       not be found */
   311            NACKErrorCode_CMD_NOT_SUPPORTED=2, /*! The service does not support the
   312                                                   specified Command Id */
   313            NACKErrorCode_QUEUE_FULL=3, /*! Cmd couldn't be passed on to dest. end
   314                                            point due to a queue full condition */
   315            NACKErrorCode_BAD_ENDPOINT_ADDRESS=4, /*! The destination end point
   316                                                      address does not exists */
   317            NACKErrorCode_BAD_MESSAGE_LENGTH=5 /*! packet lenght > endpoint max.
   318                                                   msg length or not what is
   319                                                   required to service the cmd  */
   320        };
   321    
   322        /*!
   323         *  ======== HOST ========
   324         *  The address of the host
   325         *
   326         *  The host address is always 0xFFFF.
   327         */
   328        const UInt16 HOST = 0xFFFF;
   329    
   330        /*!
   331         *  ======== BROADCAST ========
   332         *  Used to denote a broadcast message
   333         *
   334         *  The broadcast address is always 0xFFFE.
   335         */
   336        const UInt16 BROADCAST = 0xFFFE;
   337    
   338        /*!
   339         * ========= maxPktLengthInBytes =========
   340         * maximum number of bytes a packet can contain
   341         *
   342         * used to limit the amount of memory needed by the
   343         * packet factories in order to handle a new packet
   344         */
   345        config Int maxPktLengthInBytes = 128;
   346    
   347        /*
   348         * See section 8.2.2 of spru187n.pdf for info on bitfield packing and
   349         * endianness. For big-endian mode, bit fields are packed into registers
   350         * from most significant bit (MSB) to least significant bit (LSB) in the
   351         * order in which they are defined. Bit fields are packed in memory from
   352         * most significant byte (MSbyte) to least significant byte (LSbyte).
   353         * For little-endian mode, bit fields are packed into registers from
   354         * the LSB to the MSB in the order in which they are defined, and packed
   355         * in memory from LSbyte to MSbyte.
   356         *
   357         * In general, different compilers will handle bitfields in different \
   358         * (i.e. incompatible)ways.  To overcome this, the header is treated as
   359         * an array of 32b words, and the bitfields are accessed via macros that
   360         * handle the masking and shifting operations needed to insert or extract
   361         * the information from the relevant bitfields
   362         */
   363    
   364         /*!
   365          * ======== swizzle ========
   366          * returns the value in big endian format
   367          */
   368        @Macro Bits32 swizzle(Bits32 value);
   369    
   370         /*!
   371          * ======== swizzle ========
   372          * returns the value in big endian format
   373          */
   374        @Macro Bits16 swizzle16(Bits16 value);
   375    
   376        /*!
   377         *  ======== getHdrType ========
   378         *  gets the packet header type from the packet header
   379         *
   380         *  Message header is always layed out as big endian (network order).
   381         *  This macro is designed to work on both little endian and
   382         *  big endian targets, since 32b long words are consistently
   383         *  handled for both endianness - it is only when converting
   384         *  from bytes to longs that bit orders get swapped.
   385         *  #ifdef xdc_target__bigEndian can be used if necessary.
   386         *
   387         *  @param(Hdr* msgHdr)   pointer to the packet header
   388         */
   389        @Macro HdrType getHdrType(Hdr *pHdr);
   390    
   391        /*!
   392         *  ======== setHdrType ========
   393         *  sets the header type in the packet header
   394         *
   395         *  Message header is always layed out as big endian (network order).
   396         *  This macro is designed to work on both little endian and
   397         *  big endian targets, since 32b long words are consistently
   398         *  handled for both endianness - it is only when converting
   399         *  from bytes to longs that bit orders get swapped.
   400         *  #ifdef xdc_target__bigEndian can be used if necessary.
   401         *
   402         *  @param(Hdr* msgHdr)   pointer to the packet header
   403         *  @param(HdrType hdrType) the new header type
   404         */
   405        @Macro Void setHdrType(Hdr *pHdr, HdrType hdrType);
   406    
   407        /*!
   408         *  ======== getPayloadEndianness ========
   409         *  gets the payload endianness bit from the packet header
   410         *
   411         *  Message header is always layed out as big endian (network order).
   412         *  This macro is designed to work on both little endian and
   413         *  big endian targets, since 32b long words are consistently
   414         *  handled for both endianness - it is only when converting
   415         *  from bytes to longs that bit orders get swapped.
   416         *  #ifdef xdc_target__bigEndian can be used if necessary.
   417         *
   418         *  @param(Hdr* msgHdr)   pointer to the packet header
   419         */
   420        @Macro Bits32 getPayloadEndianness(Hdr *pHdr);
   421    
   422        /*!
   423         *  ======== setPayloadEndianness ========
   424         *  sets the payload endianness bit from the packet header
   425         *
   426         *  Message header is always layed out as big endian (network order).
   427         *  This macro is designed to work on both little endian and
   428         *  big endian targets, since 32b long words are consistently
   429         *  handled for both endianness - it is only when converting
   430         *  from bytes to longs that bit orders get swapped.
   431         *  #ifdef xdc_target__bigEndian can be used if necessary.
   432         *
   433         *  @param(Hdr* msgHdr)   pointer to the packet header
   434         *  @param(Hdr* msgHdr)   Endianness of the payload
   435         */
   436        @Macro Bits32 setPayloadEndianness(Hdr *pHdr, PayloadEndian endianess);
   437    
   438        /*!
   439         *  ======== getMsgLength ========
   440         *  gets the packet length (in bytes) from the packet header
   441         *
   442         *  Message header is always layed out as big endian (network order).
   443         *  This macro is designed to work on both little endian and
   444         *  big endian targets, since 32b long words are consistently
   445         *  handled for both endianness - it is only when converting
   446         *  from bytes to longs that bit orders get swapped.
   447         *  #ifdef xdc_target__bigEndian can be used if necessary.
   448         *
   449         *  @param(Hdr* msgHdr)   pointer to the packet header
   450         */
   451        @Macro Int32 getMsgLength(Hdr *pHdr);
   452    
   453        /*!
   454         *  ======== setMsgLength ========
   455         *  sets the packet length (in bytes) from the packet header
   456         *
   457         *  Message header is always layed out as big endian (network order).
   458         *  This macro is designed to work on both little endian and
   459         *  big endian targets, since 32b long words are consistently
   460         *  handled for both endianness - it is only when converting
   461         *  from bytes to longs that bit orders get swapped.
   462         *  #ifdef xdc_target__bigEndian can be used if necessary.
   463         *
   464         *  @param(Hdr* msgHdr)   pointer to the packet header
   465         *  @param(pktLength) the new packet length
   466         *
   467         */
   468        @Macro Void setMsgLength(Hdr *pHdr, UInt16 pktLength);
   469    
   470        /*!
   471         *  ======== getEventLength ========
   472         *  Gets the packet length (in bytes) from the packet header
   473         *
   474         *  Includes the packet header
   475         *
   476         *  @param(Hdr* msgHdr)   pointer to the packet header
   477         */
   478        @Macro Int32 getEventLength(Hdr *pHdr);
   479    
   480        /*!
   481         *  ======== setEventLength ========
   482         *  Sets the packet length (in bytes) from the packet header
   483         *
   484         *  Includes the packet header
   485         *
   486         *  @param(Hdr* msgHdr)   pointer to the packet header
   487         *  @param(pktLength) the new packet length
   488         *
   489         */
   490        @Macro Void setEventLength(Hdr *pHdr, Bits32 pktLength);
   491    
   492        /*!
   493         *  ======== getLength ========
   494         *  Gets the packet length (in bytes) from the packet header
   495         *
   496         *  Includes the packet header
   497         *
   498         *  @param(Hdr* msgHdr)   pointer to the packet header
   499         */
   500        Int32 getLength(Hdr *pHdr);
   501    
   502        /*!
   503         *  ======== getSequenceCount ========
   504         *  gets the sequence count from the packet header
   505         *
   506         *  Message header is always layed out as big endian (network order).
   507         *  This macro is designed to work on both little endian and
   508         *  big endian targets, since 32b long words are consistently
   509         *  handled for both endianness - it is only when converting
   510         *  from bytes to longs that bit orders get swapped.
   511         *  #ifdef xdc_target__bigEndian can be used if necessary.
   512         *
   513         *  @param(Hdr* msgHdr)   pointer to the packet header
   514         */
   515        @Macro UInt16 getSequenceCount(Hdr *pHdr);
   516    
   517        /*!
   518         *  ======== setSequenceCount ========
   519         *  sets the sequence count in the packet header
   520         *
   521         *  Message header is always layed out as big endian (network order).
   522         *  This macro is designed to work on both little endian and
   523         *  big endian targets, since 32b long words are consistently
   524         *  handled for both endianness - it is only when converting
   525         *  from bytes to longs that bit orders get swapped.
   526         *  #ifdef xdc_target__bigEndian can be used if necessary.
   527         *
   528         *  @param(Hdr* msgHdr)   pointer to the packet header
   529         *  @param(seqCount) the new packet sequence count
   530         */
   531        @Macro Void setSequenceCount(Hdr *pHdr, Bits16 seqCount);
   532    
   533        /*! @_nodoc
   534         *  ======== getLoggerPriority ========
   535         *  gets the logger priority field from the event packet header
   536         *
   537         *  Message header is always layed out as big endian (network order).
   538         *  This macro is designed to work on both little endian and
   539         *  big endian targets, since 32b long words are consistently
   540         *  handled for both endianness - it is only when converting
   541         *  from bytes to longs that bit orders get swapped.
   542         *  #ifdef xdc_target__bigEndian can be used if necessary.
   543         *
   544         *  @param(Hdr* msgHdr)   pointer to the packet header
   545         *  @a(return) the priority of the logger that logged the events
   546         *  @see IUIATransfer#Priority
   547         */
   548        @Macro IUIATransfer.Priority getLoggerPriority(Hdr *pHdr);
   549    
   550        /*! @_nodoc
   551         *  ======== setLoggerPriority ========
   552         *  sets the logger priority field in the event packet header
   553         *
   554         *  Message header is always layed out as big endian (network order).
   555         *  This macro is designed to work on both little endian and
   556         *  big endian targets, since 32b long words are consistently
   557         *  handled for both endianness - it is only when converting
   558         *  from bytes to longs that bit orders get swapped.
   559         *  #ifdef xdc_target__bigEndian can be used if necessary.
   560         *
   561         *  @param(Hdr* msgHdr)   pointer to the packet header
   562         *  @param(priority) the logger priority ( @see IUIATransfer#Priority )
   563         */
   564        @Macro Void setLoggerPriority(Hdr *pHdr, IUIATransfer.Priority priority);
   565        /*!
   566         *  ======== getLoggerModuleId ========
   567         *  gets the logger ID from the event packet header
   568         *
   569         *  Message header is always layed out as big endian (network order).
   570         *  This macro is designed to work on both little endian and
   571         *  big endian targets, since 32b long words are consistently
   572         *  handled for both endianness - it is only when converting
   573         *  from bytes to longs that bit orders get swapped.
   574         *  #ifdef xdc_target__bigEndian can be used if necessary.
   575         *
   576         *  @param(Hdr* msgHdr)   pointer to the packet header
   577         */
   578        @Macro Bits16 getLoggerModuleId(Hdr *pHdr);
   579    
   580        /*!
   581         *  ======== setLoggerModuleId ========
   582         *  sets the module ID in the event packet header
   583         *
   584         *  Message header is always layed out as big endian (network order).
   585         *  This macro is designed to work on both little endian and
   586         *  big endian targets, since 32b long words are consistently
   587         *  handled for both endianness - it is only when converting
   588         *  from bytes to longs that bit orders get swapped.
   589         *  #ifdef xdc_target__bigEndian can be used if necessary.
   590         *
   591         *  @param(Hdr* msgHdr)   pointer to the packet header
   592         *  @param(loggerModuleId) the moduleID of the logger that logged the events
   593         */
   594        @Macro Void setLoggerModuleId(Hdr *pHdr, Bits16 loggerModuleId);
   595    
   596        /*!
   597         *  ======== getLoggerInstanceId ========
   598         *  gets the logger instance ID from the event packet header
   599         *
   600         *  Message header is always layed out as big endian (network order).
   601         *  This macro is designed to work on both little endian and
   602         *  big endian targets, since 32b long words are consistently
   603         *  handled for both endianness - it is only when converting
   604         *  from bytes to longs that bit orders get swapped.
   605         *  #ifdef xdc_target__bigEndian can be used if necessary.
   606         *
   607         *  @param(Hdr* msgHdr)   pointer to the packet header
   608         */
   609        @Macro Bits16 getLoggerInstanceId(Hdr *pHdr);
   610    
   611        /*!
   612         *  ======== setLoggerInstanceId ========
   613         *  sets the sequence count in the packet header
   614         *
   615         *  Message header is always layed out as big endian (network order).
   616         *  This macro is designed to work on both little endian and
   617         *  big endian targets, since 32b long words are consistently
   618         *  handled for both endianness - it is only when converting
   619         *  from bytes to longs that bit orders get swapped.
   620         *  #ifdef xdc_target__bigEndian can be used if necessary.
   621         *
   622         *  @param(Hdr* msgHdr)   pointer to the packet header
   623         *  @param(seqCount) the new packet sequence count
   624         */
   625        @Macro Void setLoggerInstanceId(Hdr *pHdr, Bits16 loggerInstanceId);
   626    
   627        /*!
   628         *  ======== getMsgType ========
   629         *  gets the packet type from the packet header
   630         *
   631         *  Message header is always layed out as big endian (network order).
   632         *  This macro is designed to work on both little endian and
   633         *  big endian targets, since 32b long words are consistently
   634         *  handled for both endianness - it is only when converting
   635         *  from bytes to longs that bit orders get swapped.
   636         *  #ifdef xdc_target__bigEndian can be used if necessary.
   637         *
   638         *  @param(Hdr* pHdr)   pointer to the packet header
   639         */
   640        @Macro MsgType getMsgType(Hdr *pHdr);
   641    
   642        /*!
   643         *  ======== setMsgType ========
   644         *  sets the packet type in the packet header
   645         *
   646         *  Message header is always layed out as big endian (network order).
   647         *  This macro is designed to work on both little endian and
   648         *  big endian targets, since 32b long words are consistently
   649         *  handled for both endianness - it is only when converting
   650         *  from bytes to longs that bit orders get swapped.
   651         *  #ifdef xdc_target__bigEndian can be used if necessary.
   652         *
   653         *  @param(Hdr* msgHdr)   pointer to the packet header
   654         *  @param(msgType) the new packet type
   655         */
   656        @Macro Void setMsgType(Hdr *pHdr, MsgType msgType);
   657    
   658        /*!
   659         *  ======== getCmdId ========
   660         *  gets the packet type from the packet header
   661         *
   662         *  Message header is always layed out as big endian (network order).
   663         *  This macro is designed to work on both little endian and
   664         *  big endian targets, since 32b long words are consistently
   665         *  handled for both endianness - it is only when converting
   666         *  from bytes to longs that bit orders get swapped.
   667         *  #ifdef xdc_target__bigEndian can be used if necessary.
   668         *
   669         *  @param(Hdr* msgHdr)   pointer to the packet header
   670         */
   671        @Macro UInt16 getCmdId(Hdr *pHdr);
   672    
   673        /*!
   674         *  ======== setCmdId ========
   675         *  sets the command Id in the packet header
   676         *
   677         *  Message header is always layed out as big endian (network order).
   678         *  This macro is designed to work on both little endian and
   679         *  big endian targets, since 32b long words are consistently
   680         *  handled for both endianness - it is only when converting
   681         *  from bytes to longs that bit orders get swapped.
   682         *  #ifdef xdc_target__bigEndian can be used if necessary.
   683         *
   684         *  @param(Hdr* msgHdr)   pointer to the packet header
   685         *  @param(cmdId) the new command Id
   686         */
   687        @Macro Void setCmdId(Hdr *pHdr, UInt16 cmdId);
   688    
   689        /*!
   690         *  ======== getServiceId ========
   691         *  gets the packet type from the packet header
   692         *
   693         *  Message header is always layed out as big endian (network order).
   694         *  This macro is designed to work on both little endian and
   695         *  big endian targets, since 32b long words are consistently
   696         *  handled for both endianness - it is only when converting
   697         *  from bytes to longs that bit orders get swapped.
   698         *  #ifdef xdc_target__bigEndian can be used if necessary.
   699         *
   700         *  @param(Hdr* msgHdr)   pointer to the packet header
   701         */
   702        @Macro UInt16 getServiceId(Hdr *pHdr);
   703        /*!
   704         *  ======== setServiceId ========
   705         *  sets the packet type in the packet header
   706         *
   707         *  Message header is always layed out as big endian (network order).
   708         *  This macro is designed to work on both little endian and
   709         *  big endian targets, since 32b long words are consistently
   710         *  handled for both endianness - it is only when converting
   711         *  from bytes to longs that bit orders get swapped.
   712         *  #ifdef xdc_target__bigEndian can be used if necessary.
   713         *
   714         *  @param(Hdr* msgHdr)   pointer to the packet header
   715         *  @param(serviceId) the new service Id
   716         */
   717        @Macro Void setServiceId(Hdr *pHdr, UInt16 serviceId);
   718    
   719        /*!
   720         * ======== getTag =========
   721         * gets the 32b tag field from the packet header
   722         *
   723         *  @param(Hdr* msgHdr)   pointer to the packet header
   724         */
   725        @Macro Bits32 getTag(Hdr *pHdr);
   726    
   727        /*!
   728         * ======== setTag =========
   729         * sets the 32b tag field in the packet header
   730         *
   731         *  @param(Hdr* msgHdr)   pointer to the packet header
   732         *  @param(tagValue) the tag value to store in the header
   733         */
   734        @Macro Void setTag(Hdr *pHdr, Bits32 tagValue);
   735    
   736        /*!
   737         *  ======== getDestAdrs ========
   738         *  gets the packet destination address from the packet header
   739         *
   740         *  Message header is always layed out as big endian (network order).
   741         *  This macro is designed to work on both little endian and
   742         *  big endian targets, since 32b long words are consistently
   743         *  handled for both endianness - it is only when converting
   744         *  from bytes to longs that bit orders get swapped.
   745         *  #ifdef xdc_target__bigEndian can be used if necessary.
   746         *
   747         *  Example1 :
   748         *   Void example1(UIAPacket_Object *obj){
   749         *      Int16 destAdrs = UIAPacket_getDestAdrs(&obj->hdr);
   750         *      ...
   751         *   }
   752         *  Example2 :
   753         *    Void example2(UIAPacket_Hdr *pHdr){
   754         *      Int16 destAdrs = UIAPacket_getDestAdrs(pHdr);
   755         *      ...
   756         *    }
   757         *
   758         *  @param(Hdr* msgHdr)   pointer to the packet header
   759         */
   760        @Macro UInt16 getDestAdrs(Hdr *pHdr);
   761    
   762        /*!
   763         *  ======== setDestAdrs ========
   764         *  sets the packet destination address in the packet header
   765         *
   766         *  The destination address identifies which endpoint (i.e. which
   767         *  CPU or process) the packet should be sent to.
   768         *  0 is used to broadcast the packet.
   769         *  1 is used for point-to-point connections.
   770         *  Replies to a packet always use the sender address in the
   771         *  originating packet as the destination address.
   772         *  Destination addresses other than the above can be determined
   773         *  via a discovery process.
   774         *
   775         *  Message header is always layed out as big endian (network order).
   776         *  This macro is designed to work on both little endian and
   777         *  big endian targets, since 32b long words are consistently
   778         *  handled for both endianness - it is only when converting
   779         *  from bytes to longs that bit orders get swapped.
   780         *  #ifdef xdc_target__bigEndian can be used if necessary.
   781         *
   782         *  @param(Hdr* msgHdr)   pointer to the packet header
   783         *  @param(destAdrs) the new destination address
   784         */
   785        @Macro Void setDestAdrs(Hdr *pHdr, UInt16 destAdrs);
   786    
   787        /*!
   788         *  ======== getSenderAdrs ========
   789         *  gets the packet sender address from the packet header
   790         *
   791         *  Message header is always layed out as big endian (network order).
   792         *  This macro is designed to work on both little endian and
   793         *  big endian targets, since 32b long words are consistently
   794         *  handled for both endianness - it is only when converting
   795         *  from bytes to longs that bit orders get swapped.
   796         *  #ifdef xdc_target__bigEndian can be used if necessary.
   797         *
   798         *  @param(Hdr* msgHdr)   pointer to the packet header
   799         */
   800        @Macro UInt16 getSenderAdrs(Hdr *pHdr);
   801    
   802        /*!
   803         *  ======== setSenderAdrs ========
   804         *  sets the packet sender address in the packet header
   805         *
   806         *  The sender address identifies which endpoint (i.e. which
   807         *  CPU or process) the packet is coming from
   808         *  1 is used by default.
   809         *  Sender addresses other than 1 can be set via configuration
   810         *  (e.g. to identify which CPU core a packet originated from).
   811         *
   812         *  Message header is always layed out as big endian (network order).
   813         *  This macro is designed to work on both little endian and
   814         *  big endian targets, since 32b long words are consistently
   815         *  handled for both endianness - it is only when converting
   816         *  from bytes to longs that bit orders get swapped.
   817         *  #ifdef xdc_target__bigEndian can be used if necessary.
   818         *
   819         *  @param(Hdr* msgHdr)   pointer to the packet header
   820         *  @param(senderAdrs) the new destination address
   821         */
   822        @Macro Void setSenderAdrs(Hdr *pHdr, UInt16 senderAdrs);
   823    
   824        /*!
   825         * ======== initMsgHdr ========
   826         * initializes all bitfields in the message header
   827         *
   828         *  @param(Hdr* msgHdr)   pointer to the packet header
   829         *  @param(endianness) endianness of the payload
   830         *  @param(msgType) the packet type
   831         *  @param(msgLength) the number of Bytes in the packet, including the
   832         *     header and footer
   833         *  @param(serviceId) the service Id
   834         *  @param(seqCount) the sequence number for the packet
   835         *  @param(cmdId) the command Id
   836         *  @param(tag) the tag value to store in the header
   837         *  @param(destAdrs) the destination address
   838         *  @param(senderAdrs) the sender address
   839         */
   840        @Macro Void initMsgHdr(Hdr *pHdr, PayloadEndian endianness,
   841                               MsgType msgType, UInt16 msgLength,
   842                               UInt16 serviceId, UInt16 seqCount,
   843                               UInt16 cmdId,  UInt32 tag,
   844                               UInt16 destAdrs, UInt16 senderAdrs);
   845    
   846        /*!
   847         * ======== initEventRecHdr ========
   848         * initializes all bitfields in the message header
   849         *
   850         *  @param(Hdr* msgHdr)   pointer to the packet header
   851         *  @param(endianness) endianness of the payload
   852         *  @param(eventLength) the number of Bytes in the packet, including
   853         *     the header and footer
   854         *  @param(seqCount) the sequence number for the packet
   855         *  @param(priority) the logger's priority
   856         *  @param(moduleId) the logger's module Id
   857         *  @param(instanceId) the logger's instanceId
   858         *  @param(destAdrs) the destination address
   859         *  @param(senderAdrs) the sender address
   860         */
   861        @Macro Void initEventRecHdr(Hdr *pHdr, PayloadEndian endianness,
   862                                    UInt32 eventLength, UInt16 seqCount,
   863                                    IUIATransfer.Priority priority, UInt16 moduleId,
   864                                    UInt16 instanceId, UInt16 destAdrs,
   865                                    UInt16 senderAdrs);
   866    
   867        /*!
   868         * ======== getFooter ========
   869         * returns the integer to use as the packet footer
   870         *
   871         *  @param(Hdr* pHdr)   pointer to the packet header
   872         */
   873        @Macro Int32 getFooter(Hdr *pHdr);
   874    
   875        /*!
   876         * ======== setInvalidHdr ========
   877         * Used to set the header type as invalid
   878         *
   879         *  @param(Hdr* pHdr)   pointer to the packet header
   880         *  @param(eventLength) the number of Bytes in the packet of memory
   881         *       that is invalid (including the first word of the 32-bit hdr)
   882         */
   883        @Macro Void setInvalidHdr(Hdr *pHdr, UInt32 eventLength);
   884    }