vendor/opencsd/v1.4.0vendor/opencsd

2 files changed, 76 insertions, 6 deletions

diff --git a/decoder/docs/prog_guide/prog_guide_generic_pkts.md b/decoder/docs/prog_guide/prog_guide_generic_pkts.md
index e4d50b79fc80..aad15b847977 100644
--- a/decoder/docs/prog_guide/prog_guide_generic_pkts.md
+++ b/decoder/docs/prog_guide/prog_guide_generic_pkts.md
@@ -84,7 +84,11 @@ typedef struct _ocsd_generic_trace_elem {
         ocsd_swt_info_t sw_trace_info;      /* software trace packet info    */
 		uint32_t num_instr_range;	        /* number of instructions covered by range packet (for T32 this cannot be calculated from en-st/i_size) */
         unsync_info_t unsync_eot_info;      /* additional information for unsync / end-of-trace packets. */
-    };
+		trace_marker_payload_t sync_marker; /* marker element - sync later element to position in stream */
+        trace_memtrans_t mem_trans;         /* memory transaction packet - transaction event */
+        trace_sw_ite_t sw_ite;              /* PE sw instrumentation using FEAT_ITE */
+
+	};
 
     const void *ptr_extended_data;        /* pointer to extended data buffer (data trace, sw trace payload) / custom structure */
 
@@ -325,6 +329,58 @@ SW trace packets that have a payload will use the extended_data flag and pointer
 
 SW trace packets that include timestamp information will us the `has_ts` flag and fill in the timestamp value.
 
+These packets are generated by memory writes to STM / ITM trace hardware. 
+
+### OCSD_GEN_TRC_ELEM_SYNC_MARKER ###
+__packet fields valid__: `sync_marker`
+
+Synchronisation marker - marks position in stream of an element that is output later.
+e.g. a timestamp marker can be output to represent the correct position in the stream for a 
+timestamp packet the is output later.
+
+The `sync_marker` field has a structure as shown below.
+
+~~~{.c}
+typedef enum _trace_sync_marker_t {
+    ELEM_MARKER_TS,        /**< Marker for timestamp element */
+} trace_sync_marker_t;
+
+typedef struct _trace_marker_payload_t {
+    trace_sync_marker_t type;   /**< type of sync marker */
+    uint32_t value;             /**< sync marker value - usage depends on type */
+} trace_marker_payload_t;
+~~~
+
+### OCSD_GEN_TRC_ELEM_MEMTRANS ###
+__packet fields valid__: `mem_trans`
+
+Memory transaction elements may appear in the output stream, if they are not otherwise cancelled
+by speculative trace packets.
+
+The memory transaction field has values as defined in the enum below:-
+
+~~~{.c}
+typedef enum _memtrans_t {
+    OCSD_MEM_TRANS_TRACE_INIT,/* Trace started while PE in transactional state */
+    OCSD_MEM_TRANS_START,     /* Trace after this packet is part of a transactional memory sequence */
+    OCSD_MEM_TRANS_COMMIT,    /* Transactional memory sequence valid. */
+    OCSD_MEM_TRANS_FAIL,      /* Transactional memory sequence failed - operations since start of transaction have been unwound. */  
+} trace_memtrans_t;
+~~~
+
+### OCSD_GEN_TRC_ELEM_INSTRUMENTATION ###
+__packet fields valid__: `sw_ite`
+
+Software instrumentation packets generated by the PE `TRCIT` instruction (on cores with `FEAT_ITE`).
+
+The `sw_ite` structure has the fields defined below:-
+
+~~~{.c}
+typedef struct _sw_ite_t {
+    uint8_t el;             /* exception level for PE sw instrumentation instruction */
+    uint64_t value;         /* payload for PE sw instrumentation instruction */
+} trace_sw_ite_t;
+~~~
 
 ### OCSD_GEN_TRC_ELEM_CUSTOM ###
 __packet fields optional__: `extended_data -> ptr_extended_data`,_any others_
diff --git a/decoder/docs/prog_guide/prog_guide_main.md b/decoder/docs/prog_guide/prog_guide_main.md
index 87afbf0225c6..9504bdc244d3 100644
--- a/decoder/docs/prog_guide/prog_guide_main.md
+++ b/decoder/docs/prog_guide/prog_guide_main.md
@@ -138,9 +138,17 @@ The error logger can be attached to an output logger - ocsdMsgLogger - which can
 error, or other error messages, out to screen or logging file. Errors can be filtered according to a severity rating,
 defined by @ref ocsd_err_severity_t.
 
-The DecodeTree will use a default error logger from the library - with a message logger
-that will output to `stderr`. Client applications can adjust the configuration of this error logger and 
-message logger, or provide their own configured error logger / message logger pair. 
+The DecodeTree can use a default error logger from the library - with a message logger that will output to `stderr`. 
+
+Client applications can create and adjust the configuration of this error logger and message logger by getting and intialising
+ the logger. 
+
+~~~{.cpp}
+	// ** Initialise default error logger.
+	DecodeTree::getDefaultErrorLogger()->initErrorLogger(verbosity,true);
+~~~	
+
+Alternatively clients may provide their own configured error logger / message logger pair.
 
 The test program `trc_pkt_lister` provides a customised version of an `ocsdMsgLogger` / `ocsdDefaultErrorLogger` pair
 to ensure that messages and errors are logged to the screen and a file of its choice. This logger is eventually
@@ -272,6 +280,7 @@ The different trace source types have different configuration structures, classe
 
 | protocol  | config struct       |  class      |  name define                 | 
 |:----------|:--------------------|:------------|:-----------------------------|
+| __ETE__   | @ref ocsd_ete_cfg   | ETEConfig   | @ref OCSD_BUILTIN_DCD_ETE    |
 | __ETMv4__ | @ref ocsd_etmv4_cfg | EtmV4Config | @ref OCSD_BUILTIN_DCD_ETMV4I |
 | __ETMv3__ | @ref ocsd_etmv3_cfg | EtmV3Config | @ref OCSD_BUILTIN_DCD_ETMV3  |
 | __PTM__   | @ref ocsd_ptm_cfg   | PtmConfig   | @ref OCSD_BUILTIN_DCD_PTM    |
@@ -300,15 +309,19 @@ types to be managed by a memory access mapper:-
 
 ~~~{.cpp}
 	class DecodeTree {
-		///...
+		// ...
+		ocsd_err_t createMemAccMapper(memacc_mapper_t type = MEMACC_MAP_GLOBAL);
+		// ...
 		ocsd_err_t addBufferMemAcc(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const uint8_t *p_mem_buffer, const uint32_t mem_length);
 		ocsd_err_t addBinFileMemAcc(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const std::string &filepath);
 		ocsd_err_t addBinFileRegionMemAcc(const ocsd_file_mem_region_t *region_array, const int num_regions, const ocsd_mem_space_acc_t mem_space, const std::string &filepath);     */
 		ocsd_err_t addCallbackMemAcc(const ocsd_vaddr_t st_address, const ocsd_vaddr_t en_address, const ocsd_mem_space_acc_t mem_space, Fn_MemAcc_CB p_cb_func, const void *p_context); 
-		///...
+		// ...
 	}	
 ~~~
 
+The `createMemAccMapper()` function must be called to create the mapper, before the `add...MemAcc()` calls are used.
+
 It is further possible to differentiate between memory image access objects by the memory space for which they are valid. If it is known that a certain code image 
 is present in secure EL3, then an image can be associated with the @ref ocsd_mem_space_acc_t type value @ref OCSD_MEM_SPACE_EL3, which will allow another image to be 
 present at the same address but a different exception level.  However, for the majority of systems, such detailed knowledge of the code is not available, or 
@@ -323,6 +336,7 @@ The C-API contains a similar set of calls to set up memory access objects:-
 	OCSD_C_API ocsd_err_t ocsd_dt_add_callback_mem_acc(const dcd_tree_handle_t handle, const ocsd_vaddr_t st_address, const ocsd_vaddr_t en_address, const ocsd_mem_space_acc_t mem_space, Fn_MemAcc_CB p_cb_func, const void *p_context); 
 ~~~
 
+Note that the C-API will automatically create a default mapper when the first memory access object is added.
 
 ### Adding the output callbacks ###