1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32
33 34 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 }