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 unsync and wait) */
528 
529 /** mask to combine all common packet processor operational control flags */
530 #define OCSD_OPFLG_PKTDEC_COMMON (OCSD_OPFLG_PKTDEC_ERROR_BAD_PKTS)
531 
532 /** @}*/
533 
534 /** @name Decoder creation information
535 
536     Flags to use when creating decoders by name.
537     - share bitfield with pkt processor flags and packet decoder common flags.
538 
539     Builtin decoder names.
540 
541     Protocol type enum.
542 @{*/
543 
544 #define OCSD_CREATE_FLG_PACKET_PROC     0x01    /**< Create packet processor only.              */
545 #define OCSD_CREATE_FLG_FULL_DECODER    0x02    /**< Create packet processor + decoder pair     */
546 #define OCSD_CREATE_FLG_INST_ID         0x04    /**< Use instance ID in decoder instance name   */
547 
548 #define OCSD_BUILTIN_DCD_STM        "STM"       /**< STM decoder */
549 #define OCSD_BUILTIN_DCD_ETMV3      "ETMV3"     /**< ETMv3 decoder */
550 #define OCSD_BUILTIN_DCD_ETMV4I     "ETMV4I"    /**< ETMv4 instruction decoder */
551 #define OCSD_BUILTIN_DCD_ETMV4D     "ETMV4D"    /**< ETMv4 data decoder */
552 #define OCSD_BUILTIN_DCD_PTM        "PTM"       /**< PTM decoder */
553 #define OCSD_BUILTIN_DCD_ETE        "ETE"       /**< ETE decoder */
554 
555 /*! Trace Protocol Builtin Types + extern
556  */
557 typedef enum _ocsd_trace_protocol_t {
558     OCSD_PROTOCOL_UNKNOWN = 0, /**< Protocol unknown */
559 
560 /* Built in library decoders */
561     OCSD_PROTOCOL_ETMV3,   /**< ETMV3 instruction and data trace protocol decoder. */
562     OCSD_PROTOCOL_ETMV4I,  /**< ETMV4 instruction trace protocol decoder. */
563     OCSD_PROTOCOL_ETMV4D,  /**< ETMV4 data trace protocol decoder. */
564     OCSD_PROTOCOL_PTM,     /**< PTM program flow instruction trace protocol decoder. */
565     OCSD_PROTOCOL_STM,     /**< STM system trace protocol decoder. */
566     OCSD_PROTOCOL_ETE,     /**< ETE trace protocol decoder */
567 
568 /* others to be added here */
569     OCSD_PROTOCOL_BUILTIN_END,  /**< Invalid protocol - built-in protocol types end marker */
570 
571 /* Custom / external decoders */
572     OCSD_PROTOCOL_CUSTOM_0 = 100,   /**< Values from this onwards are assigned to external registered decoders */
573     OCSD_PROTOCOL_CUSTOM_1,
574     OCSD_PROTOCOL_CUSTOM_2,
575     OCSD_PROTOCOL_CUSTOM_3,
576     OCSD_PROTOCOL_CUSTOM_4,
577     OCSD_PROTOCOL_CUSTOM_5,
578     OCSD_PROTOCOL_CUSTOM_6,
579     OCSD_PROTOCOL_CUSTOM_7,
580     OCSD_PROTOCOL_CUSTOM_8,
581     OCSD_PROTOCOL_CUSTOM_9,
582 
583     OCSD_PROTOCOL_END      /**< Invalid protocol - protocol types end marker */
584 } ocsd_trace_protocol_t;
585 
586 /** Test if protocol type is a library built-in decoder */
587 #define OCSD_PROTOCOL_IS_BUILTIN(P) ((P > OCSD_PROTOCOL_UNKNOWN) && (P < OCSD_PROTOCOL_BUILTIN_END))
588 
589 /** Test if protocol type is a custom external registered decoder */
590 #define OCSD_PROTOCOL_IS_CUSTOM(P)  ((P >= OCSD_PROTOCOL_CUSTOM_0) && (P < OCSD_PROTOCOL_END ))
591 
592 /** @}*/
593 
594 
595 /** @name Software Trace Packets Info
596 
597     Contains the information for the generic software trace output packet.
598 
599     Software trace packet master and channel data.
600     Payload info:
601         size - packet payload size in bits;
602         marker - if this packet has a marker/flag
603         timestamp - if this packet has a timestamp associated
604         number of packets - packet processor can optionally correlate identically
605         sized packets on the same master / channel to be output as a single generic packet
606 
607     Payload output as separate LE buffer, of sufficient bytes to hold all the packets.
608 @{*/
609 
610 typedef struct _ocsd_swt_info {
611     uint16_t swt_master_id;
612     uint16_t swt_channel_id;
613     union {
614         struct {
615             uint32_t swt_payload_pkt_bitsize:8; /**< [bits 0:7 ] Packet size in bits of the payload packets */
616             uint32_t swt_payload_num_packets:8; /**< [bits 8:15 ] number of consecutive packets of this type in the payload data */
617             uint32_t swt_marker_packet:1;       /**< [bit 16 ] packet is marker / flag packet */
618             uint32_t swt_has_timestamp:1;       /**< [bit 17 ] packet has timestamp. */
619             uint32_t swt_marker_first:1;        /**< [bit 18 ] for multiple packet payloads, this indicates if any marker is on first or last packet */
620             uint32_t swt_master_err:1;          /**< [bit 19 ] current master has error - payload is error code */
621             uint32_t swt_global_err:1;          /**< [bit 20 ] global error - payload is error code - master and channel ID not valid */
622             uint32_t swt_trigger_event:1;       /**< [bit 21 ] trigger event packet - payload is event number */
623             uint32_t swt_frequency:1;           /**< [bit 22 ] frequency packet - payload is frequency */
624             uint32_t swt_id_valid:1;            /**< [bit 23 ] master & channel ID has been set by input stream  */
625         };
626         uint32_t swt_flag_bits;
627     };
628 } ocsd_swt_info_t;
629 
630 /** mask for the swt_id_valid flag - need to retain between packets */
631 #define SWT_ID_VALID_MASK (0x1 << 23)
632 
633 /** @}*/
634 
635 /** @}*/
636 #endif // ARM_OCSD_IF_TYPES_H_INCLUDED
637 
638 /* End of File opencsd/ocsd_if_types.h */
639