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