1    /*
     2     * Copyright (c) 2013-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     * ======== 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     *  EventHdr for HdrType_EventWithPrevLen* and HdrType_SnapshotEventWithPrevLen*
   113     *   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
   114     *   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
   115     *  |---------------------------------------------------------------|
   116     *  |H H H H H|L L L L L L L L L L L|P P P P P P P P P P P|S S S S S|
   117     *  |---------------------------------------------------------------|
   118     *
   119     *  H = HdrType         (5-bits)
   120     *  L = Event Length in bytes    (11-bits: # of bytes in current event)
   121     *  P = Number of Bytes in Previous Event (5-bits: # of bytes in prev. event)
   122     *  S = Sequence Number (5-bits)
   123     */
   124    @CustomHeader
   125    module EventHdr {
   126        /*!
   127         *  ======== HdrType ========
   128         *  Enumeration of the various types of events headers
   129         *
   130         *  Stored in a 5 bit bitfield (b31-b27) of the first word in the event.
   131         */
   132        enum HdrType {
   133            HdrType_Event = 0, /*! Event with no timestamp or other optional parameters */
   134            HdrType_EventWithTimestamp = 1, /*! Event with 64 bit Timestamp */
   135            HdrType_EventWithSnapshotId = 2, /*! Snapshot event */
   136            HdrType_EventWithSnapshotIdAndTimestamp = 3, /*! Snapshot event with 64 bit Timestamp */
   137            HdrType_EventWith32bTimestamp = 4, /*! Event with 32 bit Timestamp */
   138            HdrType_EventWithTimestampAndEndpointId = 5,
   139            HdrType_EventWithSnapshotIdAnd32bTimestamp = 6, /*! Snapshot event with 32 bit Timestamp */
   140            HdrType_EventWithSnapshotIdAndTimestampAndEndpointId = 7,
   141            HdrType_EventWithPrevLenWithNoTimestamp = 8, /*! reverse param event with prev. length field */
   142            HdrType_EventWithPrevLenWith32bTimestamp = 9,  /*! reverse param event with prev. length field */
   143            HdrType_EventWithPrevLenWith64bTimestamp = 10,  /*! reverse param event with prev. length field */
   144            HdrType_SnapshotEventWithPrevLen = 11, /*! Snapshot event with no timestamp*/
   145            HdrType_SnapshotEventWithPrevLenAnd64bTimestamp = 12, /*! Snapshot event with 64 bit Timestamp */
   146            HdrType_Reserved13 = 13, /*! reserved for future use */
   147            HdrType_Reserved14 = 14, /*! reserved for future use */
   148            HdrType_Reserved15 = 15, /*! reserved for future use */
   149            HdrType_Reserved16 = 16, /*! reserved for future use */
   150            HdrType_Reserved17 = 17, /*! reserved for future use */
   151            HdrType_Reserved18 = 18, /*! reserved for future use */
   152            HdrType_Reserved19 = 19, /*! reserved for future use */
   153            HdrType_Reserved20 = 20, /*! reserved for future use */
   154            HdrType_Reserved21 = 21, /*! reserved for future use */
   155            HdrType_Reserved22 = 22, /*! reserved for future use */
   156            HdrType_Reserved23 = 23, /*! reserved for future use */
   157            HdrType_Reserved24 = 24, /*! reserved for future use */
   158            HdrType_Reserved25 = 25, /*! reserved for future use */
   159            HdrType_Reserved26 = 26, /*! reserved for future use */
   160            HdrType_Reserved27 = 27, /*! reserved for future use */
   161            HdrType_Reserved28 = 28, /*! reserved for future use */
   162            HdrType_Reserved29 = 29, /*! reserved for future use */
   163            HdrType_Reserved30 = 30, /*! reserved for future use */
   164            HdrType_Reserved31 = 31  /*! reserved for future use */
   165        };
   166    
   167        /*!
   168         *  ======== getHdrType ========
   169         *  Gets the message header type from the first word of the event header
   170         *
   171         *  @param(eventWord1)   first word of the event header
   172         *
   173         *  @a(returns)          HdrType of the event
   174         */
   175        @Macro HdrType getHdrType(UInt32 eventWord1);
   176    
   177        /*!
   178         *  ======== setHdrType ========
   179         *  Sets the header type in the event header
   180         *
   181         *  @param(eventWord1)   the first word of the event header to be updated
   182         *  @param(HdrType hdrType)  the new header type
   183         */
   184        @Macro Void setHdrType(UInt32 eventWord1, EventHdr.HdrType hdrType);
   185    
   186        /*!
   187         *  ======== getLength ========
   188         *  gets the event length (in bytes) from the event header
   189         *
   190         *  @param(eventWord1)   first word of the event header
   191         */
   192        @Macro SizeT getLength(UInt32 eventWord1);
   193    
   194        /*!
   195         *  ======== setLength ========
   196         *  sets the event length (in bytes) in the event header
   197         *
   198         *  @param(eventWord1)   first word of the event header
   199         *  @param(eventLength)    the new event length
   200         */
   201        @Macro Void setLength(UInt32 eventWord1, SizeT eventLength);
   202    
   203        /*!
   204         *  ======== getSeqCount ========
   205         *  gets the sequence count from the message header
   206         *
   207         *  @param(eventWord1)   first word of the event header
   208         */
   209        @Macro UInt16 getSeqCount(UInt32 eventWord1);
   210    
   211        /*!
   212         *  ======== setSeqCount ========
   213         *  sets the sequence count in the message header
   214         *
   215         *  @param(eventWord1)   first word of the event header
   216         *  @param(seqCount)     the new message sequence count
   217         */
   218        @Macro Void setSeqCount(UInt32 eventWord1, UInt16 seqCount);
   219    
   220        /*!
   221         *  ======== genEventHdrWord1 ========
   222         *  generates the first word to use in an Event header
   223         *
   224         *  @param(numBytesInEvent)  number of bytes in the event
   225         *  @param(seqCount)            sequence count number to tag the event with
   226         *  @param(eventHdrType)        type of event header for this event
   227         */
   228        @Macro UInt32 genEventHdrWord1(SizeT numBytesInEvent, UInt16 seqCount,
   229                                       EventHdr.HdrType eventHdrType);
   230    
   231        /*!
   232         *  ======== genEventWithPrevLenHdrWord1 ========
   233         *  generates the first word to use in a header that contains the length of the previous event
   234         *
   235         *  @param(numBytesInEvent)  number of bytes in the event
   236         *  @param(numBytesInPrevEvent)  number of bytes in the previous event
   237         *  @param(seqCount)            sequence count number to tag the event with
   238         *  @param(eventHdrType)        type of event header for this event
   239         */
   240        @Macro UInt32 genEventWithPrevLenHdrWord1(SizeT numBytesInEvent, SizeT numBytesInPrevEvent, UInt16 seqCount,
   241                                       EventHdr.HdrType eventHdrType);
   242    
   243        /*!
   244         *  @_nodoc
   245         *  ======== getEventHdrWithPrevLenSeqCount ========
   246         *  Extract the sequence number from an EventHdr with previous length.
   247         *  For testing.
   248         */
   249        @Macro UInt32 getEventHdrWithPrevLenSeqCount(UInt32 word);
   250    
   251        /*!
   252         *  @_nodoc
   253         *  ======== getPrevLength ========
   254         *  Extract the length of the previous event from an EventHdr with previous
   255         *  length.  For testing.
   256         */
   257        @Macro UInt32 getPrevLength(UInt32 word);
   258    }