1 /*! 2 * \file opencsd/ocsd_if_types.h 3 * \brief OpenCSD : Standard Types used in the library interfaces. 4 * 5 * \copyright Copyright (c) 2015, ARM Limited. All Rights Reserved. 6 */ 7 8 /* 9 * Redistribution and use in source and binary forms, with or without modification, 10 * are permitted provided that the following conditions are met: 11 * 12 * 1. Redistributions of source code must retain the above copyright notice, 13 * this list of conditions and the following disclaimer. 14 * 15 * 2. Redistributions in binary form must reproduce the above copyright notice, 16 * this list of conditions and the following disclaimer in the documentation 17 * and/or other materials provided with the distribution. 18 * 19 * 3. Neither the name of the copyright holder nor the names of its contributors 20 * may be used to endorse or promote products derived from this software without 21 * specific prior written permission. 22 * 23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND 24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 25 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 26 * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 27 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 28 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 29 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 30 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33 */ 34 35 #ifndef ARM_OCSD_IF_TYPES_H_INCLUDED 36 #define ARM_OCSD_IF_TYPES_H_INCLUDED 37 38 #include <stdint.h> 39 #include <stddef.h> 40 #if defined(_MSC_VER) && (_MSC_VER < 1900) 41 /** VS2010 does not support inttypes - remove when VS2010 support is dropped */ 42 #define __PRI64_PREFIX "ll" 43 #define PRIX64 __PRI64_PREFIX "X" 44 #define PRIu64 __PRI64_PREFIX "u" 45 #define PRIu32 "u" 46 #else 47 #include <inttypes.h> 48 #endif 49 50 51 /** @defgroup ocsd_interfaces OpenCSD Library : Interfaces 52 @brief Set of types, structures and virtual interface classes making up the primary API 53 54 Set of component interfaces that connect various source reader and decode components into a 55 decode tree to allow trace decode for the trace data being output by the source reader. 56 57 @{*/ 58 59 60 61 /** @name Trace Indexing and Channel IDs 62 @{*/ 63 #ifdef ENABLE_LARGE_TRACE_SOURCES 64 typedef uint64_t ocsd_trc_index_t; /**< Trace source index type - 64 bit size */ 65 #define OCSD_TRC_IDX_STR PRIu64 66 #else 67 typedef uint32_t ocsd_trc_index_t; /**< Trace source index type - 32 bit size */ 68 #define OCSD_TRC_IDX_STR PRIu32 69 #endif 70 71 /** Invalid trace index value */ 72 #define OCSD_BAD_TRC_INDEX ((ocsd_trc_index_t)-1) 73 /** Invalid trace source ID value */ 74 #define OCSD_BAD_CS_SRC_ID ((uint8_t)-1) 75 /** macro returing true if trace source ID is in valid range (0x0 < ID < 0x70) */ 76 #define OCSD_IS_VALID_CS_SRC_ID(id) ((id > 0) && (id < 0x70)) 77 /** macro returing true if trace source ID is in reserved range (ID == 0x0 || 0x70 <= ID <= 0x7F) */ 78 #define OCSD_IS_RESERVED_CS_SRC_ID(id) ((id == 0) || ((id >= 0x70) && (id <= 0x7F)) 79 /** @}*/ 80 81 /** @name General Library Return and Error Codes 82 @{*/ 83 84 /** Library Error return type */ 85 typedef enum _ocsd_err_t { 86 87 /* general return errors */ 88 OCSD_OK = 0, /**< No Error. */ 89 OCSD_ERR_FAIL, /**< General systemic failure. */ 90 OCSD_ERR_MEM, /**< Internal memory allocation error. */ 91 OCSD_ERR_NOT_INIT, /**< Component not initialised or initialisation failure. */ 92 OCSD_ERR_INVALID_ID, /**< Invalid CoreSight Trace Source ID. */ 93 OCSD_ERR_BAD_HANDLE, /**< Invalid handle passed to component. */ 94 OCSD_ERR_INVALID_PARAM_VAL, /**< Invalid value parameter passed to component. */ 95 OCSD_ERR_INVALID_PARAM_TYPE, /**< Type mismatch on abstract interface */ 96 OCSD_ERR_FILE_ERROR, /**< File access error */ 97 OCSD_ERR_NO_PROTOCOL, /**< Trace protocol unsupported */ 98 /* attachment point errors */ 99 OCSD_ERR_ATTACH_TOO_MANY, /**< Cannot attach - attach device limit reached. */ 100 OCSD_ERR_ATTACH_INVALID_PARAM, /**< Cannot attach - invalid parameter. */ 101 OCSD_ERR_ATTACH_COMP_NOT_FOUND,/**< Cannot detach - component not found. */ 102 /* source reader errors */ 103 OCSD_ERR_RDR_FILE_NOT_FOUND, /**< source reader - file not found. */ 104 OCSD_ERR_RDR_INVALID_INIT, /**< source reader - invalid initialisation parameter. */ 105 OCSD_ERR_RDR_NO_DECODER, /**< source reader - not trace decoder set. */ 106 /* data path errors */ 107 OCSD_ERR_DATA_DECODE_FATAL, /**< A decoder in the data path has returned a fatal error. */ 108 /* frame deformatter errors */ 109 OCSD_ERR_DFMTR_NOTCONTTRACE, /**< Trace input to deformatter none-continuous */ 110 OCSD_ERR_DFMTR_BAD_FHSYNC, /**< Bad frame or half frame sync in trace deformatter */ 111 /* packet processor errors - protocol issues etc */ 112 OCSD_ERR_BAD_PACKET_SEQ, /**< Bad packet sequence */ 113 OCSD_ERR_INVALID_PCKT_HDR, /**< Invalid packet header */ 114 OCSD_ERR_PKT_INTERP_FAIL, /**< Interpreter failed - cannot recover - bad data or sequence */ 115 /* packet decoder errors */ 116 OCSD_ERR_UNSUPPORTED_ISA, /**< ISA not supported in decoder. */ 117 OCSD_ERR_HW_CFG_UNSUPP, /**< Programmed trace configuration not supported by decoder.*/ 118 OCSD_ERR_UNSUPP_DECODE_PKT, /**< Packet not supported in decoder */ 119 OCSD_ERR_BAD_DECODE_PKT, /**< reserved or unknown packet in decoder. */ 120 OCSD_ERR_COMMIT_PKT_OVERRUN, /**< overrun in commit packet stack - tried to commit more than available */ 121 OCSD_ERR_MEM_NACC, /**< unable to access required memory address */ 122 OCSD_ERR_RET_STACK_OVERFLOW, /**< internal return stack overflow checks failed - popped more than we pushed. */ 123 /* decode tree errors */ 124 OCSD_ERR_DCDT_NO_FORMATTER, /**< No formatter in use - operation not valid. */ 125 /* target memory access errors */ 126 OCSD_ERR_MEM_ACC_OVERLAP, /**< Attempted to set an overlapping range in memory access map */ 127 OCSD_ERR_MEM_ACC_FILE_NOT_FOUND, /**< Memory access file could not be opened */ 128 OCSD_ERR_MEM_ACC_FILE_DIFF_RANGE, /**< Attempt to re-use the same memory access file for a different address range */ 129 OCSD_ERR_MEM_ACC_RANGE_INVALID, /**< Address range in accessor set to invalid values */ 130 OCSD_ERR_MEM_ACC_BAD_LEN, /**< Memory accessor returned a bad read length value (larger than requested */ 131 /* test errors - errors generated only by the test code, not the library */ 132 OCSD_ERR_TEST_SNAPSHOT_PARSE, /**< test snapshot file parse error */ 133 OCSD_ERR_TEST_SNAPSHOT_PARSE_INFO, /**< test snapshot file parse information */ 134 OCSD_ERR_TEST_SNAPSHOT_READ, /**< test snapshot reader error */ 135 OCSD_ERR_TEST_SS_TO_DECODER, /**< test snapshot to decode tree conversion error */ 136 /* decoder registration */ 137 OCSD_ERR_DCDREG_NAME_REPEAT, /**< attempted to register a decoder with the same name as another one */ 138 OCSD_ERR_DCDREG_NAME_UNKNOWN, /**< attempted to find a decoder with a name that is not known in the library */ 139 OCSD_ERR_DCDREG_TYPE_UNKNOWN, /**< attempted to find a decoder with a type that is not known in the library */ 140 OCSD_ERR_DCDREG_TOOMANY, /**< attempted to register too many custom decoders */ 141 /* decoder config */ 142 OCSD_ERR_DCD_INTERFACE_UNUSED, /**< Attempt to connect or use and interface not supported by this decoder. */ 143 /* end marker*/ 144 OCSD_ERR_LAST 145 } ocsd_err_t; 146 147 /* component handle types */ 148 typedef unsigned int ocsd_hndl_rdr_t; /**< reader control handle */ 149 typedef unsigned int ocsd_hndl_err_log_t; /**< error logger connection handle */ 150 151 /* common invalid handle type */ 152 #define OCSD_INVALID_HANDLE (unsigned int)-1 /**< Global invalid handle value */ 153 154 /*! Error Severity Type 155 * 156 * Used to indicate the severity of an error, and also as the 157 * error log verbosity level in the error logger. 158 * 159 * The logger will ignore errors with a severity value higher than the 160 * current verbosity level. 161 * 162 * The value OCSD_ERR_SEV_NONE can only be used as a verbosity level to switch off logging, 163 * not as a severity value on an error. The other values can be used as both error severity and 164 * logger verbosity values. 165 */ 166 typedef enum _ocsd_err_severity_t { 167 OCSD_ERR_SEV_NONE, /**< No error logging. */ 168 OCSD_ERR_SEV_ERROR, /**< Most severe error - perhaps fatal. */ 169 OCSD_ERR_SEV_WARN, /**< Warning level. Inconsistent or incorrect data seen but can carry on decode processing */ 170 OCSD_ERR_SEV_INFO, /**< Information only message. Use for debugging code or suspect input data. */ 171 } ocsd_err_severity_t; 172 173 /** @}*/ 174 175 /** @name Trace Datapath 176 @{*/ 177 178 /** Trace Datapath operations. 179 */ 180 typedef enum _ocsd_datapath_op_t { 181 OCSD_OP_DATA = 0, /**< Standard index + data packet */ 182 OCSD_OP_EOT, /**< End of available trace data. No data packet. */ 183 OCSD_OP_FLUSH, /**< Flush existing data where possible, retain decode state. No data packet. */ 184 OCSD_OP_RESET, /**< Reset decode state - drop any existing partial data. No data packet. */ 185 } ocsd_datapath_op_t; 186 187 /** 188 * Trace Datapath responses 189 */ 190 typedef enum _ocsd_datapath_resp_t { 191 OCSD_RESP_CONT, /**< Continue processing */ 192 OCSD_RESP_WARN_CONT, /**< Continue processing : a component logged a warning. */ 193 OCSD_RESP_ERR_CONT, /**< Continue processing : a component logged an error.*/ 194 OCSD_RESP_WAIT, /**< Pause processing */ 195 OCSD_RESP_WARN_WAIT, /**< Pause processing : a component logged a warning. */ 196 OCSD_RESP_ERR_WAIT, /**< Pause processing : a component logged an error. */ 197 OCSD_RESP_FATAL_NOT_INIT, /**< Processing Fatal Error : component unintialised. */ 198 OCSD_RESP_FATAL_INVALID_OP, /**< Processing Fatal Error : invalid data path operation. */ 199 OCSD_RESP_FATAL_INVALID_PARAM, /**< Processing Fatal Error : invalid parameter in datapath call. */ 200 OCSD_RESP_FATAL_INVALID_DATA, /**< Processing Fatal Error : invalid trace data */ 201 OCSD_RESP_FATAL_SYS_ERR, /**< Processing Fatal Error : internal system error. */ 202 } ocsd_datapath_resp_t; 203 204 /*! Macro returning true if datapath response value is FATAL. */ 205 #define OCSD_DATA_RESP_IS_FATAL(x) (x >= OCSD_RESP_FATAL_NOT_INIT) 206 /*! Macro returning true if datapath response value indicates WARNING logged. */ 207 #define OCSD_DATA_RESP_IS_WARN(x) ((x == OCSD_RESP_WARN_CONT) || (x == OCSD_RESP_WARN_WAIT)) 208 /*! Macro returning true if datapath response value indicates ERROR logged. */ 209 #define OCSD_DATA_RESP_IS_ERR(x) ((x == OCSD_RESP_ERR_CONT) || (x == OCSD_RESP_ERR_WAIT)) 210 /*! Macro returning true if datapath response value indicates WARNING or ERROR logged. */ 211 #define OCSD_DATA_RESP_IS_WARN_OR_ERR(x) (OCSD_DATA_RESP_IS_ERR(x) || OCSD_DATA_RESP_IS_WARN(x)) 212 /*! Macro returning true if datapath response value is CONT. */ 213 #define OCSD_DATA_RESP_IS_CONT(x) (x < OCSD_RESP_WAIT) 214 /*! Macro returning true if datapath response value is WAIT. */ 215 #define OCSD_DATA_RESP_IS_WAIT(x) ((x >= OCSD_RESP_WAIT) && (x < OCSD_RESP_FATAL_NOT_INIT)) 216 217 /** @}*/ 218 219 /** @name Trace Decode component types 220 @{*/ 221 222 223 /** Raw frame element data types 224 Data blocks types output from ITrcRawFrameIn. 225 */ 226 typedef enum _rcdtl_rawframe_elem_t { 227 OCSD_FRM_NONE, /**< None data operation on data path. (EOT etc.) */ 228 OCSD_FRM_PACKED, /**< Raw packed frame data */ 229 OCSD_FRM_HSYNC, /**< HSYNC data */ 230 OCSD_FRM_FSYNC, /**< Frame Sync Data */ 231 OCSD_FRM_ID_DATA, /**< unpacked data for ID */ 232 } ocsd_rawframe_elem_t; 233 234 235 /** Indicates if the trace source will be frame formatted or a single protocol source. 236 Used in decode tree creation and configuration code. 237 */ 238 typedef enum _ocsd_dcd_tree_src_t { 239 OCSD_TRC_SRC_FRAME_FORMATTED, /**< input source is frame formatted. */ 240 OCSD_TRC_SRC_SINGLE, /**< input source is from a single protocol generator. */ 241 } ocsd_dcd_tree_src_t; 242 243 #define OCSD_DFRMTR_HAS_FSYNCS 0x01 /**< Deformatter Config : formatted data has fsyncs - input data 4 byte aligned */ 244 #define OCSD_DFRMTR_HAS_HSYNCS 0x02 /**< Deformatter Config : formatted data has hsyncs - input data 2 byte aligned */ 245 #define OCSD_DFRMTR_FRAME_MEM_ALIGN 0x04 /**< Deformatter Config : formatted frames are memory aligned, no syncs. Input data 16 byte frame aligned. */ 246 #define OCSD_DFRMTR_PACKED_RAW_OUT 0x08 /**< Deformatter Config : output raw packed frame data if raw monitor attached. */ 247 #define OCSD_DFRMTR_UNPACKED_RAW_OUT 0x10 /**< Deformatter Config : output raw unpacked frame data if raw monitor attached. */ 248 #define OCSD_DFRMTR_RESET_ON_4X_FSYNC 0x20 /**< Deformatter Config : reset downstream decoders if frame aligned 4x consecutive fsyncs spotted. (perf workaround) */ 249 #define OCSD_DFRMTR_VALID_MASK 0x3F /**< Deformatter Config : valid mask for deformatter configuration */ 250 251 #define OCSD_DFRMTR_FRAME_SIZE 0x10 /**< CoreSight frame formatter frame size constant in bytes. */ 252 253 /** @}*/ 254 255 /** @name Trace Decode Component Name Prefixes 256 * 257 * Set of standard prefixes to be used for component names 258 @{*/ 259 260 /** Component name prefix for trace source reader components */ 261 #define OCSD_CMPNAME_PREFIX_SOURCE_READER "SRDR" 262 /** Component name prefix for trace frame deformatter component */ 263 #define OCSD_CMPNAME_PREFIX_FRAMEDEFORMATTER "DFMT" 264 /** Component name prefix for trace packet processor. */ 265 #define OCSD_CMPNAME_PREFIX_PKTPROC "PKTP" 266 /** Component name prefix for trace packet decoder. */ 267 #define OCSD_CMPNAME_PREFIX_PKTDEC "PDEC" 268 269 /** @}*/ 270 271 /** @name Trace Decode Arch and Profile 272 @{*/ 273 274 /** Core Architecture Version */ 275 typedef enum _ocsd_arch_version { 276 ARCH_UNKNOWN = 0x0000, /**< unknown architecture */ 277 ARCH_CUSTOM = 0x0001, /**< None ARM, custom architecture */ 278 ARCH_V7 = 0x0700, /**< V7 architecture */ 279 ARCH_V8 = 0x0800, /**< V8 architecture */ 280 ARCH_V8r3 = 0x0803, /**< V8.3 architecture */ 281 ARCH_AA64 = 0x0864, /**< Min v8r3 plus additional AA64 PE features */ 282 ARCH_V8_max = ARCH_AA64, 283 } ocsd_arch_version_t; 284 285 // macros for arch version comparisons. 286 #define OCSD_IS_V8_ARCH(arch) ((arch >= ARCH_V8) && (arch <= ARCH_V8_max)) 287 #define OCSD_IS_ARCH_MINVER(arch, min_arch) (arch >= min_arch) 288 289 /** Core Profile */ 290 typedef enum _ocsd_core_profile { 291 profile_Unknown, /**< Unknown profile */ 292 profile_CortexM, /**< Cortex-M profile */ 293 profile_CortexR, /**< Cortex-R profile */ 294 profile_CortexA, /**< Cortex-A profile */ 295 profile_Custom, /**< None ARM, custom arch profile */ 296 } ocsd_core_profile_t; 297 298 /** Combined architecture and profile descriptor for a core */ 299 typedef struct _ocsd_arch_profile_t { 300 ocsd_arch_version_t arch; /**< core architecture */ 301 ocsd_core_profile_t profile; /**< core profile */ 302 } ocsd_arch_profile_t; 303 304 /* may want to use a 32 bit v-addr when running on 32 bit only ARM platforms. */ 305 #ifdef USE_32BIT_V_ADDR 306 typedef uint32_t ocsd_vaddr_t; /**< 32 bit virtual addressing in library - use if compiling on 32 bit platforms */ 307 #define OCSD_MAX_VA_BITSIZE 32 /**< 32 bit Virtual address bitsize macro */ 308 #define OCSD_VA_MASK ~0UL /**< 32 bit Virtual address bitsize mask */ 309 #else 310 typedef uint64_t ocsd_vaddr_t; /**< 64 bit virtual addressing in library */ 311 #define OCSD_MAX_VA_BITSIZE 64 /**< 64 bit Virtual address bitsize macro */ 312 #define OCSD_VA_MASK ~0ULL /**< 64 bit Virtual address bitsize mask */ 313 #endif 314 315 /** A bit mask for the first 'bits' consecutive bits of an address */ 316 #define OCSD_BIT_MASK(bits) (bits == OCSD_MAX_VA_BITSIZE) ? OCSD_VA_MASK : ((ocsd_vaddr_t)1 << bits) - 1 317 318 /** @}*/ 319 320 /** @name Instruction Decode Information 321 @{*/ 322 323 /** Instruction Set Architecture type 324 * 325 */ 326 typedef enum _ocsd_isa 327 { 328 ocsd_isa_arm, /**< V7 ARM 32, V8 AArch32 */ 329 ocsd_isa_thumb2, /**< Thumb2 -> 16/32 bit instructions */ 330 ocsd_isa_aarch64, /**< V8 AArch64 */ 331 ocsd_isa_tee, /**< Thumb EE - unsupported */ 332 ocsd_isa_jazelle, /**< Jazelle - unsupported in trace */ 333 ocsd_isa_custom, /**< Instruction set - custom arch decoder */ 334 ocsd_isa_unknown /**< ISA not yet known */ 335 } ocsd_isa; 336 337 /** Security level type 338 */ 339 typedef enum _ocsd_sec_level 340 { 341 ocsd_sec_secure, /**< Core is in secure state */ 342 ocsd_sec_nonsecure /**< Core is in non-secure state */ 343 } ocsd_sec_level ; 344 345 /** Exception level type 346 */ 347 typedef enum _ocsd_ex_level 348 { 349 ocsd_EL_unknown = -1, /**< EL unknown / unsupported in trace */ 350 ocsd_EL0 = 0, /**< EL0 */ 351 ocsd_EL1, /**< EL1 */ 352 ocsd_EL2, /**< EL2 */ 353 ocsd_EL3, /**< EL3 */ 354 } ocsd_ex_level; 355 356 357 /** instruction types - significant for waypoint calculations */ 358 typedef enum _ocsd_instr_type { 359 OCSD_INSTR_OTHER, /**< Other instruction - not significant for waypoints. */ 360 OCSD_INSTR_BR, /**< Immediate Branch instruction */ 361 OCSD_INSTR_BR_INDIRECT, /**< Indirect Branch instruction */ 362 OCSD_INSTR_ISB, /**< Barrier : ISB instruction */ 363 OCSD_INSTR_DSB_DMB, /**< Barrier : DSB or DMB instruction */ 364 OCSD_INSTR_WFI_WFE, /**< WFI or WFE traced as direct branch */ 365 OCSD_INSTR_TSTART, /**< PE Arch feature FEAT_TME - TSTART instruction */ 366 } ocsd_instr_type; 367 368 /** instruction sub types - addiitonal information passed to the output packets 369 for trace analysis tools. 370 */ 371 typedef enum _ocsd_instr_subtype { 372 OCSD_S_INSTR_NONE, /**< no subtype set */ 373 OCSD_S_INSTR_BR_LINK, /**< branch with link */ 374 OCSD_S_INSTR_V8_RET, /**< v8 ret instruction - subtype of BR_INDIRECT */ 375 OCSD_S_INSTR_V8_ERET, /**< v8 eret instruction - subtype of BR_INDIRECT */ 376 OCSD_S_INSTR_V7_IMPLIED_RET, /**< v7 instruction which could imply return e.g. MOV PC, LR; POP { ,pc} */ 377 } ocsd_instr_subtype; 378 379 /** Instruction decode request structure. 380 * 381 * Used in IInstrDecode interface. 382 * 383 * Caller fills in the input: information, callee then fills in the decoder: information. 384 */ 385 typedef struct _ocsd_instr_info { 386 /* input information */ 387 ocsd_arch_profile_t pe_type; /**< input: Core Arch and profile */ 388 ocsd_isa isa; /**< Input: Current ISA. */ 389 ocsd_vaddr_t instr_addr; /**< Input: Instruction address. */ 390 uint32_t opcode; /**< Input: Opcode at address. 16 bit opcodes will use MS 16bits of parameter. */ 391 uint8_t dsb_dmb_waypoints; /**< Input: DMB and DSB are waypoints */ 392 uint8_t wfi_wfe_branch; /**< Input: WFI, WFE classed as direct branches */ 393 394 /* instruction decode info */ 395 ocsd_instr_type type; /**< Decoder: Current instruction type. */ 396 ocsd_vaddr_t branch_addr; /**< Decoder: Calculated address of branch instrcution (direct branches only) */ 397 ocsd_isa next_isa; /**< Decoder: ISA for next intruction. */ 398 uint8_t instr_size; /**< Decoder : size of the decoded instruction */ 399 uint8_t is_conditional; /**< Decoder : set to 1 if this instruction is conditional */ 400 uint8_t is_link; /**< Decoder : is a branch with link instruction */ 401 uint8_t thumb_it_conditions; /**< Decoder : return number of following instructions set with conditions by this Thumb IT instruction */ 402 ocsd_instr_subtype sub_type; /**< Decoder : current instruction sub-type if known */ 403 } ocsd_instr_info; 404 405 406 /** Core(PE) context structure 407 records current security state, exception level, VMID and ContextID for core. 408 */ 409 typedef struct _ocsd_pe_context { 410 ocsd_sec_level security_level; /**< security state */ 411 ocsd_ex_level exception_level; /**< exception level */ 412 uint32_t context_id; /**< context ID */ 413 uint32_t vmid; /**< VMID */ 414 struct { 415 uint32_t bits64:1; /**< 1 if 64 bit operation */ 416 uint32_t ctxt_id_valid:1; /**< 1 if context ID value valid */ 417 uint32_t vmid_valid:1; /**< 1 if VMID value is valid */ 418 uint32_t el_valid:1; /**< 1 if EL value is valid (ETMv4 traces EL, other protocols do not) */ 419 }; 420 } ocsd_pe_context; 421 422 423 /** @}*/ 424 425 /** @name Opcode Memory Access 426 Types used when accessing memory storage for traced opcodes.. 427 @{*/ 428 429 /** memory space bitfield enum for available security states and exception levels used 430 when accessing memory. */ 431 typedef enum _ocsd_mem_space_acc_t { 432 OCSD_MEM_SPACE_EL1S = 0x1, /**< S EL1/0 */ 433 OCSD_MEM_SPACE_EL1N = 0x2, /**< NS EL1/0 */ 434 OCSD_MEM_SPACE_EL2 = 0x4, /**< NS EL2 */ 435 OCSD_MEM_SPACE_EL3 = 0x8, /**< S EL3 */ 436 OCSD_MEM_SPACE_EL2S = 0x10, /**< S EL2 */ 437 OCSD_MEM_SPACE_S = 0x19, /**< Any S */ 438 OCSD_MEM_SPACE_N = 0x6, /**< Any NS */ 439 OCSD_MEM_SPACE_ANY = 0x1F, /**< Any sec level / EL - live system use current EL + sec state */ 440 } ocsd_mem_space_acc_t; 441 442 /** 443 * Callback function definition for callback function memory accessor type. 444 * 445 * When using callback memory accessor, the decoder will call this function to obtain the 446 * memory at the address for the current opcodes. The memory space will represent the current 447 * exception level and security context of the traced code. 448 * 449 * Return the number of bytes read, which can be less than the amount requested if this would take the 450 * access address outside the range of addresses defined when this callback was registered with the decoder. 451 * 452 * Return 0 bytes if start address out of covered range, or memory space is not one of those defined as supported 453 * when the callback was registered. 454 * 455 * @param p_context : opaque context pointer set by callback client. 456 * @param address : start address of memory to be accessed 457 * @param mem_space : memory space of accessed memory (current EL & security state) 458 * @param reqBytes : number of bytes required 459 * @param *byteBuffer : buffer for data. 460 * 461 * @return uint32_t : Number of bytes actually read, or 0 for access error. 462 */ 463 typedef uint32_t (* Fn_MemAcc_CB)(const void *p_context, const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const uint32_t reqBytes, uint8_t *byteBuffer); 464 465 /** 466 * Callback function definition for callback function memory accessor type. 467 * 468 * When using callback memory accessor, the decoder will call this function to obtain the 469 * memory at the address for the current opcodes. The memory space will represent the current 470 * exception level and security context of the traced code. 471 * 472 * Return the number of bytes read, which can be less than the amount requested if this would take the 473 * access address outside the range of addresses defined when this callback was registered with the decoder. 474 * 475 * Return 0 bytes if start address out of covered range, or memory space is not one of those defined as supported 476 * when the callback was registered. 477 * 478 * @param p_context : opaque context pointer set by callback client. 479 * @param address : start address of memory to be accessed 480 * @param mem_space : memory space of accessed memory (current EL & security state) 481 * @param trcID : Trace ID for source of trace - allow CB to client to associate mem req with source cpu. 482 * @param reqBytes : number of bytes required 483 * @param *byteBuffer : buffer for data. 484 * 485 * @return uint32_t : Number of bytes actually read, or 0 for access error. 486 */ 487 typedef uint32_t (* Fn_MemAccID_CB)(const void *p_context, const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const uint8_t trcID, const uint32_t reqBytes, uint8_t *byteBuffer); 488 489 490 /** memory region type for adding multi-region binary files to memory access interface */ 491 typedef struct _ocsd_file_mem_region { 492 size_t file_offset; /**< Offset from start of file for memory region */ 493 ocsd_vaddr_t start_address; /**< Start address of memory region */ 494 size_t region_size; /**< size in bytes of memory region */ 495 } ocsd_file_mem_region_t; 496 497 /** @}*/ 498 499 /** @name Packet Processor Operation Control Flags 500 common operational flags - bottom 16 bits, 501 protocol component specific - top 16 bits. 502 (common flags share bitfield with pkt decoder common flags and create flags) 503 @{*/ 504 505 #define OCSD_OPFLG_PKTPROC_NOFWD_BAD_PKTS 0x00000010 /**< don't forward bad packets up data path */ 506 #define OCSD_OPFLG_PKTPROC_NOMON_BAD_PKTS 0x00000020 /**< don't forward bad packets to monitor interface */ 507 #define OCSD_OPFLG_PKTPROC_ERR_BAD_PKTS 0x00000040 /**< throw error for bad packets - halt decoding. */ 508 #define OCSD_OPFLG_PKTPROC_UNSYNC_ON_BAD_PKTS 0x00000080 /**< switch to unsynced state on bad packets - wait for next sync point */ 509 510 /** mask to combine all common packet processor operational control flags */ 511 #define OCSD_OPFLG_PKTPROC_COMMON (OCSD_OPFLG_PKTPROC_NOFWD_BAD_PKTS | \ 512 OCSD_OPFLG_PKTPROC_NOMON_BAD_PKTS | \ 513 OCSD_OPFLG_PKTPROC_ERR_BAD_PKTS | \ 514 OCSD_OPFLG_PKTPROC_UNSYNC_ON_BAD_PKTS ) 515 516 /** mask for the component spcific flags */ 517 #define OCSD_OPFLG_COMP_MODE_MASK 0xFFFF0000 518 519 /** @}*/ 520 521 /** @name Packet Decoder Operation Control Flags 522 common operational flags - bottom 16 bits, 523 protcol component specific - top 16 bits. 524 (common flags share bitfield with pkt processor common flags and create flags) 525 @{*/ 526 527 #define OCSD_OPFLG_PKTDEC_ERROR_BAD_PKTS 0x00000100 /**< throw error on bad packets input (default is to warn) */ 528 #define OCSD_OPFLG_PKTDEC_HALT_BAD_PKTS 0x00000200 /**< halt decoder on bad packets (default is to log error and continue by resetting decoder and wait for sync */ 529 530 /** mask to combine all common packet processor operational control flags */ 531 #define OCSD_OPFLG_PKTDEC_COMMON (OCSD_OPFLG_PKTDEC_ERROR_BAD_PKTS | OCSD_OPFLG_PKTDEC_HALT_BAD_PKTS) 532 533 /** @}*/ 534 535 /** @name Decoder creation information 536 537 Flags to use when creating decoders by name. 538 - share bitfield with pkt processor flags and packet decoder common flags. 539 540 Builtin decoder names. 541 542 Protocol type enum. 543 @{*/ 544 545 #define OCSD_CREATE_FLG_PACKET_PROC 0x01 /**< Create packet processor only. */ 546 #define OCSD_CREATE_FLG_FULL_DECODER 0x02 /**< Create packet processor + decoder pair */ 547 #define OCSD_CREATE_FLG_INST_ID 0x04 /**< Use instance ID in decoder instance name */ 548 549 #define OCSD_BUILTIN_DCD_STM "STM" /**< STM decoder */ 550 #define OCSD_BUILTIN_DCD_ETMV3 "ETMV3" /**< ETMv3 decoder */ 551 #define OCSD_BUILTIN_DCD_ETMV4I "ETMV4I" /**< ETMv4 instruction decoder */ 552 #define OCSD_BUILTIN_DCD_ETMV4D "ETMV4D" /**< ETMv4 data decoder */ 553 #define OCSD_BUILTIN_DCD_PTM "PTM" /**< PTM decoder */ 554 #define OCSD_BUILTIN_DCD_ETE "ETE" /**< ETE decoder */ 555 556 /*! Trace Protocol Builtin Types + extern 557 */ 558 typedef enum _ocsd_trace_protocol_t { 559 OCSD_PROTOCOL_UNKNOWN = 0, /**< Protocol unknown */ 560 561 /* Built in library decoders */ 562 OCSD_PROTOCOL_ETMV3, /**< ETMV3 instruction and data trace protocol decoder. */ 563 OCSD_PROTOCOL_ETMV4I, /**< ETMV4 instruction trace protocol decoder. */ 564 OCSD_PROTOCOL_ETMV4D, /**< ETMV4 data trace protocol decoder. */ 565 OCSD_PROTOCOL_PTM, /**< PTM program flow instruction trace protocol decoder. */ 566 OCSD_PROTOCOL_STM, /**< STM system trace protocol decoder. */ 567 OCSD_PROTOCOL_ETE, /**< ETE trace protocol decoder */ 568 569 /* others to be added here */ 570 OCSD_PROTOCOL_BUILTIN_END, /**< Invalid protocol - built-in protocol types end marker */ 571 572 /* Custom / external decoders */ 573 OCSD_PROTOCOL_CUSTOM_0 = 100, /**< Values from this onwards are assigned to external registered decoders */ 574 OCSD_PROTOCOL_CUSTOM_1, 575 OCSD_PROTOCOL_CUSTOM_2, 576 OCSD_PROTOCOL_CUSTOM_3, 577 OCSD_PROTOCOL_CUSTOM_4, 578 OCSD_PROTOCOL_CUSTOM_5, 579 OCSD_PROTOCOL_CUSTOM_6, 580 OCSD_PROTOCOL_CUSTOM_7, 581 OCSD_PROTOCOL_CUSTOM_8, 582 OCSD_PROTOCOL_CUSTOM_9, 583 584 OCSD_PROTOCOL_END /**< Invalid protocol - protocol types end marker */ 585 } ocsd_trace_protocol_t; 586 587 /** Test if protocol type is a library built-in decoder */ 588 #define OCSD_PROTOCOL_IS_BUILTIN(P) ((P > OCSD_PROTOCOL_UNKNOWN) && (P < OCSD_PROTOCOL_BUILTIN_END)) 589 590 /** Test if protocol type is a custom external registered decoder */ 591 #define OCSD_PROTOCOL_IS_CUSTOM(P) ((P >= OCSD_PROTOCOL_CUSTOM_0) && (P < OCSD_PROTOCOL_END )) 592 593 /** @}*/ 594 595 596 /** @name Software Trace Packets Info 597 598 Contains the information for the generic software trace output packet. 599 600 Software trace packet master and channel data. 601 Payload info: 602 size - packet payload size in bits; 603 marker - if this packet has a marker/flag 604 timestamp - if this packet has a timestamp associated 605 number of packets - packet processor can optionally correlate identically 606 sized packets on the same master / channel to be output as a single generic packet 607 608 Payload output as separate LE buffer, of sufficient bytes to hold all the packets. 609 @{*/ 610 611 typedef struct _ocsd_swt_info { 612 uint16_t swt_master_id; 613 uint16_t swt_channel_id; 614 union { 615 struct { 616 uint32_t swt_payload_pkt_bitsize:8; /**< [bits 0:7 ] Packet size in bits of the payload packets */ 617 uint32_t swt_payload_num_packets:8; /**< [bits 8:15 ] number of consecutive packets of this type in the payload data */ 618 uint32_t swt_marker_packet:1; /**< [bit 16 ] packet is marker / flag packet */ 619 uint32_t swt_has_timestamp:1; /**< [bit 17 ] packet has timestamp. */ 620 uint32_t swt_marker_first:1; /**< [bit 18 ] for multiple packet payloads, this indicates if any marker is on first or last packet */ 621 uint32_t swt_master_err:1; /**< [bit 19 ] current master has error - payload is error code */ 622 uint32_t swt_global_err:1; /**< [bit 20 ] global error - payload is error code - master and channel ID not valid */ 623 uint32_t swt_trigger_event:1; /**< [bit 21 ] trigger event packet - payload is event number */ 624 uint32_t swt_frequency:1; /**< [bit 22 ] frequency packet - payload is frequency */ 625 uint32_t swt_id_valid:1; /**< [bit 23 ] master & channel ID has been set by input stream */ 626 }; 627 uint32_t swt_flag_bits; 628 }; 629 } ocsd_swt_info_t; 630 631 /** mask for the swt_id_valid flag - need to retain between packets */ 632 #define SWT_ID_VALID_MASK (0x1 << 23) 633 634 /** @}*/ 635 636 /** @name Demux Statistics 637 638 Contains statistics for the CoreSight frame demultiplexor. 639 640 Counts total bytes sent to decoders registered against a trace ID, bytes in the input stream that are 641 associated with a trace ID that has no registered decoder, and frame bytes that are not trace data, but 642 are used to decode the frames - ID bytes, sync bytes etc. 643 @{*/ 644 645 typedef struct _ocsd_demux_stats { 646 uint64_t valid_id_bytes; /**< number of bytes associated with an ID that has a registered decoder */ 647 uint64_t no_id_bytes; /**< number of bytes associated with an ID that has no decoder */ 648 uint64_t reserved_id_bytes; /**< number of bytes associated with reserved IDs */ 649 uint64_t unknown_id_bytes; /**< bytes processed before ID seen in input frames */ 650 uint64_t frame_bytes; /**< number of non-data bytes used for frame de-mux - ID bytes, sync etc */ 651 } ocsd_demux_stats_t; 652 653 /** @}*/ 654 655 /** @name Decode statistics 656 657 Contains statistics for bytes decoded by the packet decoder, if statistics are supported. 658 659 Stats block instantiated in the base class - derived protocol specific decoder must initialise and 660 use as required. 661 662 The single channel block contains the stats for the requested channel via the API call. 663 664 The global demux block contains the totals for all channels and non-data bytes used in CoreSight 665 frame demux. This block will show identical data for every requested channel via the API. 666 667 @{*/ 668 669 typedef struct _ocsd_decode_stats { 670 uint32_t version; /**< library version number */ 671 uint16_t revision; /**< revision number - defines the structure version for the stats. */ 672 /* single channel block */ 673 uint64_t channel_total; /**< total bytes processed for this channel */ 674 uint64_t channel_unsynced; /**< number of unsynced bytes processed on this channel */ 675 uint32_t bad_header_errs; /**< number of bad packet header errors */ 676 uint32_t bad_sequence_errs; /**< number of bad packet sequence errors */ 677 678 ocsd_demux_stats_t demux; /**< global demux stats block */ 679 } ocsd_decode_stats_t; 680 681 #define OCSD_STATS_REVISION 0x1 682 683 /** @}*/ 684 685 686 /** @}*/ 687 #endif // ARM_OCSD_IF_TYPES_H_INCLUDED 688 689 /* End of File opencsd/ocsd_if_types.h */ 690