1OpenCSD Library - Generic Trace Packet Descriptions {#generic_pkts} 2=================================================== 3 4@brief Interpretation of the Generic Trace output packets. 5 6Generic Trace Packets - Collection. 7----------------------------------- 8 9### Packet interface ### 10 11The generic trace packets are the fully decoded output from the trace library. 12 13These are delivered to the client application in the form of a callback function. Packets from all trace sources 14will use the same single callback function, with the CoreSight Trace ID provided to identify the source. 15 16The callback is in the form of an interface class ITrcGenElemIn, which has a single function: 17 18~~~{.cpp} 19virtual 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 25The client program will create derived class providing this interface to collect trace packets from the library. 26 27The 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 35can represent multiple atoms and hence multiple ranges. 36 37The C-API provides a similarly specified callback function definition, with an additional opaque `void *` pointer 38that the client application may use. 39 40~~~{.c} 41/** function pointer type for decoder outputs. all protocols, generic data element input */ 42typedef 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} 51typedef 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 uint32_t excep_ret_addr_br_tgt:1; /* 1 if exception return address (en_addr) is also the target of a taken branch addr from the previous range. */ 75 uint32_t excep_M_tail_chain:1; /* 1 if the exception is an M class exception with no pref ret address - tail chained or similar */ 76 77 }; 78 uint32_t flag_bits; 79 }; 80 81 //! packet specific payloads 82 union { 83 uint32_t exception_number; /* exception number for exception type packets */ 84 trace_event_t trace_event; /* Trace event - trigger etc */ 85 trace_on_reason_t trace_on_reason; /* reason for the trace on packet */ 86 ocsd_swt_info_t sw_trace_info; /* software trace packet info */ 87 uint32_t num_instr_range; /* number of instructions covered by range packet (for T32 this cannot be calculated from en-st/i_size) */ 88 unsync_info_t unsync_eot_info; /* additional information for unsync / end-of-trace packets. */ 89 trace_marker_payload_t sync_marker; /* marker element - sync later element to position in stream */ 90 trace_memtrans_t mem_trans; /* memory transaction packet - transaction event */ 91 trace_sw_ite_t sw_ite; /* PE sw instrumentation using FEAT_ITE */ 92 93 }; 94 95 const void *ptr_extended_data; /* pointer to extended data buffer (data trace, sw trace payload) / custom structure */ 96 97} ocsd_generic_trace_elem; 98~~~ 99 100The packet structure contains multiple fields and flag bits. The validity of any of these fields or flags 101is dependent on the `elem_type` member. The client program must not assume that field values will persist 102between packets, and must process all valid data during the callback function. 103 104The packet reference guide below defines the fields valid for each packet type. 105 106-------------------------------------------------------------------------------------------------- 107 108Generic Trace Packets - Packet Reference. 109----------------------------------------- 110 111This section contains reference descriptions of each of the generic trace packets types define as part of the 112`ocsd_gen_trc_elem_t` enum value that appears as the first `elem_type` field in the packet structure. 113 114The descriptions will include information on which fields in the packets are always valid, optional and any protocol specific information. 115 116The tags used in the reference are:- 117- __packet fields valid__ : fields that are always valid and filled for this packet type. 118- __packet fields optional__ : fields that _may_ be filled for this packet type. 119 The form `flag -> field` indicates a flag that may be set and the value that is valid if the flag is true 120- __protocol specific__ : indicates type or fields may be source protocol specific. 121 122_Note_: while most of the packets are not protocol specific, there are some protocol differences that mean 123certain types and fields will differ slightly across protocols. These differences are highlighted in the 124reference. 125 126### OCSD_GEN_TRC_ELEM_NO_SYNC ### 127__packet fields valid__: `unsync_eot_info` 128 129Element output before the decoder has synchronised with the input stream, or synchronisation is lost. 130The `unsync_eot_info` will give reason for lack of synchronisation. 131 132 133### OCSD_GEN_TRC_ELEM_INSTR_RANGE ### 134__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` 135 136__packet fields optional__: `has_cc -> cycle_count,` 137 138__protocol specific__ : ETMv3, PTM 139 140This should be the most common packet output for full trace decode. Represents a range of instructions of 141a single `isa`, executed by the PE. Instruction byte range is from `st_addr` (inclusive) to `en_addr` (exclusive). 142The total number of instructions executed for the range is given in `num_instr_range`. 143 144Information on the last instruction in the range is provided. `last_i_type` shows if the last instruction 145was a branch or otherwise - which combined with `last_instr_exec` determines if the branch was taken. 146The last instruction size in bytes is given, to allow clients to quickly determine the address of the last 147instruction by subtraction from `en_addr`. This value can be 2 or 4 bytes in the T32 instruction set. 148 149__ETMv3, PTM__ : These protocols can output a cycle count directly as part of the trace packet that generates 150the trace range. In this case `has_cc` will be 1 and `cycle_count` will be valid. 151 152 153### OCSD_GEN_TRC_ELEM_I_RANGE_NOPATH ### 154__packet fields valid__: `isa, st_addr, en_addr, num_instr_range` 155 156`num_instr_range` represents the number of instructions executed in this range, but there is incomplete information 157as to program execution path from start to end of range. 158If `num_instr` is 0, then an unknown number of instructions were executed between the start and end of the range. 159`st_addr` represents the start of execution represented by this packet. 160`en_addr` represents the address where execution will continue from after the instructions represented by this packet. 161`isa` represents the ISA for the instruction at `en_addr`. 162 163Used when ETMv4 Q elements are being traced. 164 165 166### OCSD_GEN_TRC_ELEM_ADDR_NACC ### 167__packet fields valid__: `st_addr` 168 169Trace decoder found address in trace that cannot be accessed in the mapped memory images. 170`st_addr` is the address that cannot be found. 171 172Decoder will wait for new address to appear in trace before attempting to restart decoding. 173 174 175### OCSD_GEN_TRC_ELEM_UNKNOWN ### 176__packet fields valid__: None 177 178Decoder saw invalid packet for protocol being processed. Likely incorrect protocol settings, or corrupted 179trace data. 180 181### OCSD_GEN_TRC_ELEM_TRACE_ON ### 182__packet fields valid__: `trace_on_reason` 183 184__packet fields optional__: `has_cc -> cycle_count,` 185 186__protocol specific__ : ETMv3, PTM 187 188Notification that trace has started / is synced after a discontinuity or at start of trace decode. 189 190__ETMv3, PTM__ : These protocols can output a cycle count directly as part of the trace packet that generates 191the trace on indicator. In this case `has_cc` will be 1 and `cycle_count` will be valid. 192 193 194### OCSD_GEN_TRC_ELEM_EO_TRACE ### 195__packet fields valid__: None 196 197Marker for end of trace data. Sent once for each CoreSight ID channel. 198 199### OCSD_GEN_TRC_ELEM_PE_CONTEXT ### 200__packet fields valid__: `context` 201 202__packet fields optional__: `has_cc -> cycle_count,` 203 204__protocol specific__ : ETMv3, PTM 205 206This packet indicates an update to the PE context - which may be the initial context in a trace stream, or a 207change since the trace started. 208 209The context is contained in a `ocsd_pe_context` structure. 210 211~~~{.c} 212typedef struct _ocsd_pe_context { 213 ocsd_sec_level security_level; /* security state */ 214 ocsd_ex_level exception_level; /* exception level */ 215 uint32_t context_id; /* context ID */ 216 uint32_t vmid; /* VMID */ 217 struct { 218 uint32_t bits64:1; /* 1 if 64 bit operation */ 219 uint32_t ctxt_id_valid:1; /* 1 if context ID value valid */ 220 uint32_t vmid_valid:1; /* 1 if VMID value is valid */ 221 uint32_t el_valid:1; /* 1 if EL value is valid (ETMv4 traces current EL, other protocols do not) */ 222 }; 223} ocsd_pe_context; 224~~~ 225 226__ETMv3, PTM__ : These protocols can output a cycle count directly as part of the trace packet that generates 227the PE context. In this case `has_cc` will be 1 and `cycle_count` will be valid. 228 229__ETMv3__ : From ETM 3.5 onwards, exception_level can be set to `ocsd_EL2` when tracing through hypervisor code. 230On all other occasions this will be set to `ocsd_EL_unknown`. 231 232 233### OCSD_GEN_TRC_ELEM_ADDR_UNKNOWN ### 234__packet fields optional__: `has_cc -> cycle_count,` 235 236__protocol specific__: ETMv3 237 238This packet will only be seen when decoding an ETMv3 protocol source. This indicates that the decoder 239is waiting for a valid address in order to process trace correctly. 240 241The packet can have a cycle count associated with it which the client must account for when tracking cycles used. 242The packet will be sent once when unknown address occurs. Further `OCSD_GEN_TRC_ELEM_CYCLE_COUNT` packets may follow 243 before the decode receives a valid address to continue decode. 244 245 246### OCSD_GEN_TRC_ELEM_EXCEPTION ### 247__packet fields valid__: `exception_number` 248 249__packet fields optional__: `has_cc -> cycle_count, excep_ret_addr -> en_addr, excep_data_marker, excep_ret_addr_br_tgt, excep_M_tail_chain` 250 251__protocol specific__: ETMv4, ETMv3, PTM 252 253All protocols will include the exception number in the packet. 254 255__ETMv4__ : This protocol may provide the preferred return address for the exception - this is the address of 256the instruction that could be executed on exception return. This address appears in `en_addr` if `excep_ret_addr` = 1. 257 258Additionally, this address could also represent the target address of a branch, if the exception occured at the branch target, before any further 259instructions were executed. If this is the case then the excep_ret_addr_br_tgt flag will be set. This makes explicit what was previously only implied by teh packet ordered. This information could be used for clients such as perf that branch source/target address pairs. 260 261Where `excep_M_tail_chain == 1`, the exception was the result of M profile exception tail chaining, or similar M profile 262events indicated by a standard address value, where the value is not the preferred return address. 263 264__ETMv3__ : This can set the `excep_data_marker` flag. This indicates that the exception packet is a marker 265to indicate exception entry in a 7M profile core, for the purposes of tracking data. This will __not__ provide 266an exception number in this case. 267 268__PTM__ : Can have an associated cycle count (`has_cc == 1`), and may provide preferred return address in `en_addr` 269if `excep_ret_addr` = 1. 270 271### OCSD_GEN_TRC_ELEM_EXCEPTION_RET ### 272__packet fields valid__: None 273 274Marker that a preceding branch was an exception return. 275 276### OCSD_GEN_TRC_ELEM_TIMESTAMP ### 277__packet fields valid__: `timestamp` 278 279__packet fields optional__: `has_cc -> cycle_count,` 280 281__protocol specific__: ETMv4, PTM 282 283The timestamp packet explicitly provides a timestamp value for the trace stream ID in the callback interface. 284 285__PTM__ : This can have an associated cycle count (`has_cc == 1`). For this protocol, the cycle count __is__ part 286of the cumulative cycle count for the trace session. 287 288__ETMv4__ : This can have an associated cycle count (`has_cc == 1`). For this protocl, the cycle coun represents 289the number of cycles between the previous cycle count packet and this timestamp packet, but __is not__ part of 290the cumulative cycle count for the trace session. 291 292 293### OCSD_GEN_TRC_ELEM_CYCLE_COUNT ### 294__packet fields valid__: `has_cc -> cycle_count` 295 296Packet contains a cycle count value. A cycle count value represents the number of cycles passed since the 297last cycle count value seen. The cycle count value may be associated with a specific packet or instruction 298range preceding the cycle count packet. 299 300Cycle count packets may be added together to build a cumulative count for the trace session. 301 302### OCSD_GEN_TRC_ELEM_EVENT ### 303__packet fields valid__: `trace_event` 304 305This is a hardware event injected into the trace by the ETM/PTM hardware resource programming. See the 306relevent trace hardware reference manuals for the programming of these events. 307 308The `trace_event` is a `trace_event_t` structure that can have an event type - and an event number. 309 310~~~{.c} 311typedef struct _trace_event_t { 312 uint16_t ev_type; /* event type - unknown (0) trigger (1), numbered event (2)*/ 313 uint16_t ev_number; /* event number if numbered event type */ 314} trace_event_t; 315~~~ 316 317The event types depend on the trace hardware:- 318 319__ETMv4__ : produces numbered events. The event number is a bitfield of up to four events that occurred. 320Events 0-3 -> bits 0-3. The bitfield allows a single packet to represent multiple different events occurring. 321 322_Note_: The ETMv4 specification has further information on timing of events and event packets. Event 0 323is also considered a trigger event in ETMv4 hardware, but is not explicitly represented as such in the OCSD protocol. 324 325__PTM__, __ETMv3__ : produce trigger events. Event number always set to 0. 326 327 328### OCSD_GEN_TRC_ELEM_SWTRACE ### 329__packet fields valid__: `sw_trace_info` 330 331__packet fields optional__: `has_ts -> timestamp`, ` extended_data -> ptr_extended_data` 332 333The Software trace packet always has a filled in `sw_trace_info` field to describe the current master and channel ID, 334plus the packet type and size of any payload data. 335 336SW trace packets that have a payload will use the extended_data flag and pointer to deliver this data. 337 338SW trace packets that include timestamp information will us the `has_ts` flag and fill in the timestamp value. 339 340These packets are generated by memory writes to STM / ITM trace hardware. 341 342### OCSD_GEN_TRC_ELEM_SYNC_MARKER ### 343__packet fields valid__: `sync_marker` 344 345Synchronisation marker - marks position in stream of an element that is output later. 346e.g. a timestamp marker can be output to represent the correct position in the stream for a 347timestamp packet the is output later. 348 349The `sync_marker` field has a structure as shown below. 350 351~~~{.c} 352typedef enum _trace_sync_marker_t { 353 ELEM_MARKER_TS, /**< Marker for timestamp element */ 354} trace_sync_marker_t; 355 356typedef struct _trace_marker_payload_t { 357 trace_sync_marker_t type; /**< type of sync marker */ 358 uint32_t value; /**< sync marker value - usage depends on type */ 359} trace_marker_payload_t; 360~~~ 361 362### OCSD_GEN_TRC_ELEM_MEMTRANS ### 363__packet fields valid__: `mem_trans` 364 365Memory transaction elements may appear in the output stream, if they are not otherwise cancelled 366by speculative trace packets. 367 368The memory transaction field has values as defined in the enum below:- 369 370~~~{.c} 371typedef enum _memtrans_t { 372 OCSD_MEM_TRANS_TRACE_INIT,/* Trace started while PE in transactional state */ 373 OCSD_MEM_TRANS_START, /* Trace after this packet is part of a transactional memory sequence */ 374 OCSD_MEM_TRANS_COMMIT, /* Transactional memory sequence valid. */ 375 OCSD_MEM_TRANS_FAIL, /* Transactional memory sequence failed - operations since start of transaction have been unwound. */ 376} trace_memtrans_t; 377~~~ 378 379### OCSD_GEN_TRC_ELEM_INSTRUMENTATION ### 380__packet fields valid__: `sw_ite` 381 382Software instrumentation packets generated by the PE `TRCIT` instruction (on cores with `FEAT_ITE`). 383 384The `sw_ite` structure has the fields defined below:- 385 386~~~{.c} 387typedef struct _sw_ite_t { 388 uint8_t el; /* exception level for PE sw instrumentation instruction */ 389 uint64_t value; /* payload for PE sw instrumentation instruction */ 390} trace_sw_ite_t; 391~~~ 392 393### OCSD_GEN_TRC_ELEM_CUSTOM ### 394__packet fields optional__: `extended_data -> ptr_extended_data`,_any others_ 395 396Custom protocol decoders can use this packet type to provide protocol specific information. 397 398Standard fields may be used for similar purposes as defined above, or the extended data pointer can reference 399other data. 400 401-------------------------------------------------------------------------------------------------- 402 403Generic Trace Packets - Notes on interpretation. 404------------------------------------------------ 405 406The interpretation of the trace output should always be done with reference to the underlying protocol 407specifications. 408 409While the output packets are in general protocol agnostic, there are some inevitable 410differences related to the underlying protocol that stem from the development of the trace hardware over time. 411 412### OCSD ranges and Trace Atom Packets ### 413The most common raw trace packet in all the protocols is the Atom packet, and this packet is the basis for most of 414the `OCSD_GEN_TRC_ELEM_INSTR_RANGE` packets output from the library. A trace range will be output for each atom 415in the raw trace stream - the `last_instr_exec` flag taking the value of the Atom - 1 for E, 0 for N. 416 417`OCSD_GEN_TRC_ELEM_INSTR_RANGE` packets can also be generated for non-atom packets, where flow changes - e.g. 418exceptions. 419 420 421### Multi feature OCSD output packets ### 422Where a raw trace packet contains additional information on top of the basic packet data, then this additional 423information will be added to the OCSD output packet and flagged accordingly (in the `flag_bits` union in the 424packet structure). 425 426Typically this will be atom+cycle count packets in ETMv3 and PTM protocols. For efficiency and to retain 427the coupling between the information an `OCSD_GEN_TRC_ELEM_INSTR_RANGE` packet will be output in this case 428with a `has_cc` flag set and the `cycle_count` value filled. 429 430ETMv3 and PTM can add a cycle count to a number of packets, or explicitly emit a cycle count only packet. By 431contrast ETMv4 only emits cycle count only packets. 432 433Clients processing the library output must be aware of these optional additions to the base packet. The 434OCSD packet descriptions above outline where the additional information can occur. 435 436### Cycle counts ### 437 438Cycle counts are cumulative, and represent cycles since the last cycle count output. 439Explicit cycle count packets are associated with the previous range event, otherwise where a 440packet includes a cycle count as additional information, then the count is associated with that 441specific packet - which will often be a range packet. 442 443The only exception to this is where the underlying protocol is ETMv4, and a cycle count is included 444in a timestamp packet. Here the cycle count represents that number of cycles since the last cycle count 445packet that occurred before the timestamp packet was emitted. This cycle count is not part of the cumulative 446count. See the ETMv4 specification for further details. 447 448 449### Correlation - timestamps and cycle counts ### 450 451Different trace streams can be correlated using either timestamps, or timestamps plus cycle counts. 452 453Both timestamps and cycle counts are enabled by programming ETM control registers, and it is also possible 454to control the frequency that timestamps appear, or the threshold at which cycle count packets are emitted by 455additional programming. 456 457The output of timestamps and cycle counts increases the amount of trace generated, very significantly when cycle 458counts are present, so the choice of generating these elements needs to be balanced against the requirement 459for their use. 460 461Decent correlation can be gained by the use of timestamps alone - especially if the source is programmed to 462produce them more frequently than the default timestamp events. More precise correllation can be performed if 463the 'gaps' between timestamps can be resolved using cycle counts. 464 465Correlation is performed by identifying the same/close timestamp values in two separate trace streams. Cycle counts 466if present can then be used to resolve the correlation with additional accuracy. 467 468 469 470 471 472 473 474 475 476 477 478