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     * ======== EventHdr.xdc ========
    35     */
    36    package ti.uia.runtime;
    37    
    38    /*!
    39     *  ======== EventHdr ========
    40     *  Module defines the header format to be used when logging an event
    41     *
    42     *  Each event's first word includes the type, length of the event and
    43     *  sequence number. The length includes the first word and is in bytes.
    44     *
    45     *  The following is the desciption of the first word.
    46     *
    47     *  @p(code)
    48     *  EventHdr
    49     *   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
    50     *   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
    51     *  |---------------------------------------------------------------|
    52     *  |H H H H H|L L L L L L L L L L L|S S S S S S S S S S S S S S S S|
    53     *  |---------------------------------------------------------------|
    54     *
    55     *  H = HdrType         (5-bits)
    56     *  L = Event Length    (11-bits)
    57     *  S = Sequence Number (16-bits)
    58     *  @p
    59     *
    60     *  There are currently 4 different types of events supported in UIA. The
    61     *  following discusses the format of each one of the types.
    62     *
    63     *  @p(code)
    64     *  HdrType_Event
    65     *    word0: EventHdr
    66     *    word1: event Id (top 16 bits) & module Id (bottom 16 bits)
    67     *
    68     *  HdrType_EventWithTimestamp
    69     *    word0: EventHdr
    70     *    word1: Timestamp lower 32 bits
    71     *    word2: Timestamp upper 32 bits
    72     *    word3: event Id (top 16 bits) & module Id (bottom 16 bits)
    73     *
    74     *  HdrType_EventWithSnapshotId
    75     *    word0: EventHdr
    76     *    word1: event Id (top 16 bits) & module Id (bottom 16 bits)
    77     *    word2: filename pointer
    78     *    word3: linenum
    79     *    word4: snapshotId
    80     *    word5: address where the data was located
    81     *    word6: total length of data (top 16-bits)
    82     *           length for this record (bottom 16 bits)
    83     *    word7: format pointer
    84     *    data:  the rest of the record contains the data
    85     *
    86     *  HdrType_EventWithSnapshotIdAndTimestamp:
    87     *    word0: EventHdr
    88     *    word1: Timestamp lower 32 bits
    89     *    word2: Timestamp upper 32 bits
    90     *    word3: event Id (top 16 bits) & module Id (bottom 16 bits)
    91     *    word4: filename pointer
    92     *    word5: linenum
    93     *    word6: snapshotId
    94     *    word7: address where the data was located
    95     *    word8: total length of data (top 16-bits)
    96     *           length for this record (bottom 16 bits)
    97     *    word9: format pointer
    98     *    data:  the rest of the record contains the data
    99     *  @p
   100     *
   101     *  Snapshot events can span multiple records. The snapshotId is used to
   102     *  correlate the records when this occurs.
   103     *  The length field (word6 or word8) contains two lengths. The bottom 16 bits
   104     *  length of data for this record. The top 16 bits is the sum of all
   105     *  lengths for this specific snapshotId.
   106     *
   107     *  The address field points to the location of the data. When the snapshot
   108     *  spans multiple records, the address field is updated accordingly. Therefore
   109     *  this field can be used to detect dropped records. Note the snapshot
   110     *  event data is contiguous.
   111     */
   112    @CustomHeader
   113    module EventHdr {
   114        /*!
   115         *  ======== HdrType ========
   116         *  Enumeration of the various types of events headers
   117         *
   118         *  Stored in a 5 bit bitfield (b31-b27) of the first word in the event.
   119         */
   120        enum HdrType {
   121            HdrType_Event = 0, /*! Event with no timestamp or other optional parameters */
   122            HdrType_EventWithTimestamp = 1, /*! Event with 64 bit Timestamp */
   123            HdrType_EventWithSnapshotId = 2, /*! Snapshot event */
   124            HdrType_EventWithSnapshotIdAndTimestamp = 3, /*! Snapshot event with 64 bit Timestamp */
   125            HdrType_Reserved4 = 4, /*! reserved for future use  */
   126            HdrType_Reserved5 = 5, /*! reserved for future use */
   127            HdrType_Reserved6 = 6, /*! reserved for future use */
   128            HdrType_Reserved7 = 7, /*! reserved for future use */
   129            HdrType_Reserved8 = 8, /*! reserved for future use */
   130            HdrType_Reserved9 = 9, /*! reserved for future use */
   131            HdrType_Reserved10 = 10, /*! reserved for future use */
   132            HdrType_Reserved11 = 11, /*! reserved for future use */
   133            HdrType_Reserved12 = 12, /*! reserved for future use */
   134            HdrType_Reserved13 = 13, /*! reserved for future use */
   135            HdrType_Reserved14 = 14, /*! reserved for future use */
   136            HdrType_Reserved15 = 15, /*! reserved for future use */
   137            HdrType_Reserved16 = 16, /*! reserved for future use */
   138            HdrType_Reserved17 = 17, /*! reserved for future use */
   139            HdrType_Reserved18 = 18, /*! reserved for future use */
   140            HdrType_Reserved19 = 19, /*! reserved for future use */
   141            HdrType_Reserved20 = 20, /*! reserved for future use */
   142            HdrType_Reserved21 = 21, /*! reserved for future use */
   143            HdrType_Reserved22 = 22, /*! reserved for future use */
   144            HdrType_Reserved23 = 23, /*! reserved for future use */
   145            HdrType_Reserved24 = 24, /*! reserved for future use */
   146            HdrType_Reserved25 = 25, /*! reserved for future use */
   147            HdrType_Reserved26 = 26, /*! reserved for future use */
   148            HdrType_Reserved27 = 27, /*! reserved for future use */
   149            HdrType_Reserved28 = 28, /*! reserved for future use */
   150            HdrType_Reserved29 = 29, /*! reserved for future use */
   151            HdrType_Reserved30 = 30, /*! reserved for future use */
   152            HdrType_Reserved31 = 31  /*! reserved for future use */
   153        };
   154    
   155        /*!
   156         *  ======== getHdrType ========
   157         *  Gets the message header type from the first word of the event header
   158         *
   159         *  @param(eventWord1)   first word of the event header
   160         *
   161         *  @a(returns)          HdrType of the event
   162         */
   163        @Macro HdrType getHdrType(UInt32 eventWord1);
   164    
   165        /*!
   166         *  ======== setHdrType ========
   167         *  Sets the header type in the event header
   168         *
   169         *  @param(eventWord1)   the first word of the event header to be updated
   170         *  @param(HdrType hdrType)  the new header type
   171         */
   172        @Macro Void setHdrType(UInt32 eventWord1, EventHdr.HdrType hdrType);
   173    
   174        /*!
   175         *  ======== getLength ========
   176         *  gets the event length (in bytes) from the event header
   177         *
   178         *  @param(eventWord1)   first word of the event header
   179         */
   180        @Macro SizeT getLength(UInt32 eventWord1);
   181    
   182        /*!
   183         *  ======== setLength ========
   184         *  sets the event length (in bytes) in the event header
   185         *
   186         *  @param(eventWord1)   first word of the event header
   187         *  @param(eventLength)    the new event length
   188         */
   189        @Macro Void setLength(UInt32 eventWord1, SizeT eventLength);
   190    
   191        /*!
   192         *  ======== getSeqCount ========
   193         *  gets the sequence count from the message header
   194         *
   195         *  @param(eventWord1)   first word of the event header
   196         */
   197        @Macro UInt16 getSeqCount(UInt32 eventWord1);
   198    
   199        /*!
   200         *  ======== setSeqCount ========
   201         *  sets the sequence count in the message header
   202         *
   203         *  @param(eventWord1)   first word of the event header
   204         *  @param(seqCount)     the new message sequence count
   205         */
   206        @Macro Void setSeqCount(UInt32 eventWord1, UInt16 seqCount);
   207    
   208        /*!
   209         *  ======== genEventHdrWord1 ========
   210         *  generates the first word to use in an Event header
   211         *
   212         *  @param(numBytesInEventMsg)  number of bytes in the event
   213         *  @param(seqCount)            sequence count number to tag the event with
   214         *  @param(isTimestampEnabled)  flag indicating if a 64b timestamp is
   215         *                              logged with the event
   216         */
   217        @Macro UInt32 genEventHdrWord1(SizeT numBytesInEventMsg, UInt16 seqCount,
   218                                       Bool isTimestampEnabled);
   219    }