1    /*
     2     * Copyright (c) 2012-2014, 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         * @p(code)
   105         *
   106         *  HdrType_EventPkt word1
   107         *   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
   108         *   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
   109         *  |---------------------------------------------------------------|
   110         *  |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|
   111         *  |---------------------------------------------------------------|
   112         *
   113         *  H = HdrType         (4-bits)
   114         *  E = Payload endian   (1-bit)
   115         *  L = Packet Length   (27-bits)
   116         *
   117         *  HdrType_EventPkt word2
   118         *   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
   119         *   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
   120         *  |---------------------------------------------------------------|
   121         *  |S S S S S S S S S S S S S S S S|E E E E E E E E E E E E E E|P P|
   122         *  |---------------------------------------------------------------|
   123         *
   124         *  S = Packet Sequence Number              (16-bits)
   125         *  E = Event Sequence Number for first event in the packet (14-bits)     
   126         *  P = Priority: Normal=0, High > 0 (2-bits)
   127         *
   128         *  HdrType_EventPkt word3
   129         *   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
   130         *   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
   131         *  |---------------------------------------------------------------|
   132         *  |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|
   133         *  |---------------------------------------------------------------|
   134         *
   135         *  D -  wasLoggerDynamicallyCreated  (1-bit:  0 = statically created,
   136         *                                            1 = dynamically created )
   137         *  I - Logger Instance ID           (15-bits)
   138         *  M - Logger Module ID             (16-bits)
   139         *
   140         *  HdrType_EventPkt word4
   141         *   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
   142         *   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
   143         *  |---------------------------------------------------------------|
   144         *  |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|
   145         *  |---------------------------------------------------------------|
   146         *
   147         *  D - Destination Address (16-bits)
   148         *  S - Source Address      (16-bits)
   149         *
   150         *  @p(code)
   151         *
   152         * For HdrType_EventPktWithCRC 
   153         *  word 5 holds the 16b CRC of the application name (0 for RTOSes such as SysBIOS)
   154         *   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
   155         *   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
   156         *  |---------------------------------------------------------------|
   157         *  |R R R R R R R R R R R R R R R|C C C C C C C C C C C C C C C C C|
   158         *  |---------------------------------------------------------------|
   159         *  C = CRC16 of the application name (0 if only one process) (32-bits)  
   160         *  R = Reserved (set to 0)      
   161         *
   162         *  @p(code)
   163         *
   164         *  For memory constrained systems, ti.uia.loggers.LoggerMin uses the 
   165         *  following 2 word Event Packet header format, with HdrType =
   166         *  HdrType_MinEventPkt :
   167         *
   168         *   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
   169         *   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
   170         *  |---------------------------------------------------------------|
   171         *  |H H H H|E|D D D D D|R R R R R R|L L L L L L L L L L L L L L L L|
   172         *  |---------------------------------------------------------------|
   173         *
   174         *  H = HdrType          (4-bits)
   175         *  E = Payload endian   (1-bit)
   176         *  D = Sender Adrs / Device ID  (5 bits – DNUM) 
   177         *  R = Reserved (set to 0)        
   178         *  L = packet Length     (16-bits)
   179         *
   180         *  HdrType_MinEventPkt word2
   181         *   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
   182         *   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
   183         *  |---------------------------------------------------------------|
   184         *  |S S S S S S S S S S S S S S S S|E E E E E E E E E E E E E E|P P|
   185         *  |---------------------------------------------------------------|
   186         *
   187         *  S = Packet Sequence Number              (16-bits)
   188         *  E = Event Sequence Number for first event in the packet (14-bits)
   189         *  P = Priority: Normal=0, High > 0 (2-bits)
   190         */
   191        struct Hdr {
   192            Bits32 word1;
   193            Bits32 word2;
   194            Bits32 word3;
   195            Bits32 word4;
   196        };
   197    
   198        /*!
   199         * ======== HdrType ========
   200         *  Enumeration of the various types of packet
   201         *  headers.
   202         *
   203         *  Stored in a 4 bit bitfield (b31-b28) of the first word in the
   204         *  packet.
   205         *
   206         *  The HdrType_InvalidData denotes that following data is invalid.
   207         *  This can used to pad to the end of a buffer. Only the first word
   208         *  of the header is filled in. The length includes the header field.
   209         *
   210         */
   211        enum HdrType {
   212            HdrType_InvalidData = 0, /*! reserved for future use */
   213            HdrType_MsgWithPID = 1, /*! message with Process ID field (for multi-process O/Ses) */
   214            HdrType_EventPktWithCRC = 2, /*! event packet with CRC of applciation name (for multi-process O/Ses)  */
   215            HdrType_MinEventPkt = 3, /*! small footprint event packet used by ti.uia.loggers.LoggerMin */
   216            HdrType_Reserved4 = 4, /*! reserved for future use */
   217            HdrType_Reserved5 = 5, /*! reserved for future use */
   218            HdrType_Reserved6 = 6, /*! reserved for future use */
   219            HdrType_Reserved7 = 7, /*! reserved for future use */
   220            HdrType_ChannelizedData = 8, /*! Channelized data stream */
   221            HdrType_Msg = 9, /*! Message  (4 words header, 1 word footer) */
   222            HdrType_EventPkt = 10, /*! Event rec. containing multiple events:
   223                                      (4 word hdr, 1 word footer) */
   224            HdrType_CPUTrace = 11, /*! CPU Trace ETB data
   225                                       (4 word hdr, 1 word footer) */
   226            HdrType_STMTrace = 12, /*! STM Trace ETB data
   227                                       (4 word hdr, 1 word footer) */
   228            HdrType_MemoryBuffer = 13, /*! Memory Buffer data */
   229            HdrType_USER2 = 14, /*! User defined header type 2 */
   230            HdrType_USER3 = 15  /*! User defined header type 3 */
   231        };
   232        
   233    
   234        /*!
   235         * ======== PayloadEndian ========
   236         * Enumeration of payload endianness
   237         */
   238        enum PayloadEndian {
   239            PayloadEndian_LITTLE = 0,
   240            PayloadEndian_BIG = 1
   241        };
   242    
   243        /*!
   244         * ======== Footer ========
   245         * Packet Footer
   246         *
   247         * The packet footer is always in network byte order
   248         * i.e. big-endian byte ordering
   249         */
   250        struct Footer
   251        {
   252            Int32 word1;        /*! 16 MSBs contain msg length in Bytes,
   253                                        16 LSBs contain 0x7777 */
   254        }
   255    
   256        /*!
   257         * ======== MsgType ========
   258         * Message Types
   259         *
   260         * Enumeration of the various types of packets.
   261         * Stored in a 4 bit bitfield.
   262         *
   263         * MsgType_ACK:
   264         * Each packet of type CMD or DATA is immediately acknowledged by
   265         * sending either an ACK reply (if the packet can be processed),
   266         * a RESULT or PARTIALRESULT reply (if requested data can be provided
   267         * immediately) or a NACK reply (if the packet cannot be processed).
   268         * The Service that receives the command is responsible for sending
   269         * the ACK or NACK.  If the requested service is not available, the
   270         * Endpoint is responsible for sending the NACK packet.
   271         *
   272         * MsgType_CMD:
   273         * CMD packets are typically sent from the host to the target.
   274         * The receiving endpoint routes the command to the service
   275         * identified in the Service Id field.
   276         *
   277         * MsgType_RESULT:
   278         * RESULT replies are sent along with any requested data.
   279         * If the Service cannot reply with the requested data immediately,
   280         * it should return with an ACK packet and send a RESULT packet
   281         * that echoes the header info of the original command.
   282         *
   283         * MsgType_PARTIALRESULT:
   284         * PARTIALRESULT replies are sent along with any requested data when the
   285         * requested action can only be partly fulfilled.  Examples are when the
   286         * service is reporting on some ongoing operation or has been requested
   287         * to periodically poll some data value.
   288         *
   289         * MsgType_EVENT:
   290         * EVENT packets are sent to all interested parties in order to notify them
   291         * about state changes.   They can, for example, be used to report an error
   292         * that has occurred which may impact the ability of the target to continue
   293         * operating normally.
   294         *
   295         * MsgType_FLOWCTRL
   296         * FLOWCTRL packets are provided for TCF compliance.  They are used to avoid
   297         * flooding of communication links.  In response, endpoints can either
   298         * increase or decrease rate of packets sent, although this is only loosely
   299         * defined. TCF services are not directly concerned with flow control.
   300         * The data passed with FLOWCTRL packets reports the traffic congestion level
   301         * as an integer between -100 and 100, where 0 = "optimal load"
   302         *
   303         * MsgType_DATA
   304         * DATA packets are used for sending event log data and other streams of data.
   305         * Details about how this will be used are being worked out to ensure alignment
   306         * with BIOS RTA Log Servers.
   307         *
   308         * MsgType_NACK_BAD_DATA:
   309         * Negative Acknowledge due to bad data.  Sent in response to a command that
   310         * had invalid data in the body of the packet.  The original data is echoed
   311         * in the NACK response.
   312         *
   313         * MsgType_NACK_WITH_ERROR_CODE
   314         * Negative Acknowledge with Error Code. Sent along with an error code in
   315         * the first word of the body of the reply that describes the error that was
   316         * encountered
   317         */
   318        enum MsgType {
   319            MsgType_ACK=0, /*! Reply acknowledging receipt of CMD or DATA packet */
   320            MsgType_CMD=1, /*! Command packets              */
   321            MsgType_RESULT=2, /*! Result reply                */
   322            MsgType_PARTIALRESULT=3, /*! Partial result reply */
   323            MsgType_NOTIFY=4, /*! Notify messaage (equiv. to the EVENT packet in TCF) */
   324            MsgType_FLOWCTRL=5, /*! Flow control packet      */
   325            MsgType_DATA=6, /*! Data packet (used for streaming data to host) */
   326            MsgType_RESERVED7,
   327            MsgType_RESERVED8,
   328            MsgType_RESERVED9,
   329            MsgType_RESERVED10,
   330            MsgType_RESERVED11,
   331            MsgType_RESERVED12,
   332            MsgType_RESERVED13,
   333            MsgType_NACK_BAD_DATA=14, /*! Negative Acknowledge due to bad data */
   334            MsgType_NACK_WITH_ERROR_CODE=15 /*! Negative Acknowledge -
   335                                                error code in msg body */
   336        };
   337    
   338        /*!
   339         * ======== NACKErrorCode ========
   340         * Message Negative Acknowledge Error Codes
   341         *
   342         * Stored in the first 32b word of the data body of the packet
   343         * in Network Byte Order
   344         */
   345        enum NACKErrorCode {
   346            NACKErrorCode_NO_REASON_SPECIFIED=0, /*! Use this when none of the
   347                                                     defined NACK error codes are
   348                                                     appropriate */
   349            NACKErrorCode_SERVICE_NOT_SUPPORTED=1, /*! A module that handles the
   350                                                       requested Service Id could
   351                                                       not be found */
   352            NACKErrorCode_CMD_NOT_SUPPORTED=2, /*! The service does not support the
   353                                                   specified Command Id */
   354            NACKErrorCode_QUEUE_FULL=3, /*! Cmd couldn't be passed on to dest. end
   355                                            point due to a queue full condition */
   356            NACKErrorCode_BAD_ENDPOINT_ADDRESS=4, /*! The destination end point
   357                                                      address does not exists */
   358            NACKErrorCode_BAD_MESSAGE_LENGTH=5 /*! packet lenght > endpoint max.
   359                                                   msg length or not what is
   360                                                   required to service the cmd  */
   361        };
   362    
   363        /*!
   364         *  ======== HOST ========
   365         *  The address of the host
   366         *
   367         *  The host address is always 0xFFFF.
   368         */
   369        const UInt16 HOST = 0xFFFF;
   370    
   371        /*!
   372         *  ======== BROADCAST ========
   373         *  Used to denote a broadcast message
   374         *
   375         *  The broadcast address is always 0xFFFE.
   376         */
   377        const UInt16 BROADCAST = 0xFFFE;
   378    
   379        /*!
   380         * ========= maxPktLengthInBytes =========
   381         * maximum number of bytes a packet can contain
   382         *
   383         * used to limit the amount of memory needed by the
   384         * packet factories in order to handle a new packet
   385         */
   386        config Int maxPktLengthInBytes = 128;
   387    
   388        /*
   389         * See section 8.2.2 of spru187n.pdf for info on bitfield packing and
   390         * endianness. For big-endian mode, bit fields are packed into registers
   391         * from most significant bit (MSB) to least significant bit (LSB) in the
   392         * order in which they are defined. Bit fields are packed in memory from
   393         * most significant byte (MSbyte) to least significant byte (LSbyte).
   394         * For little-endian mode, bit fields are packed into registers from
   395         * the LSB to the MSB in the order in which they are defined, and packed
   396         * in memory from LSbyte to MSbyte.
   397         *
   398         * In general, different compilers will handle bitfields in different \
   399         * (i.e. incompatible)ways.  To overcome this, the header is treated as
   400         * an array of 32b words, and the bitfields are accessed via macros that
   401         * handle the masking and shifting operations needed to insert or extract
   402         * the information from the relevant bitfields
   403         */
   404    
   405         /*!
   406          * ======== swizzle ========
   407          * returns the value in big endian format
   408          */
   409        @Macro Bits32 swizzle(Bits32 value);
   410    
   411         /*!
   412          * ======== swizzle ========
   413          * returns the value in big endian format
   414          */
   415        @Macro Bits16 swizzle16(Bits16 value);
   416    
   417        /*!
   418         *  ======== getHdrType ========
   419         *  gets the packet header type from the packet header
   420         *
   421         *  Message header is always layed out as big endian (network order).
   422         *  This macro is designed to work on both little endian and
   423         *  big endian targets, since 32b long words are consistently
   424         *  handled for both endianness - it is only when converting
   425         *  from bytes to longs that bit orders get swapped.
   426         *  #ifdef xdc_target__bigEndian can be used if necessary.
   427         *
   428         *  @param(Hdr* msgHdr)   pointer to the packet header
   429         */
   430        @Macro HdrType getHdrType(Hdr *pHdr);
   431    
   432        /*!
   433         *  ======== setHdrType ========
   434         *  sets the header type in the packet header
   435         *
   436         *  Message header is always layed out as big endian (network order).
   437         *  This macro is designed to work on both little endian and
   438         *  big endian targets, since 32b long words are consistently
   439         *  handled for both endianness - it is only when converting
   440         *  from bytes to longs that bit orders get swapped.
   441         *  #ifdef xdc_target__bigEndian can be used if necessary.
   442         *
   443         *  @param(Hdr* msgHdr)   pointer to the packet header
   444         *  @param(HdrType hdrType) the new header type
   445         */
   446        @Macro Void setHdrType(Hdr *pHdr, HdrType hdrType);
   447    
   448        /*!
   449         *  ======== getPayloadEndianness ========
   450         *  gets the payload endianness bit from the packet header
   451         *
   452         *  Message header is always layed out as big endian (network order).
   453         *  This macro is designed to work on both little endian and
   454         *  big endian targets, since 32b long words are consistently
   455         *  handled for both endianness - it is only when converting
   456         *  from bytes to longs that bit orders get swapped.
   457         *  #ifdef xdc_target__bigEndian can be used if necessary.
   458         *
   459         *  @param(Hdr* msgHdr)   pointer to the packet header
   460         */
   461        @Macro Bits32 getPayloadEndianness(Hdr *pHdr);
   462    
   463        /*!
   464         *  ======== setPayloadEndianness ========
   465         *  sets the payload endianness bit from the packet header
   466         *
   467         *  Message header is always layed out as big endian (network order).
   468         *  This macro is designed to work on both little endian and
   469         *  big endian targets, since 32b long words are consistently
   470         *  handled for both endianness - it is only when converting
   471         *  from bytes to longs that bit orders get swapped.
   472         *  #ifdef xdc_target__bigEndian can be used if necessary.
   473         *
   474         *  @param(Hdr* msgHdr)   pointer to the packet header
   475         *  @param(Hdr* msgHdr)   Endianness of the payload
   476         */
   477        @Macro Bits32 setPayloadEndianness(Hdr *pHdr, PayloadEndian endianess);
   478    
   479        /*!
   480         *  ======== getMsgLength ========
   481         *  gets the packet length (in bytes) from the packet header
   482         *
   483         *  Message header is always layed out as big endian (network order).
   484         *  This macro is designed to work on both little endian and
   485         *  big endian targets, since 32b long words are consistently
   486         *  handled for both endianness - it is only when converting
   487         *  from bytes to longs that bit orders get swapped.
   488         *  #ifdef xdc_target__bigEndian can be used if necessary.
   489         *
   490         *  @param(Hdr* msgHdr)   pointer to the packet header
   491         */
   492        @Macro Int32 getMsgLength(Hdr *pHdr);
   493    
   494        /*!
   495         *  ======== setMsgLength ========
   496         *  sets the packet length (in bytes) from the packet header
   497         *
   498         *  Message header is always layed out as big endian (network order).
   499         *  This macro is designed to work on both little endian and
   500         *  big endian targets, since 32b long words are consistently
   501         *  handled for both endianness - it is only when converting
   502         *  from bytes to longs that bit orders get swapped.
   503         *  #ifdef xdc_target__bigEndian can be used if necessary.
   504         *
   505         *  @param(Hdr* msgHdr)   pointer to the packet header
   506         *  @param(pktLength) the new packet length
   507         *
   508         */
   509        @Macro Void setMsgLength(Hdr *pHdr, UInt16 pktLength);
   510    
   511        /*!
   512         *  ======== getEventLength ========
   513         *  Gets the packet length (in bytes) from the packet header
   514         *
   515         *  Includes the packet header
   516         *
   517         *  @param(Hdr* msgHdr)   pointer to the packet header
   518         */
   519        @Macro Int32 getEventLength(Hdr *pHdr);
   520    
   521        /*!
   522         *  @_nodoc
   523         *  ======== getMinEventLength ========
   524         *  Gets the packet length (in bytes) from a MinEvent packet header
   525         *  (for testing).
   526         *
   527         *  Includes the packet header
   528         *
   529         *  @param(Hdr* pHdr)   pointer to the packet header
   530         */
   531        @Macro Int32 getMinEventLength(Hdr *pHdr);
   532    
   533        /*!
   534         *  ======== setEventLength ========
   535         *  Sets the packet length (in bytes) from the packet header
   536         *
   537         *  Includes the packet header
   538         *
   539         *  @param(Hdr* msgHdr)   pointer to the packet header
   540         *  @param(pktLength) the new packet length
   541         *
   542         */
   543        @Macro Void setEventLength(Hdr *pHdr, Bits32 pktLength);
   544        
   545        /*!
   546         *  ======== setEventLengthFast ========
   547         *  Sets the packet length (in bytes) from the packet header
   548         *  by just writing the length, instead of reading the old
   549         *  value, setting the length, and writing it back.
   550         *
   551         *  Includes the packet header
   552         *
   553         *  @param(Hdr* msgHdr)   pointer to the packet header
   554         *  @param(pktLength) the new packet length
   555         *
   556         */
   557        @Macro Void setEventLengthFast(Hdr *pHdr, Bits32 pktLength);
   558        
   559        /*!
   560         * ======== setMinEventPacketLength ========
   561         * Set UIA packet length of the completed packet
   562         *
   563         *  @param(Hdr* msgHdr)   pointer to the packet header
   564         *  @param(pktLength) the new packet length
   565         *  @param(loggerInstanceId) the logger's instanceId
   566         *  @param(senderAdrs) the sender address (i.e. DNUM or endpoint ID, 0 if only 1 CPU per device)
   567         */
   568        @Macro Void setMinEventPacketLength(Hdr *pHdr, Bits32 pktLength, 
   569                                    UInt16 loggerInstanceId, 
   570                                    UInt16 senderAdrs);
   571        /*!
   572         *  ======== getLength ========
   573         *  Gets the packet length (in bytes) from the packet header
   574         *
   575         *  Includes the packet header
   576         *
   577         *  @param(Hdr* msgHdr)   pointer to the packet header
   578         */
   579        Int32 getLength(Hdr *pHdr);
   580    
   581        /*!
   582         *  ======== getSequenceCount ========
   583         *  gets the sequence count from the packet header
   584         *
   585         *  Message header is always layed out as big endian (network order).
   586         *  This macro is designed to work on both little endian and
   587         *  big endian targets, since 32b long words are consistently
   588         *  handled for both endianness - it is only when converting
   589         *  from bytes to longs that bit orders get swapped.
   590         *  #ifdef xdc_target__bigEndian can be used if necessary.
   591         *
   592         *  @param(Hdr* msgHdr)   pointer to the packet header
   593         */
   594        @Macro UInt16 getSequenceCount(Hdr *pHdr);
   595    
   596        /*!
   597         *  ======== setSequenceCount ========
   598         *  sets the packet sequence count in the 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         *  @param(seqCount) the new packet sequence count
   609         */
   610        @Macro Void setSequenceCount(Hdr *pHdr, Bits16 seqCount);
   611        
   612        /*!
   613         *  ======== setSequenceCountFast ========
   614         *  Sets the packet sequence count in the packet header
   615         *  by directly writing the word, and not reading it first.
   616         *
   617         *  Message header is always layed out as big endian (network order).
   618         *  This macro is designed to work on both little endian and
   619         *  big endian targets, since 32b long words are consistently
   620         *  handled for both endianness - it is only when converting
   621         *  from bytes to longs that bit orders get swapped.
   622         *  #ifdef xdc_target__bigEndian can be used if necessary.
   623         *
   624         *  @param(Hdr* msgHdr)   pointer to the packet header
   625         *  @param(seqCount) the new packet sequence count
   626         */
   627        @Macro Void setSequenceCountFast(Hdr *pHdr, Bits16 seqCount);
   628        
   629        /*!
   630         *  ======== setSequenceCounts ========
   631         *  sets the packet sequence count and the event sequence count for the first 
   632         *  event in the packet header
   633         *      
   634         *  Message header is always layed out as big endian (network order).
   635         *  This macro is designed to work on both little endian and
   636         *  big endian targets, since 32b long words are consistently
   637         *  handled for both endianness - it is only when converting
   638         *  from bytes to longs that bit orders get swapped.
   639         *  #ifdef xdc_target__bigEndian can be used if necessary.
   640         *   
   641         *  @param(Hdr* pHdr)   pointer to the packet header
   642         *  @param(pktSeqCount) the new packet sequence count
   643         *  @param(eventSeqCount) the event sequence count for the first event in the packet
   644         */    
   645        @Macro Void setSequenceCounts(Hdr *pHdr, Bits16 pktSeqCount, Bits16 eventSeqCount );
   646        
   647        /*!
   648         *  ======== setMinEventPacketSequenceCountFast ========
   649         *   stores the current event sequence number and 
   650         *   12 msbs of last timestamp in the packet header
   651         *
   652         *  Message header is always layed out as big endian (network order).
   653         *  This macro is designed to work on both little endian and
   654         *  big endian targets, since 32b long words are consistently
   655         *  handled for both endianness - it is only when converting
   656         *  from bytes to longs that bit orders get swapped.
   657         *  #ifdef xdc_target__bigEndian can be used if necessary.
   658         *
   659         *  @param(Hdr* pHdr)   pointer to the packet header
   660         *  @param(pktSeqCount) the new packet sequence count
   661         *  @param(eventSeqCount) the event sequence count for the first event in the packet
   662         */
   663        @Macro Void setMinEventPacketSequenceCount(Hdr *pHdr,  Bits16 pktSeqCount, Bits16 eventSeqCount);
   664    
   665        /*! @_nodoc
   666         *  ======== getLoggerPriority ========
   667         *  gets the logger priority field from the event packet header
   668         *
   669         *  Message header is always layed out as big endian (network order).
   670         *  This macro is designed to work on both little endian and
   671         *  big endian targets, since 32b long words are consistently
   672         *  handled for both endianness - it is only when converting
   673         *  from bytes to longs that bit orders get swapped.
   674         *  #ifdef xdc_target__bigEndian can be used if necessary.
   675         *
   676         *  @param(Hdr* msgHdr)   pointer to the packet header
   677         *  @a(return) the priority of the logger that logged the events
   678         *  @see IUIATransfer#Priority
   679         */
   680        @Macro IUIATransfer.Priority getLoggerPriority(Hdr *pHdr);
   681    
   682        /*! @_nodoc
   683         *  ======== setLoggerPriority ========
   684         *  sets the logger priority field in the event 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         *  @param(priority) the logger priority ( @see IUIATransfer#Priority )
   695         */
   696        @Macro Void setLoggerPriority(Hdr *pHdr, IUIATransfer.Priority priority);
   697        /*!
   698         *  ======== getLoggerModuleId ========
   699         *  gets the logger ID from the event packet header
   700         *
   701         *  Message header is always layed out as big endian (network order).
   702         *  This macro is designed to work on both little endian and
   703         *  big endian targets, since 32b long words are consistently
   704         *  handled for both endianness - it is only when converting
   705         *  from bytes to longs that bit orders get swapped.
   706         *  #ifdef xdc_target__bigEndian can be used if necessary.
   707         *
   708         *  @param(Hdr* msgHdr)   pointer to the packet header
   709         */
   710        @Macro Bits16 getLoggerModuleId(Hdr *pHdr);
   711    
   712        /*!
   713         *  ======== setLoggerModuleId ========
   714         *  sets the module ID in the event packet header
   715         *
   716         *  Message header is always layed out as big endian (network order).
   717         *  This macro is designed to work on both little endian and
   718         *  big endian targets, since 32b long words are consistently
   719         *  handled for both endianness - it is only when converting
   720         *  from bytes to longs that bit orders get swapped.
   721         *  #ifdef xdc_target__bigEndian can be used if necessary.
   722         *
   723         *  @param(Hdr* msgHdr)   pointer to the packet header
   724         *  @param(loggerModuleId) the moduleID of the logger that logged the events
   725         */
   726        @Macro Void setLoggerModuleId(Hdr *pHdr, Bits16 loggerModuleId);
   727    
   728        /*!
   729         *  ======== getLoggerInstanceId ========
   730         *  gets the logger instance ID from the event packet header
   731         *
   732         *  Message header is always layed out as big endian (network order).
   733         *  This macro is designed to work on both little endian and
   734         *  big endian targets, since 32b long words are consistently
   735         *  handled for both endianness - it is only when converting
   736         *  from bytes to longs that bit orders get swapped.
   737         *  #ifdef xdc_target__bigEndian can be used if necessary.
   738         *
   739         *  @param(Hdr* msgHdr)   pointer to the packet header
   740         */
   741        @Macro Bits16 getLoggerInstanceId(Hdr *pHdr);
   742    
   743        /*!
   744         *  ======== setLoggerInstanceId ========
   745         *  sets the sequence count in the packet header
   746         *
   747         *  Message header is always layed out as big endian (network order).
   748         *  This macro is designed to work on both little endian and
   749         *  big endian targets, since 32b long words are consistently
   750         *  handled for both endianness - it is only when converting
   751         *  from bytes to longs that bit orders get swapped.
   752         *  #ifdef xdc_target__bigEndian can be used if necessary.
   753         *
   754         *  @param(Hdr* msgHdr)   pointer to the packet header
   755         *  @param(seqCount) the new packet sequence count
   756         */
   757        @Macro Void setLoggerInstanceId(Hdr *pHdr, Bits16 loggerInstanceId);
   758    
   759        /*!
   760         *  ======== getMsgType ========
   761         *  gets the packet type from the packet header
   762         *
   763         *  Message header is always layed out as big endian (network order).
   764         *  This macro is designed to work on both little endian and
   765         *  big endian targets, since 32b long words are consistently
   766         *  handled for both endianness - it is only when converting
   767         *  from bytes to longs that bit orders get swapped.
   768         *  #ifdef xdc_target__bigEndian can be used if necessary.
   769         *
   770         *  @param(Hdr* pHdr)   pointer to the packet header
   771         */
   772        @Macro MsgType getMsgType(Hdr *pHdr);
   773    
   774        /*!
   775         *  ======== setMsgType ========
   776         *  sets the packet type in the packet header
   777         *
   778         *  Message header is always layed out as big endian (network order).
   779         *  This macro is designed to work on both little endian and
   780         *  big endian targets, since 32b long words are consistently
   781         *  handled for both endianness - it is only when converting
   782         *  from bytes to longs that bit orders get swapped.
   783         *  #ifdef xdc_target__bigEndian can be used if necessary.
   784         *
   785         *  @param(Hdr* msgHdr)   pointer to the packet header
   786         *  @param(msgType) the new packet type
   787         */
   788        @Macro Void setMsgType(Hdr *pHdr, MsgType msgType);
   789    
   790        /*!
   791         *  ======== getCmdId ========
   792         *  gets the packet type from the packet header
   793         *
   794         *  Message header is always layed out as big endian (network order).
   795         *  This macro is designed to work on both little endian and
   796         *  big endian targets, since 32b long words are consistently
   797         *  handled for both endianness - it is only when converting
   798         *  from bytes to longs that bit orders get swapped.
   799         *  #ifdef xdc_target__bigEndian can be used if necessary.
   800         *
   801         *  @param(Hdr* msgHdr)   pointer to the packet header
   802         */
   803        @Macro UInt16 getCmdId(Hdr *pHdr);
   804    
   805        /*!
   806         *  ======== setCmdId ========
   807         *  sets the command Id in the packet header
   808         *
   809         *  Message header is always layed out as big endian (network order).
   810         *  This macro is designed to work on both little endian and
   811         *  big endian targets, since 32b long words are consistently
   812         *  handled for both endianness - it is only when converting
   813         *  from bytes to longs that bit orders get swapped.
   814         *  #ifdef xdc_target__bigEndian can be used if necessary.
   815         *
   816         *  @param(Hdr* msgHdr)   pointer to the packet header
   817         *  @param(cmdId) the new command Id
   818         */
   819        @Macro Void setCmdId(Hdr *pHdr, UInt16 cmdId);
   820    
   821        /*!
   822         *  ======== getServiceId ========
   823         *  gets the packet type from the packet header
   824         *
   825         *  Message header is always layed out as big endian (network order).
   826         *  This macro is designed to work on both little endian and
   827         *  big endian targets, since 32b long words are consistently
   828         *  handled for both endianness - it is only when converting
   829         *  from bytes to longs that bit orders get swapped.
   830         *  #ifdef xdc_target__bigEndian can be used if necessary.
   831         *
   832         *  @param(Hdr* msgHdr)   pointer to the packet header
   833         */
   834        @Macro UInt16 getServiceId(Hdr *pHdr);
   835        /*!
   836         *  ======== setServiceId ========
   837         *  sets the packet type in the packet header
   838         *
   839         *  Message header is always layed out as big endian (network order).
   840         *  This macro is designed to work on both little endian and
   841         *  big endian targets, since 32b long words are consistently
   842         *  handled for both endianness - it is only when converting
   843         *  from bytes to longs that bit orders get swapped.
   844         *  #ifdef xdc_target__bigEndian can be used if necessary.
   845         *
   846         *  @param(Hdr* msgHdr)   pointer to the packet header
   847         *  @param(serviceId) the new service Id
   848         */
   849        @Macro Void setServiceId(Hdr *pHdr, UInt16 serviceId);
   850    
   851        /*!
   852         * ======== getTag =========
   853         * gets the 32b tag field from the packet header
   854         *
   855         *  @param(Hdr* msgHdr)   pointer to the packet header
   856         */
   857        @Macro Bits32 getTag(Hdr *pHdr);
   858    
   859        /*!
   860         * ======== setTag =========
   861         * sets the 32b tag field in the packet header
   862         *
   863         *  @param(Hdr* msgHdr)   pointer to the packet header
   864         *  @param(tagValue) the tag value to store in the header
   865         */
   866        @Macro Void setTag(Hdr *pHdr, Bits32 tagValue);
   867    
   868        /*!
   869         *  ======== getDestAdrs ========
   870         *  gets the packet destination address from the packet header
   871         *
   872         *  Message header is always layed out as big endian (network order).
   873         *  This macro is designed to work on both little endian and
   874         *  big endian targets, since 32b long words are consistently
   875         *  handled for both endianness - it is only when converting
   876         *  from bytes to longs that bit orders get swapped.
   877         *  #ifdef xdc_target__bigEndian can be used if necessary.
   878         *
   879         *  Example1 :
   880         *   Void example1(UIAPacket_Object *obj){
   881         *      Int16 destAdrs = UIAPacket_getDestAdrs(&obj->hdr);
   882         *      ...
   883         *   }
   884         *  Example2 :
   885         *    Void example2(UIAPacket_Hdr *pHdr){
   886         *      Int16 destAdrs = UIAPacket_getDestAdrs(pHdr);
   887         *      ...
   888         *    }
   889         *
   890         *  @param(Hdr* msgHdr)   pointer to the packet header
   891         */
   892        @Macro UInt16 getDestAdrs(Hdr *pHdr);
   893    
   894        /*!
   895         *  ======== setDestAdrs ========
   896         *  sets the packet destination address in the packet header
   897         *
   898         *  The destination address identifies which endpoint (i.e. which
   899         *  CPU or process) the packet should be sent to.
   900         *  0 is used to broadcast the packet.
   901         *  1 is used for point-to-point connections.
   902         *  Replies to a packet always use the sender address in the
   903         *  originating packet as the destination address.
   904         *  Destination addresses other than the above can be determined
   905         *  via a discovery process.
   906         *
   907         *  Message header is always layed out as big endian (network order).
   908         *  This macro is designed to work on both little endian and
   909         *  big endian targets, since 32b long words are consistently
   910         *  handled for both endianness - it is only when converting
   911         *  from bytes to longs that bit orders get swapped.
   912         *  #ifdef xdc_target__bigEndian can be used if necessary.
   913         *
   914         *  @param(Hdr* msgHdr)   pointer to the packet header
   915         *  @param(destAdrs) the new destination address
   916         */
   917        @Macro Void setDestAdrs(Hdr *pHdr, UInt16 destAdrs);
   918    
   919        /*!
   920         *  ======== getSenderAdrs ========
   921         *  gets the packet sender address from the packet header
   922         *
   923         *  Message header is always layed out as big endian (network order).
   924         *  This macro is designed to work on both little endian and
   925         *  big endian targets, since 32b long words are consistently
   926         *  handled for both endianness - it is only when converting
   927         *  from bytes to longs that bit orders get swapped.
   928         *  #ifdef xdc_target__bigEndian can be used if necessary.
   929         *
   930         *  @param(Hdr* msgHdr)   pointer to the packet header
   931         */
   932        @Macro UInt16 getSenderAdrs(Hdr *pHdr);
   933    
   934        /*!
   935         *  ======== setSenderAdrs ========
   936         *  sets the packet sender address in the packet header
   937         *
   938         *  The sender address identifies which endpoint (i.e. which
   939         *  CPU or process) the packet is coming from
   940         *  1 is used by default.
   941         *  Sender addresses other than 1 can be set via configuration
   942         *  (e.g. to identify which CPU core a packet originated from).
   943         *
   944         *  Message header is always layed out as big endian (network order).
   945         *  This macro is designed to work on both little endian and
   946         *  big endian targets, since 32b long words are consistently
   947         *  handled for both endianness - it is only when converting
   948         *  from bytes to longs that bit orders get swapped.
   949         *  #ifdef xdc_target__bigEndian can be used if necessary.
   950         *
   951         *  @param(Hdr* msgHdr)   pointer to the packet header
   952         *  @param(senderAdrs) the new destination address
   953         */
   954        @Macro Void setSenderAdrs(Hdr *pHdr, UInt16 senderAdrs);
   955    
   956        /*!
   957         * ======== initMsgHdr ========
   958         * initializes all bitfields in the message header
   959         *
   960         *  @param(Hdr* msgHdr)   pointer to the packet header
   961         *  @param(endianness) endianness of the payload
   962         *  @param(msgType) the packet type
   963         *  @param(msgLength) the number of Bytes in the packet, including the
   964         *     header and footer
   965         *  @param(serviceId) the service Id
   966         *  @param(seqCount) the sequence number for the packet
   967         *  @param(cmdId) the command Id
   968         *  @param(tag) the tag value to store in the header
   969         *  @param(destAdrs) the destination address
   970         *  @param(senderAdrs) the sender address
   971         */
   972        @Macro Void initMsgHdr(Hdr *pHdr, PayloadEndian endianness,
   973                               MsgType msgType, UInt16 msgLength,
   974                               UInt16 serviceId, UInt16 seqCount,
   975                               UInt16 cmdId,  UInt32 tag,
   976                               UInt16 destAdrs, UInt16 senderAdrs);
   977    
   978        /*!
   979         * ======== initEventRecHdr ========
   980         * initializes all bitfields in the message header
   981         *
   982         *  @param(Hdr* msgHdr)   pointer to the packet header
   983         *  @param(endianness) endianness of the payload
   984         *  @param(eventLength) the number of Bytes in the packet, including
   985         *     the header and footer
   986         *  @param(seqCount) the sequence number for the packet
   987         *  @param(priority) the logger's priority
   988         *  @param(moduleId) the logger's module Id
   989         *  @param(instanceId) the logger's instanceId
   990         *  @param(destAdrs) the destination address
   991         *  @param(senderAdrs) the sender address
   992         */
   993        @Macro Void initEventRecHdr(Hdr *pHdr, PayloadEndian endianness,
   994                                    UInt32 eventLength, UInt16 seqCount,
   995                                    IUIATransfer.Priority priority, UInt16 moduleId,
   996                                    UInt16 instanceId, UInt16 destAdrs,
   997                                    UInt16 senderAdrs);
   998    
   999        /*!
  1000         * ======== initMinEventRecHdr ========
  1001         * initializes all bitfields in the minimum event packet header,
  1002         * setting the length, sequence count and last timestamp fields to 0
  1003         *
  1004         *  @param(Hdr* pPktHdr)   pointer to the packet header
  1005         *  @param(endianness) endianness of the payload
  1006         *  @param(loggerInstanceId) the logger's instanceId
  1007         *  @param(senderAdrs) the sender address (i.e. DNUM / endpoint ID for the CPU core)
  1008         */
  1009        @Macro Void initMinEventRecHdr(Hdr *pHdr, PayloadEndian endianness, 
  1010                                    UInt16 loggerInstanceId, 
  1011                                    UInt16 senderAdrs);
  1012        /*!
  1013         * ======== getFooter ========
  1014         * returns the integer to use as the packet footer
  1015         *
  1016         *  @param(Hdr* pHdr)   pointer to the packet header
  1017         */
  1018        @Macro Int32 getFooter(Hdr *pHdr);
  1019    
  1020        /*!
  1021         * ======== setInvalidHdr ========
  1022         * Used to set the header type as invalid
  1023         *
  1024         *  @param(Hdr* pHdr)   pointer to the packet header
  1025         *  @param(eventLength) the number of Bytes in the packet of memory
  1026         *       that is invalid (including the first word of the 32-bit hdr)
  1027         */
  1028        @Macro Void setInvalidHdr(Hdr *pHdr, UInt32 eventLength);
  1029    }