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 * 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 }