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_root, /**< PE FEAT_RME: Core is in root state. */ 344 ocsd_sec_realm, /**< PE FEAT_RME: Core is in realm state. */ 345 } ocsd_sec_level ; 346 347 /** Exception level type 348 */ 349 typedef enum _ocsd_ex_level 350 { 351 ocsd_EL_unknown = -1, /**< EL unknown / unsupported in trace */ 352 ocsd_EL0 = 0, /**< EL0 */ 353 ocsd_EL1, /**< EL1 */ 354 ocsd_EL2, /**< EL2 */ 355 ocsd_EL3, /**< EL3 */ 356 } ocsd_ex_level; 357 358 359 /** instruction types - significant for waypoint calculations */ 360 typedef enum _ocsd_instr_type { 361 OCSD_INSTR_OTHER, /**< Other instruction - not significant for waypoints. */ 362 OCSD_INSTR_BR, /**< Immediate Branch instruction */ 363 OCSD_INSTR_BR_INDIRECT, /**< Indirect Branch instruction */ 364 OCSD_INSTR_ISB, /**< Barrier : ISB instruction */ 365 OCSD_INSTR_DSB_DMB, /**< Barrier : DSB or DMB instruction */ 366 OCSD_INSTR_WFI_WFE, /**< WFI or WFE traced as direct branch */ 367 OCSD_INSTR_TSTART, /**< PE Arch feature FEAT_TME - TSTART instruction */ 368 } ocsd_instr_type; 369 370 /** instruction sub types - addiitonal information passed to the output packets 371 for trace analysis tools. 372 */ 373 typedef enum _ocsd_instr_subtype { 374 OCSD_S_INSTR_NONE, /**< no subtype set */ 375 OCSD_S_INSTR_BR_LINK, /**< branch with link */ 376 OCSD_S_INSTR_V8_RET, /**< v8 ret instruction - subtype of BR_INDIRECT */ 377 OCSD_S_INSTR_V8_ERET, /**< v8 eret instruction - subtype of BR_INDIRECT */ 378 OCSD_S_INSTR_V7_IMPLIED_RET, /**< v7 instruction which could imply return e.g. MOV PC, LR; POP { ,pc} */ 379 } ocsd_instr_subtype; 380 381 /** Instruction decode request structure. 382 * 383 * Used in IInstrDecode interface. 384 * 385 * Caller fills in the input: information, callee then fills in the decoder: information. 386 */ 387 typedef struct _ocsd_instr_info { 388 /* input information */ 389 ocsd_arch_profile_t pe_type; /**< input: Core Arch and profile */ 390 ocsd_isa isa; /**< Input: Current ISA. */ 391 ocsd_vaddr_t instr_addr; /**< Input: Instruction address. */ 392 uint32_t opcode; /**< Input: Opcode at address. 16 bit opcodes will use MS 16bits of parameter. */ 393 uint8_t dsb_dmb_waypoints; /**< Input: DMB and DSB are waypoints */ 394 uint8_t wfi_wfe_branch; /**< Input: WFI, WFE classed as direct branches */ 395 396 /* instruction decode info */ 397 ocsd_instr_type type; /**< Decoder: Current instruction type. */ 398 ocsd_vaddr_t branch_addr; /**< Decoder: Calculated address of branch instrcution (direct branches only) */ 399 ocsd_isa next_isa; /**< Decoder: ISA for next intruction. */ 400 uint8_t instr_size; /**< Decoder : size of the decoded instruction */ 401 uint8_t is_conditional; /**< Decoder : set to 1 if this instruction is conditional */ 402 uint8_t is_link; /**< Decoder : is a branch with link instruction */ 403 uint8_t thumb_it_conditions; /**< Decoder : return number of following instructions set with conditions by this Thumb IT instruction */ 404 ocsd_instr_subtype sub_type; /**< Decoder : current instruction sub-type if known */ 405 } ocsd_instr_info; 406 407 408 /** Core(PE) context structure 409 records current security state, exception level, VMID and ContextID for core. 410 */ 411 typedef struct _ocsd_pe_context { 412 ocsd_sec_level security_level; /**< security state */ 413 ocsd_ex_level exception_level; /**< exception level */ 414 uint32_t context_id; /**< context ID */ 415 uint32_t vmid; /**< VMID */ 416 struct { 417 uint32_t bits64:1; /**< 1 if 64 bit operation */ 418 uint32_t ctxt_id_valid:1; /**< 1 if context ID value valid */ 419 uint32_t vmid_valid:1; /**< 1 if VMID value is valid */ 420 uint32_t el_valid:1; /**< 1 if EL value is valid (ETMv4 traces EL, other protocols do not) */ 421 }; 422 } ocsd_pe_context; 423 424 425 /** @}*/ 426 427 /** @name Opcode Memory Access 428 Types used when accessing memory storage for traced opcodes.. 429 @{*/ 430 431 /** memory space bitfield enum for available security states and exception levels used 432 when accessing memory. */ 433 typedef enum _ocsd_mem_space_acc_t { 434 OCSD_MEM_SPACE_EL1S = 0x1, /**< S EL1/0 */ 435 OCSD_MEM_SPACE_EL1N = 0x2, /**< NS EL1/0 */ 436 OCSD_MEM_SPACE_EL2 = 0x4, /**< NS EL2 */ 437 OCSD_MEM_SPACE_EL3 = 0x8, /**< S EL3 */ 438 OCSD_MEM_SPACE_EL2S = 0x10, /**< S EL2 */ 439 OCSD_MEM_SPACE_S = 0x19, /**< Any S */ 440 OCSD_MEM_SPACE_N = 0x6, /**< Any NS */ 441 OCSD_MEM_SPACE_ANY = 0x1F, /**< Any sec level / EL - live system use current EL + sec state */ 442 } ocsd_mem_space_acc_t; 443 444 /** 445 * Callback function definition for callback function memory accessor type. 446 * 447 * When using callback memory accessor, the decoder will call this function to obtain the 448 * memory at the address for the current opcodes. The memory space will represent the current 449 * exception level and security context of the traced code. 450 * 451 * Return the number of bytes read, which can be less than the amount requested if this would take the 452 * access address outside the range of addresses defined when this callback was registered with the decoder. 453 * 454 * Return 0 bytes if start address out of covered range, or memory space is not one of those defined as supported 455 * when the callback was registered. 456 * 457 * @param p_context : opaque context pointer set by callback client. 458 * @param address : start address of memory to be accessed 459 * @param mem_space : memory space of accessed memory (current EL & security state) 460 * @param reqBytes : number of bytes required 461 * @param *byteBuffer : buffer for data. 462 * 463 * @return uint32_t : Number of bytes actually read, or 0 for access error. 464 */ 465 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); 466 467 /** 468 * Callback function definition for callback function memory accessor type. 469 * 470 * When using callback memory accessor, the decoder will call this function to obtain the 471 * memory at the address for the current opcodes. The memory space will represent the current 472 * exception level and security context of the traced code. 473 * 474 * Return the number of bytes read, which can be less than the amount requested if this would take the 475 * access address outside the range of addresses defined when this callback was registered with the decoder. 476 * 477 * Return 0 bytes if start address out of covered range, or memory space is not one of those defined as supported 478 * when the callback was registered. 479 * 480 * @param p_context : opaque context pointer set by callback client. 481 * @param address : start address of memory to be accessed 482 * @param mem_space : memory space of accessed memory (current EL & security state) 483 * @param trcID : Trace ID for source of trace - allow CB to client to associate mem req with source cpu. 484 * @param reqBytes : number of bytes required 485 * @param *byteBuffer : buffer for data. 486 * 487 * @return uint32_t : Number of bytes actually read, or 0 for access error. 488 */ 489 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); 490 491 492 /** memory region type for adding multi-region binary files to memory access interface */ 493 typedef struct _ocsd_file_mem_region { 494 size_t file_offset; /**< Offset from start of file for memory region */ 495 ocsd_vaddr_t start_address; /**< Start address of memory region */ 496 size_t region_size; /**< size in bytes of memory region */ 497 } ocsd_file_mem_region_t; 498 499 /** @}*/ 500 501 /** @name Packet Processor Operation Control Flags 502 common operational flags - bottom 16 bits, 503 protocol component specific - top 16 bits. 504 (common flags share bitfield with pkt decoder common flags and create flags) 505 @{*/ 506 507 #define OCSD_OPFLG_PKTPROC_NOFWD_BAD_PKTS 0x00000010 /**< don't forward bad packets up data path */ 508 #define OCSD_OPFLG_PKTPROC_NOMON_BAD_PKTS 0x00000020 /**< don't forward bad packets to monitor interface */ 509 #define OCSD_OPFLG_PKTPROC_ERR_BAD_PKTS 0x00000040 /**< throw error for bad packets - halt decoding. */ 510 #define OCSD_OPFLG_PKTPROC_UNSYNC_ON_BAD_PKTS 0x00000080 /**< switch to unsynced state on bad packets - wait for next sync point */ 511 512 /** mask to combine all common packet processor operational control flags */ 513 #define OCSD_OPFLG_PKTPROC_COMMON (OCSD_OPFLG_PKTPROC_NOFWD_BAD_PKTS | \ 514 OCSD_OPFLG_PKTPROC_NOMON_BAD_PKTS | \ 515 OCSD_OPFLG_PKTPROC_ERR_BAD_PKTS | \ 516 OCSD_OPFLG_PKTPROC_UNSYNC_ON_BAD_PKTS ) 517 518 /** mask for the component spcific flags */ 519 #define OCSD_OPFLG_COMP_MODE_MASK 0xFFFF0000 520 521 /** @}*/ 522 523 /** @name Packet Decoder Operation Control Flags 524 common operational flags - bottom 16 bits, 525 protcol component specific - top 16 bits. 526 (common flags share bitfield with pkt processor common flags and create flags) 527 @{*/ 528 529 #define OCSD_OPFLG_PKTDEC_ERROR_BAD_PKTS 0x00000100 /**< throw error on bad packets input (default is to warn) */ 530 #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 */ 531 532 /** mask to combine all common packet processor operational control flags */ 533 #define OCSD_OPFLG_PKTDEC_COMMON (OCSD_OPFLG_PKTDEC_ERROR_BAD_PKTS | OCSD_OPFLG_PKTDEC_HALT_BAD_PKTS) 534 535 /** @}*/ 536 537 /** @name Decoder creation information 538 539 Flags to use when creating decoders by name. 540 - share bitfield with pkt processor flags and packet decoder common flags. 541 542 Builtin decoder names. 543 544 Protocol type enum. 545 @{*/ 546 547 #define OCSD_CREATE_FLG_PACKET_PROC 0x01 /**< Create packet processor only. */ 548 #define OCSD_CREATE_FLG_FULL_DECODER 0x02 /**< Create packet processor + decoder pair */ 549 #define OCSD_CREATE_FLG_INST_ID 0x04 /**< Use instance ID in decoder instance name */ 550 551 #define OCSD_BUILTIN_DCD_STM "STM" /**< STM decoder */ 552 #define OCSD_BUILTIN_DCD_ETMV3 "ETMV3" /**< ETMv3 decoder */ 553 #define OCSD_BUILTIN_DCD_ETMV4I "ETMV4I" /**< ETMv4 instruction decoder */ 554 #define OCSD_BUILTIN_DCD_ETMV4D "ETMV4D" /**< ETMv4 data decoder */ 555 #define OCSD_BUILTIN_DCD_PTM "PTM" /**< PTM decoder */ 556 #define OCSD_BUILTIN_DCD_ETE "ETE" /**< ETE decoder */ 557 558 /*! Trace Protocol Builtin Types + extern 559 */ 560 typedef enum _ocsd_trace_protocol_t { 561 OCSD_PROTOCOL_UNKNOWN = 0, /**< Protocol unknown */ 562 563 /* Built in library decoders */ 564 OCSD_PROTOCOL_ETMV3, /**< ETMV3 instruction and data trace protocol decoder. */ 565 OCSD_PROTOCOL_ETMV4I, /**< ETMV4 instruction trace protocol decoder. */ 566 OCSD_PROTOCOL_ETMV4D, /**< ETMV4 data trace protocol decoder. */ 567 OCSD_PROTOCOL_PTM, /**< PTM program flow instruction trace protocol decoder. */ 568 OCSD_PROTOCOL_STM, /**< STM system trace protocol decoder. */ 569 OCSD_PROTOCOL_ETE, /**< ETE trace protocol decoder */ 570 571 /* others to be added here */ 572 OCSD_PROTOCOL_BUILTIN_END, /**< Invalid protocol - built-in protocol types end marker */ 573 574 /* Custom / external decoders */ 575 OCSD_PROTOCOL_CUSTOM_0 = 100, /**< Values from this onwards are assigned to external registered decoders */ 576 OCSD_PROTOCOL_CUSTOM_1, 577 OCSD_PROTOCOL_CUSTOM_2, 578 OCSD_PROTOCOL_CUSTOM_3, 579 OCSD_PROTOCOL_CUSTOM_4, 580 OCSD_PROTOCOL_CUSTOM_5, 581 OCSD_PROTOCOL_CUSTOM_6, 582 OCSD_PROTOCOL_CUSTOM_7, 583 OCSD_PROTOCOL_CUSTOM_8, 584 OCSD_PROTOCOL_CUSTOM_9, 585 586 OCSD_PROTOCOL_END /**< Invalid protocol - protocol types end marker */ 587 } ocsd_trace_protocol_t; 588 589 /** Test if protocol type is a library built-in decoder */ 590 #define OCSD_PROTOCOL_IS_BUILTIN(P) ((P > OCSD_PROTOCOL_UNKNOWN) && (P < OCSD_PROTOCOL_BUILTIN_END)) 591 592 /** Test if protocol type is a custom external registered decoder */ 593 #define OCSD_PROTOCOL_IS_CUSTOM(P) ((P >= OCSD_PROTOCOL_CUSTOM_0) && (P < OCSD_PROTOCOL_END )) 594 595 /** @}*/ 596 597 598 /** @name Software Trace Packets Info 599 600 Contains the information for the generic software trace output packet. 601 602 Software trace packet master and channel data. 603 Payload info: 604 size - packet payload size in bits; 605 marker - if this packet has a marker/flag 606 timestamp - if this packet has a timestamp associated 607 number of packets - packet processor can optionally correlate identically 608 sized packets on the same master / channel to be output as a single generic packet 609 610 Payload output as separate LE buffer, of sufficient bytes to hold all the packets. 611 @{*/ 612 613 typedef struct _ocsd_swt_info { 614 uint16_t swt_master_id; 615 uint16_t swt_channel_id; 616 union { 617 struct { 618 uint32_t swt_payload_pkt_bitsize:8; /**< [bits 0:7 ] Packet size in bits of the payload packets */ 619 uint32_t swt_payload_num_packets:8; /**< [bits 8:15 ] number of consecutive packets of this type in the payload data */ 620 uint32_t swt_marker_packet:1; /**< [bit 16 ] packet is marker / flag packet */ 621 uint32_t swt_has_timestamp:1; /**< [bit 17 ] packet has timestamp. */ 622 uint32_t swt_marker_first:1; /**< [bit 18 ] for multiple packet payloads, this indicates if any marker is on first or last packet */ 623 uint32_t swt_master_err:1; /**< [bit 19 ] current master has error - payload is error code */ 624 uint32_t swt_global_err:1; /**< [bit 20 ] global error - payload is error code - master and channel ID not valid */ 625 uint32_t swt_trigger_event:1; /**< [bit 21 ] trigger event packet - payload is event number */ 626 uint32_t swt_frequency:1; /**< [bit 22 ] frequency packet - payload is frequency */ 627 uint32_t swt_id_valid:1; /**< [bit 23 ] master & channel ID has been set by input stream */ 628 }; 629 uint32_t swt_flag_bits; 630 }; 631 } ocsd_swt_info_t; 632 633 /** mask for the swt_id_valid flag - need to retain between packets */ 634 #define SWT_ID_VALID_MASK (0x1 << 23) 635 636 /** @}*/ 637 638 /** @name Demux Statistics 639 640 Contains statistics for the CoreSight frame demultiplexor. 641 642 Counts total bytes sent to decoders registered against a trace ID, bytes in the input stream that are 643 associated with a trace ID that has no registered decoder, and frame bytes that are not trace data, but 644 are used to decode the frames - ID bytes, sync bytes etc. 645 @{*/ 646 647 typedef struct _ocsd_demux_stats { 648 uint64_t valid_id_bytes; /**< number of bytes associated with an ID that has a registered decoder */ 649 uint64_t no_id_bytes; /**< number of bytes associated with an ID that has no decoder */ 650 uint64_t reserved_id_bytes; /**< number of bytes associated with reserved IDs */ 651 uint64_t unknown_id_bytes; /**< bytes processed before ID seen in input frames */ 652 uint64_t frame_bytes; /**< number of non-data bytes used for frame de-mux - ID bytes, sync etc */ 653 } ocsd_demux_stats_t; 654 655 /** @}*/ 656 657 /** @name Decode statistics 658 659 Contains statistics for bytes decoded by the packet decoder, if statistics are supported. 660 661 Stats block instantiated in the base class - derived protocol specific decoder must initialise and 662 use as required. 663 664 The single channel block contains the stats for the requested channel via the API call. 665 666 The global demux block contains the totals for all channels and non-data bytes used in CoreSight 667 frame demux. This block will show identical data for every requested channel via the API. 668 669 @{*/ 670 671 typedef struct _ocsd_decode_stats { 672 uint32_t version; /**< library version number */ 673 uint16_t revision; /**< revision number - defines the structure version for the stats. */ 674 /* single channel block */ 675 uint64_t channel_total; /**< total bytes processed for this channel */ 676 uint64_t channel_unsynced; /**< number of unsynced bytes processed on this channel */ 677 uint32_t bad_header_errs; /**< number of bad packet header errors */ 678 uint32_t bad_sequence_errs; /**< number of bad packet sequence errors */ 679 680 ocsd_demux_stats_t demux; /**< global demux stats block */ 681 } ocsd_decode_stats_t; 682 683 #define OCSD_STATS_REVISION 0x1 684 685 /** @}*/ 686 687 688 /** @}*/ 689 #endif // ARM_OCSD_IF_TYPES_H_INCLUDED 690 691 /* End of File opencsd/ocsd_if_types.h */ 692