OpenCSD - CoreSight Trace Decode Library  0.10.0
prog_guide/prog_guide_generic_pkts.md
Go to the documentation of this file.
1 OpenCSD Library - Generic Trace Packet Descriptions {#generic_pkts}
2 ===================================================
3 
4 @brief Interpretation of the Generic Trace output packets.
5 
6 Generic Trace Packets - Collection.
7 -----------------------------------
8 
9 ### Packet interface ###
10 
11 The generic trace packets are the fully decoded output from the trace library.
12 
13 These are delivered to the client application in the form of a callback function. Packets from all trace sources
14 will use the same single callback function, with the CoreSight Trace ID provided to identify the source.
15 
16 The callback is in the form of an interface class ITrcGenElemIn, which has a single function:
17 
18 ~~~{.cpp}
19 virtual ocsd_datapath_resp_t TraceElemIn( const ocsd_trc_index_t index_sop,
20  const uint8_t trc_chan_id,
21  const OcsdTraceElement &elem
22  ) = 0;
23 ~~~
24 
25 The client program will create derived class providing this interface to collect trace packets from the library.
26 
27 The parameters describe the output packet and source channel:
28 |Parameter | Description |
29 |:--------------------------------|:------------------------------------------------------------------------|
30 | `ocsd_trc_index_t index_sop` | Index of the first byte of the trace packet that generated this output. |
31 | `uint8_t trc_chan_id` | The source CoreSight Trace ID. |
32 | `OcsdTraceElement &elem` | The packet class - wraps the `ocsd_generic_trace_elem` structure. |
33 
34 _Note_ : `index_sop` may be the same for multiple output packets. This is due to an one byte atom packet which
35 can represent multiple atoms and hence multiple ranges.
36 
37 The C-API provides a similarly specified callback function definition, with an additional opaque `void *` pointer
38 that the client application may use.
39 
40 ~~~{.c}
41 /** function pointer type for decoder outputs. all protocols, generic data element input */
42 typedef ocsd_datapath_resp_t (* FnTraceElemIn)( const void *p_context,
43  const ocsd_trc_index_t index_sop,
44  const uint8_t trc_chan_id,
45  const ocsd_generic_trace_elem *elem);
46 ~~~
47 
48 ### The Packet Structure ###
49 
50 ~~~{.c}
51 typedef struct _ocsd_generic_trace_elem {
52  ocsd_gen_trc_elem_t elem_type; /* Element type - remaining data interpreted according to this value */
53  ocsd_isa isa; /* instruction set for executed instructions */
54  ocsd_vaddr_t st_addr; /* start address for instruction execution range / inaccessible code address / data address */
55  ocsd_vaddr_t en_addr; /* end address (exclusive) for instruction execution range. */
56  ocsd_pe_context context; /* PE Context */
57  uint64_t timestamp; /* timestamp value for TS element type */
58  uint32_t cycle_count; /* cycle count for explicit cycle count element, or count for element with associated cycle count */
59  ocsd_instr_type last_i_type; /* Last instruction type if instruction execution range */
60  ocsd_instr_subtype last_i_subtype; /* sub type for last instruction in range */
61 
62  //! per element flags
63  union {
64  struct {
65  uint32_t last_instr_exec:1; /* 1 if last instruction in range was executed; */
66  uint32_t last_instr_sz:3; /* size of last instruction in bytes (2/4) */
67  uint32_t has_cc:1; /* 1 if this packet has a valid cycle count included (e.g. cycle count included as part of instruction range packet, always 1 for pure cycle count packet.*/
68  uint32_t cpu_freq_change:1; /* 1 if this packet indicates a change in CPU frequency */
69  uint32_t excep_ret_addr:1; /* 1 if en_addr is the preferred exception return address on exception packet type */
70  uint32_t excep_data_marker:1; /* 1 if the exception entry packet is a data push marker only, with no address information (used typically in v7M trace for marking data pushed onto stack) */
71  uint32_t extended_data:1; /* 1 if the packet extended data pointer is valid. Allows packet extensions for custom decoders, or additional data payloads for data trace. */
72  uint32_t has_ts:1; /* 1 if the packet has an associated timestamp - e.g. SW/STM trace TS+Payload as a single packet */
73  uint32_t last_instr_cond:1; /* 1 if the last instruction was conditional */
74  };
75  uint32_t flag_bits;
76  };
77 
78  //! packet specific payloads
79  union {
80  uint32_t exception_number; /* exception number for exception type packets */
81  trace_event_t trace_event; /* Trace event - trigger etc */
82  trace_on_reason_t trace_on_reason; /* reason for the trace on packet */
83  ocsd_swt_info_t sw_trace_info; /* software trace packet info */
84  uint32_t num_instr_range; /* number of instructions covered by range packet (for T32 this cannot be calculated from en-st/i_size) */
85 
86  };
87 
88  const void *ptr_extended_data; /* pointer to extended data buffer (data trace, sw trace payload) / custom structure */
89 
90 } ocsd_generic_trace_elem;
91 ~~~
92 
93 The packet structure contains multiple fields and flag bits. The validity of any of these fields or flags
94 is dependent on the `elem_type` member. The client program must not assume that field values will persist
95 between packets, and must process all valid data during the callback function.
96 
97 The packet reference guide below defines the fields valid for each packet type.
98 
99 --------------------------------------------------------------------------------------------------
100 
101 Generic Trace Packets - Packet Reference.
102 -----------------------------------------
103 
104 This section contains reference descriptions of each of the generic trace packets types define as part of the
105 `ocsd_gen_trc_elem_t` enum value that appears as the first `elem_type` field in the packet structure.
106 
107 The descriptions will include information on which fields in the packets are always valid, optional and any protocol specific information.
108 
109 The tags used in the reference are:-
110 - __packet fields valid__ : fields that are always valid and filled for this packet type.
111 - __packet fields optional__ : fields that _may_ be filled for this packet type.
112  The form `flag -> field` indicates a flag that may be set and the value that is valid if the flag is true
113 - __protocol specific__ : indicates type or fields may be source protocol specific.
114 
115 _Note_: while most of the packets are not protocol specific, there are some protocol differences that mean
116 certain types and fields will differ slightly across protocols. These differences are highlighted in the
117 reference.
118 
119 ### OCSD_GEN_TRC_ELEM_NO_SYNC ###
120 __packet fields valid__: None
121 
122 Element output before the decoder has synchronised with the input stream, or synchronisation is lost.
123 
124 ### OCSD_GEN_TRC_ELEM_INSTR_RANGE ###
125 __packet fields valid__: `isa, st_addr, en_addr, last_i_type, last_i_subtype, last_instr_exec, last_instr_sz, num_instr_range, last_instr_cond`
126 
127 __packet fields optional__: `has_cc -> cycle_count,`
128 
129 __protocol specific__ : ETMv3, PTM
130 
131 This should be the most common packet output for full trace decode. Represents a range of instructions of
132 a single `isa`, executed by the PE. Instruction byte range is from `st_addr` (inclusive) to `en_addr` (exclusive).
133 The total number of instructions executed for the range is given in `num_instr_range`.
134 
135 Information on the last instruction in the range is provided. `last_i_type` shows if the last instruction
136 was a branch or otherwise - which combined with `last_instr_exec` determines if the branch was taken.
137 The last instruction size in bytes is given, to allow clients to quickly determine the address of the last
138 instruction by subtraction from `en_addr`. This value can be 2 or 4 bytes in the T32 instruction set.
139 
140 __ETMv3, PTM__ : These protocols can output a cycle count directly as part of the trace packet that generates
141 the trace range. In this case `has_cc` will be 1 and `cycle_count` will be valid.
142 
143 
144 ### OCSD_GEN_TRC_ELEM_ADDR_NACC ###
145 __packet fields valid__: `st_addr`
146 
147 Trace decoder found address in trace that cannot be accessed in the mapped memory images.
148 `st_addr` is the address that cannot be found.
149 
150 Decoder will wait for new address to appear in trace before attempting to restart decoding.
151 
152 
153 ### OCSD_GEN_TRC_ELEM_UNKNOWN ###
154 __packet fields valid__: None
155 
156 Decoder saw invalid packet for protocol being processed. Likely incorrect protocol settings, or corrupted
157 trace data.
158 
159 ### OCSD_GEN_TRC_ELEM_TRACE_ON ###
160 __packet fields valid__: trace_on_reason
161 
162 __packet fields optional__: `has_cc -> cycle_count,`
163 
164 __protocol specific__ : ETMv3, PTM
165 
166 Notification that trace has started / is synced after a discontinuity or at start of trace decode.
167 
168 __ETMv3, PTM__ : These protocols can output a cycle count directly as part of the trace packet that generates
169 the trace on indicator. In this case `has_cc` will be 1 and `cycle_count` will be valid.
170 
171 
172 ### OCSD_GEN_TRC_ELEM_EO_TRACE ###
173 __packet fields valid__: None
174 
175 Marker for end of trace data. Sent once for each CoreSight ID channel.
176 
177 ### OCSD_GEN_TRC_ELEM_PE_CONTEXT ###
178 __packet fields valid__: context
179 
180 __packet fields optional__: `has_cc -> cycle_count,`
181 
182 __protocol specific__ : ETMv3, PTM
183 
184 This packet indicates an update to the PE context - which may be the initial context in a trace stream, or a
185 change since the trace started.
186 
187 The context is contained in a `ocsd_pe_context` structure.
188 
189 ~~~{.c}
190 typedef struct _ocsd_pe_context {
191  ocsd_sec_level security_level; /* security state */
192  ocsd_ex_level exception_level; /* exception level */
193  uint32_t context_id; /* context ID */
194  uint32_t vmid; /* VMID */
195  struct {
196  uint32_t bits64:1; /* 1 if 64 bit operation */
197  uint32_t ctxt_id_valid:1; /* 1 if context ID value valid */
198  uint32_t vmid_valid:1; /* 1 if VMID value is valid */
199  uint32_t el_valid:1; /* 1 if EL value is valid (ETMv4 traces current EL, other protocols do not) */
200  };
201 } ocsd_pe_context;
202 ~~~
203 
204 __ETMv3, PTM__ : These protocols can output a cycle count directly as part of the trace packet that generates
205 the PE context. In this case `has_cc` will be 1 and `cycle_count` will be valid.
206 
207 __ETMv3__ : From ETM 3.5 onwards, exception_level can be set to `ocsd_EL2` when tracing through hypervisor code.
208 On all other occasions this will be set to `ocsd_EL_unknown`.
209 
210 
211 ### OCSD_GEN_TRC_ELEM_ADDR_UNKNOWN ###
212 __packet fields optional__: `has_cc -> cycle_count,`
213 
214 __protocol specific__: ETMv3
215 
216 This packet will only be seen when decoding an ETMv3 protocol source. This indicates that the decoder
217 is waiting for a valid address in order to process trace correctly.
218 
219 The packet can have a cycle count associated with it which the client must account for when tracking cycles used.
220 The packet will be sent once when unknown address occurs. Further `OCSD_GEN_TRC_ELEM_CYCLE_COUNT` packets may follow
221  before the decode receives a valid address to continue decode.
222 
223 
224 ### OCSD_GEN_TRC_ELEM_EXCEPTION ###
225 __packet fields valid__: `exception_number`
226 
227 __packet fields optional__: `has_cc -> cycle_count, excep_ret_addr -> en_addr, excep_data_marker`
228 
229 __protocol specific__: ETMv4, ETMv3, PTM
230 
231 All protocols will include the exception number in the packet.
232 
233 __ETMv4__ : This protocol may provide the preferred return address for the exception - this is the address of
234 the instruction that could be executed on exception return. This address appears in `en_addr` if `excep_ret_addr` = 1.
235 
236 __ETMv3__ : This can set the `excep_data_marker` flag. This indicates that the exception packet is a marker
237 to indicate exception entry in a 7M profile core, for the purposes of tracking data. This will __not__ provide
238 an exception number in this case.
239 
240 __PTM__ : Can have an associated cycle count (`has_cc == 1`), and may provide preferred return address in `en_addr`
241 if `excep_ret_addr` = 1.
242 
243 ### OCSD_GEN_TRC_ELEM_EXCEPTION_RET ###
244 __packet fields valid__: None
245 
246 Marker that a preceding branch was an exception return.
247 
248 ### OCSD_GEN_TRC_ELEM_TIMESTAMP ###
249 __packet fields valid__: `timestamp`
250 
251 __packet fields optional__: `has_cc -> cycle_count,`
252 
253 __protocol specific__: ETMv4, PTM
254 
255 The timestamp packet explicitly provides a timestamp value for the trace stream ID in the callback interface.
256 
257 __PTM__ : This can have an associated cycle count (`has_cc == 1`). For this protocol, the cycle count __is__ part
258 of the cumulative cycle count for the trace session.
259 
260 __ETMv4__ : This can have an associated cycle count (`has_cc == 1`). For this protocl, the cycle coun represents
261 the number of cycles between the previous cycle count packet and this timestamp packet, but __is not__ part of
262 the cumulative cycle count for the trace session.
263 
264 
265 ### OCSD_GEN_TRC_ELEM_CYCLE_COUNT ###
266 __packet fields valid__: `has_cc -> cycle_count`
267 
268 Packet contains a cycle count value. A cycle count value represents the number of cycles passed since the
269 last cycle count value seen. The cycle count value may be associated with a specific packet or instruction
270 range preceding the cycle count packet.
271 
272 Cycle count packets may be added together to build a cumulative count for the trace session.
273 
274 ### OCSD_GEN_TRC_ELEM_EVENT ###
275 __packet fields valid__: `trace_event`
276 
277 This is a hardware event injected into the trace by the ETM/PTM hardware resource programming. See the
278 relevent trace hardware reference manuals for the programming of these events.
279 
280 The `trace_event` is a `trace_event_t` structure that can have an event type - and an event number.
281 
282 ~~~{.c}
283 typedef struct _trace_event_t {
284  uint16_t ev_type; /* event type - unknown (0) trigger (1), numbered event (2)*/
285  uint16_t ev_number; /* event number if numbered event type */
286 } trace_event_t;
287 ~~~
288 
289 The event types depend on the trace hardware:-
290 
291 __ETMv4__ : produces numbered events. The event number is a bitfield of up to four events that occurred.
292 Events 0-3 -> bits 0-3. The bitfield allows a single packet to represent multiple different events occurring.
293 
294 _Note_: The ETMv4 specification has further information on timing of events and event packets. Event 0
295 is also considered a trigger event in ETMv4 hardware, but is not explicitly represented as such in the OCSD protocol.
296 
297 __PTM__, __ETMv3__ : produce trigger events. Event number always set to 0.
298 
299 
300 ### OCSD_GEN_TRC_ELEM_SWTRACE ###
301 __packet fields valid__: `sw_trace_info`
302 
303 __packet fields optional__: `has_ts -> timestamp`, ` extended_data -> ptr_extended_data`
304 
305 The Software trace packet always has a filled in `sw_trace_info` field to describe the current master and channel ID,
306 plus the packet type and size of any payload data.
307 
308 SW trace packets that have a payload will use the extended_data flag and pointer to deliver this data.
309 
310 SW trace packets that include timestamp information will us the `has_ts` flag and fill in the timestamp value.
311 
312 
313 ### OCSD_GEN_TRC_ELEM_CUSTOM ###
314 __packet fields optional__: `extended_data -> ptr_extended_data`,_any others_
315 
316 Custom protocol decoders can use this packet type to provide protocol specific information.
317 
318 Standard fields may be used for similar purposes as defined above, or the extended data pointer can reference
319 other data.
320 
321 --------------------------------------------------------------------------------------------------
322 
323 Generic Trace Packets - Notes on interpretation.
324 ------------------------------------------------
325 
326 The interpretation of the trace output should always be done with reference to the underlying protocol
327 specifications.
328 
329 While the output packets are in general protocol agnostic, there are some inevitable
330 differences related to the underlying protocol that stem from the development of the trace hardware over time.
331 
332 ### OCSD ranges and Trace Atom Packets ###
333 The most common raw trace packet in all the protocols is the Atom packet, and this packet is the basis for most of
334 the `OCSD_GEN_TRC_ELEM_INSTR_RANGE` packets output from the library. A trace range will be output for each atom
335 in the raw trace stream - the `last_instr_exec` flag taking the value of the Atom - 1 for E, 0 for N.
336 
337 `OCSD_GEN_TRC_ELEM_INSTR_RANGE` packets can also be generated for non-atom packets, where flow changes - e.g.
338 exceptions.
339 
340 
341 ### Multi feature OCSD output packets ###
342 Where a raw trace packet contains additional information on top of the basic packet data, then this additional
343 information will be added to the OCSD output packet and flagged accordingly (in the `flag_bits` union in the
344 packet structure).
345 
346 Typically this will be atom+cycle count packets in ETMv3 and PTM protocols. For efficiency and to retain
347 the coupling between the information an `OCSD_GEN_TRC_ELEM_INSTR_RANGE` packet will be output in this case
348 with a `has_cc` flag set and the `cycle_count` value filled.
349 
350 ETMv3 and PTM can add a cycle count to a number of packets, or explicitly emit a cycle count only packet. By
351 contrast ETMv4 only emits cycle count only packets.
352 
353 Clients processing the library output must be aware of these optional additions to the base packet. The
354 OCSD packet descriptions above outline where the additional information can occur.
355 
356 ### Cycle counts ###
357 
358 Cycle counts are cumulative, and represent cycles since the last cycle count output.
359 Explicit cycle count packets are associated with the previous range event, otherwise where a
360 packet includes a cycle count as additional information, then the count is associated with that
361 specific packet - which will often be a range packet.
362 
363 The only exception to this is where the underlying protocol is ETMv4, and a cycle count is included
364 in a timestamp packet. Here the cycle count represents that number of cycles since the last cycle count
365 packet that occurred before the timestamp packet was emitted. This cycle count is not part of the cumulative
366 count. See the ETMv4 specification for further details.
367 
368 
369 ### Correlation - timestamps and cycle counts ###
370 
371 Different trace streams can be correlated using either timestamps, or timestamps plus cycle counts.
372 
373 Both timestamps and cycle counts are enabled by programming ETM control registers, and it is also possible
374 to control the frequency that timestamps appear, or the threshold at which cycle count packets are emitted by
375 additional programming.
376 
377 The output of timestamps and cycle counts increases the amount of trace generated, very significantly when cycle
378 counts are present, so the choice of generating these elements needs to be balanced against the requirement
379 for their use.
380 
381 Decent correlation can be gained by the use of timestamps alone - especially if the source is programmed to
382 produce them more frequently than the default timestamp events. More precise correllation can be performed if
383 the 'gaps' between timestamps can be resolved using cycle counts.
384 
385 Correlation is performed by identifying the same/close timestamp values in two separate trace streams. Cycle counts
386 if present can then be used to resolve the correlation with additional accuracy.
387 
388 
389 
390 
391 
392 
393 
394 
395 
396 
397