Adding upstream version 1.3.3.upstream/1.3.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

7 files changed, 1064 insertions, 0 deletions

diff --git a/decoder/docs/prog_guide/cs_trace_hw.jpg b/decoder/docs/prog_guide/cs_trace_hw.jpg
new file mode 100644
index 0000000..af88f51
--- /dev/null
+++ b/decoder/docs/prog_guide/cs_trace_hw.jpg
diff --git a/decoder/docs/prog_guide/decode_data_path_resp.jpg b/decoder/docs/prog_guide/decode_data_path_resp.jpg
new file mode 100644
index 0000000..eb7edb9
--- /dev/null
+++ b/decoder/docs/prog_guide/decode_data_path_resp.jpg
diff --git a/decoder/docs/prog_guide/dt_components.jpg b/decoder/docs/prog_guide/dt_components.jpg
new file mode 100644
index 0000000..0b0270d
--- /dev/null
+++ b/decoder/docs/prog_guide/dt_components.jpg
diff --git a/decoder/docs/prog_guide/lib_usage.jpg b/decoder/docs/prog_guide/lib_usage.jpg
new file mode 100644
index 0000000..6baaa12
--- /dev/null
+++ b/decoder/docs/prog_guide/lib_usage.jpg
diff --git a/decoder/docs/prog_guide/memacc_objs.jpg b/decoder/docs/prog_guide/memacc_objs.jpg
new file mode 100644
index 0000000..ad329d4
--- /dev/null
+++ b/decoder/docs/prog_guide/memacc_objs.jpg
diff --git a/decoder/docs/prog_guide/prog_guide_generic_pkts.md b/decoder/docs/prog_guide/prog_guide_generic_pkts.md
new file mode 100644
index 0000000..4a2f5b2
--- /dev/null
+++ b/decoder/docs/prog_guide/prog_guide_generic_pkts.md
@@ -0,0 +1,453 @@
+OpenCSD Library - Generic Trace Packet Descriptions   {#generic_pkts}	
+===================================================
+
+@brief Interpretation of the Generic Trace output packets.
+
+Generic Trace Packets - Collection.
+-----------------------------------
+
+### Packet interface ###
+
+The generic trace packets are the fully decoded output from the trace library. 
+
+These are delivered to the client application in the form of a callback function. Packets from all trace sources 
+will use the same single callback function, with the CoreSight Trace ID provided to identify the source.
+
+The callback is in the form of an interface class ITrcGenElemIn, which has a single function:
+
+~~~{.cpp}
+virtual ocsd_datapath_resp_t TraceElemIn(    const ocsd_trc_index_t index_sop,
+                                             const uint8_t trc_chan_id,
+                                             const OcsdTraceElement &elem
+										) = 0;
+~~~
+
+The client program will create derived class providing this interface to collect trace packets from the library.
+
+The parameters describe the output packet and source channel:
+|Parameter                        | Description                                                             | 
+|:--------------------------------|:------------------------------------------------------------------------|
+| `ocsd_trc_index_t index_sop`    | Index of the first byte of the trace packet that generated this output. |
+| `uint8_t trc_chan_id`           | The source CoreSight Trace ID.                                          |
+| `OcsdTraceElement &elem`        | The packet class - wraps the `ocsd_generic_trace_elem` structure.       | 
+
+_Note_ : `index_sop` may be the same for multiple output packets. This is due to an one byte atom packet which
+can represent multiple atoms and hence multiple ranges.
+
+The C-API provides a similarly specified callback function definition, with an additional opaque `void *` pointer
+that the client application may use.
+
+~~~{.c}
+/** function pointer type for decoder outputs. all protocols, generic data element input */
+typedef ocsd_datapath_resp_t (* FnTraceElemIn)( const void *p_context, 
+                                                const ocsd_trc_index_t index_sop, 
+                                                const uint8_t trc_chan_id, 
+                                                const ocsd_generic_trace_elem *elem); 
+~~~
+
+### The Packet Structure ###
+
+~~~{.c}
+typedef struct _ocsd_generic_trace_elem {
+    ocsd_gen_trc_elem_t elem_type;   /* Element type - remaining data interpreted according to this value */
+    ocsd_isa           isa;          /* instruction set for executed instructions */
+    ocsd_vaddr_t       st_addr;      /* start address for instruction execution range / inaccessible code address / data address */
+    ocsd_vaddr_t       en_addr;        /* end address (exclusive) for instruction execution range. */
+    ocsd_pe_context    context;        /* PE Context */
+    uint64_t           timestamp;      /* timestamp value for TS element type */
+    uint32_t           cycle_count;    /* cycle count for explicit cycle count element, or count for element with associated cycle count */
+    ocsd_instr_type    last_i_type;    /* Last instruction type if instruction execution range */
+    ocsd_instr_subtype last_i_subtype; /* sub type for last instruction in range */
+ 
+    //! per element flags
+    union {
+        struct {
+            uint32_t last_instr_exec:1;     /* 1 if last instruction in range was executed; */
+			uint32_t last_instr_sz:3;       /* size of last instruction in bytes (2/4) */
+            uint32_t has_cc:1;              /* 1 if this packet has a valid cycle count included (e.g. cycle count included as part of instruction range packet, always 1 for pure cycle count packet.*/
+            uint32_t cpu_freq_change:1;     /* 1 if this packet indicates a change in CPU frequency */
+            uint32_t excep_ret_addr:1;      /* 1 if en_addr is the preferred exception return address on exception packet type */
+            uint32_t excep_data_marker:1;   /* 1 if the exception entry packet is a data push marker only, with no address information (used typically in v7M trace for marking data pushed onto stack) */
+            uint32_t extended_data:1;       /* 1 if the packet extended data pointer is valid. Allows packet extensions for custom decoders, or additional data payloads for data trace.  */
+            uint32_t has_ts:1;              /* 1 if the packet has an associated timestamp - e.g. SW/STM trace TS+Payload as a single packet */
+            uint32_t last_instr_cond:1;     /* 1 if the last instruction was conditional */
+            uint32_t excep_ret_addr_br_tgt:1; /* 1 if exception return address (en_addr) is also the target of a taken branch addr from the previous range. */
+        };
+        uint32_t flag_bits;
+    };
+
+    //! packet specific payloads
+    union {  
+        uint32_t exception_number;          /* exception number for exception type packets */
+        trace_event_t  trace_event;         /* Trace event - trigger etc      */
+        trace_on_reason_t trace_on_reason;  /* reason for the trace on packet */
+        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 */
+	};
+
+    const void *ptr_extended_data;        /* pointer to extended data buffer (data trace, sw trace payload) / custom structure */
+
+} ocsd_generic_trace_elem;
+~~~
+
+The packet structure contains multiple fields and flag bits. The validity of any of these fields or flags
+is dependent on the `elem_type` member. The client program must not assume that field values will persist 
+between packets, and must process all valid data during the callback function.
+
+The packet reference guide below defines the fields valid for each packet type.
+
+--------------------------------------------------------------------------------------------------
+
+Generic Trace Packets - Packet Reference.
+-----------------------------------------
+
+This section contains reference descriptions of each of the generic trace packets types define as part of the 
+`ocsd_gen_trc_elem_t` enum value that appears as the first `elem_type` field in the packet structure.
+
+The descriptions will include information on which fields in the packets are always valid, optional and any protocol specific information. 
+
+The tags used in the reference are:-
+- __packet fields valid__ : fields that are always valid and filled for this packet type.
+- __packet fields optional__ : fields that _may_ be filled for this packet type.
+ The form `flag -> field` indicates a flag that may be set and the value that is valid if the flag is true
+- __protocol specific__ : indicates type or fields may be source protocol specific.
+
+_Note_: while most of the packets are not protocol specific, there are some protocol differences that mean
+certain types and fields will differ slightly across protocols. These differences are highlighted in the 
+reference.
+
+### OCSD_GEN_TRC_ELEM_NO_SYNC ###
+__packet fields valid__: None
+
+Element output before the decoder has synchronised with the input stream, or synchronisation is lost.
+
+### OCSD_GEN_TRC_ELEM_INSTR_RANGE ###
+__packet fields valid__: `isa, st_addr, en_addr, last_i_type, last_i_subtype, last_instr_exec, last_instr_sz, num_instr_range, last_instr_cond`
+
+__packet fields optional__: `has_cc -> cycle_count,`
+
+__protocol specific__ : ETMv3, PTM 
+
+This should be the most common packet output for full trace decode. Represents a range of instructions of 
+a single `isa`, executed by the PE. Instruction byte range is from `st_addr` (inclusive) to `en_addr` (exclusive).
+The total number of instructions executed for the range is given in `num_instr_range`.
+
+Information on the last instruction in the range is provided. `last_i_type` shows if the last instruction
+was a branch or otherwise - which combined with `last_instr_exec` determines if the branch was taken.
+The last instruction size in bytes is given, to allow clients to quickly determine the address of the last 
+instruction by subtraction from `en_addr`. This value can be 2 or 4 bytes in the T32 instruction set. 
+
+__ETMv3, PTM__ : These protocols can output a cycle count directly as part of the trace packet that generates 
+the trace range. In this case `has_cc` will be 1 and `cycle_count` will be valid.
+
+
+### OCSD_GEN_TRC_ELEM_I_RANGE_NOPATH ###  
+__packet fields valid__: `isa, st_addr, en_addr, num_instr_range`
+
+`num_instr_range` represents the number of instructions executed in this range, but there is incomplete information 
+as to program execution path from start to end of range.
+If `num_instr` is 0, then an unknown number of instructions were executed between the start and end of the range.
+`st_addr` represents the start of execution represented by this packet.
+`en_addr` represents the address where execution will continue from after the instructions represented by this packet.
+`isa` represents the ISA for the instruction at `en_addr`.
+
+Used when ETMv4 Q elements are being traced.
+
+
+### OCSD_GEN_TRC_ELEM_ADDR_NACC ###
+__packet fields valid__: `st_addr`
+
+Trace decoder found address in trace that cannot be accessed in the mapped memory images.
+`st_addr` is the address that cannot be found.
+
+Decoder will wait for new address to appear in trace before attempting to restart decoding. 
+ 
+
+### OCSD_GEN_TRC_ELEM_UNKNOWN ###
+__packet fields valid__: None
+
+Decoder saw invalid packet for protocol being processed. Likely incorrect protocol settings, or corrupted 
+trace data.
+  
+### OCSD_GEN_TRC_ELEM_TRACE_ON ###
+__packet fields valid__: trace_on_reason
+
+__packet fields optional__: `has_cc -> cycle_count,`
+
+__protocol specific__ : ETMv3, PTM
+ 
+Notification that trace has started / is synced after a discontinuity or at start of trace decode.
+
+__ETMv3, PTM__ : These protocols can output a cycle count directly as part of the trace packet that generates 
+the trace on indicator. In this case `has_cc`  will be 1 and `cycle_count` will be valid.
+
+
+### OCSD_GEN_TRC_ELEM_EO_TRACE ###
+__packet fields valid__: None
+
+Marker for end of trace data. Sent once for each CoreSight ID channel.
+
+### OCSD_GEN_TRC_ELEM_PE_CONTEXT ###
+__packet fields valid__: context
+
+__packet fields optional__: `has_cc -> cycle_count,`
+
+__protocol specific__ : ETMv3, PTM
+
+This packet indicates an update to the PE context - which may be the initial context in a trace stream, or a 
+change since the trace started.
+
+The context is contained in a `ocsd_pe_context` structure.
+
+~~~{.c}
+typedef struct _ocsd_pe_context {    
+    ocsd_sec_level security_level;     /* security state */
+    ocsd_ex_level  exception_level;    /* exception level */
+    uint32_t        context_id;         /* context ID */
+    uint32_t        vmid;               /* VMID */
+    struct {
+        uint32_t bits64:1;              /* 1 if 64 bit operation */
+        uint32_t ctxt_id_valid:1;       /* 1 if context ID value valid */
+        uint32_t vmid_valid:1;          /* 1 if VMID value is valid */
+        uint32_t el_valid:1;            /* 1 if EL value is valid (ETMv4 traces current EL, other protocols do not) */
+    };
+} ocsd_pe_context;
+~~~
+
+__ETMv3, PTM__ : These protocols can output a cycle count directly as part of the trace packet that generates 
+the PE context. In this case `has_cc`  will be 1 and `cycle_count` will be valid.
+
+__ETMv3__ :  From ETM 3.5 onwards, exception_level can be set to `ocsd_EL2` when tracing through hypervisor code.
+On all other occasions this will be set to `ocsd_EL_unknown`.
+
+
+### OCSD_GEN_TRC_ELEM_ADDR_UNKNOWN ###
+__packet fields optional__: `has_cc -> cycle_count,`
+
+__protocol specific__: ETMv3
+
+This packet will only be seen when decoding an ETMv3 protocol source. This indicates that the decoder
+is waiting for a valid address in order to process trace correctly. 
+
+The packet can have a cycle count associated with it which the client must account for when tracking cycles used.
+The packet will be sent once when unknown address occurs. Further `OCSD_GEN_TRC_ELEM_CYCLE_COUNT` packets may follow
+ before the decode receives a valid address to continue decode.
+
+
+### OCSD_GEN_TRC_ELEM_EXCEPTION ###
+__packet fields valid__: `exception_number`
+
+__packet fields optional__: `has_cc -> cycle_count, excep_ret_addr -> en_addr, excep_data_marker, excep_ret_addr_br_tgt`
+
+__protocol specific__: ETMv4, ETMv3, PTM
+
+All protocols will include the exception number in the packet.
+
+__ETMv4__ : This protocol may provide the preferred return address for the exception - this is the address of
+the instruction that could be executed on exception return. This address appears in `en_addr` if `excep_ret_addr` = 1.
+
+Additionally, this address could also represent the target address of a branch, if the exception occured at the branch target, before any further instructions were execute. If htis is the case then the excep_ret_addr_br_tgt flag will be set. This makes explicit what was previously only implied by teh packet ordered. This information could be used for clients such as perf that branch source/target address pairs.
+
+__ETMv3__ : This can set the `excep_data_marker` flag. This indicates that the exception packet is a marker
+to indicate exception entry in a 7M profile core, for the purposes of tracking data. This will __not__ provide
+an exception number in this case.
+
+__PTM__ : Can have an associated cycle count (`has_cc == 1`), and may provide preferred return address in `en_addr` 
+if `excep_ret_addr` = 1.
+
+### OCSD_GEN_TRC_ELEM_EXCEPTION_RET ###
+__packet fields valid__: None
+
+Marker that a preceding branch was an exception return.
+
+### OCSD_GEN_TRC_ELEM_TIMESTAMP ###
+__packet fields valid__: `timestamp`
+
+__packet fields optional__: `has_cc -> cycle_count,`
+
+__protocol specific__: ETMv4, PTM
+
+The timestamp packet explicitly provides a timestamp value for the trace stream ID in the callback interface.
+
+__PTM__ : This can have an associated cycle count (`has_cc == 1`). For this protocol, the cycle count __is__ part
+of the cumulative cycle count for the trace session.
+
+__ETMv4__ : This can have an associated cycle count (`has_cc == 1`). For this protocl, the cycle coun represents
+the number of cycles between the previous cycle count packet and this timestamp packet, but __is not__ part of 
+the cumulative cycle count for the trace session.
+
+
+### OCSD_GEN_TRC_ELEM_CYCLE_COUNT ###
+__packet fields valid__: `has_cc -> cycle_count`
+
+Packet contains a cycle count value. A cycle count value represents the number of cycles passed since the 
+last cycle count value seen. The cycle count value may be associated with a specific packet or instruction
+range preceding the cycle count packet.
+
+Cycle count packets may be added together to build a cumulative count for the trace session.
+
+### OCSD_GEN_TRC_ELEM_EVENT ###
+__packet fields valid__: `trace_event`
+
+This is a hardware event injected into the trace by the ETM/PTM hardware resource programming. See the
+relevent trace hardware reference manuals for the programming of these events. 
+
+The `trace_event` is a `trace_event_t` structure that can have an event type - and an event number.
+
+~~~{.c}
+typedef struct _trace_event_t {
+    uint16_t ev_type;          /* event type - unknown (0) trigger (1), numbered event (2)*/
+    uint16_t ev_number;        /* event number if numbered event type */
+} trace_event_t;
+~~~
+
+The event types depend on the trace hardware:-
+
+__ETMv4__ : produces numbered events. The event number is a bitfield of up to four events that occurred.
+Events 0-3 -> bits 0-3. The bitfield allows a single packet to represent multiple different events occurring.
+
+_Note_: The ETMv4 specification has further information on timing of events and event packets.  Event 0 
+is also considered a trigger event in ETMv4 hardware, but is not explicitly represented as such in the OCSD protocol.
+
+__PTM__, __ETMv3__ : produce trigger events. Event number always set to 0.
+
+
+### OCSD_GEN_TRC_ELEM_SWTRACE ###
+__packet fields valid__: `sw_trace_info`
+
+__packet fields optional__: `has_ts -> timestamp`, ` extended_data -> ptr_extended_data`
+
+The Software trace packet always has a filled in `sw_trace_info` field to describe the current master and channel ID, 
+plus the packet type and size of any payload data.
+
+SW trace packets that have a payload will use the extended_data flag and pointer to deliver this data.
+
+SW trace packets that include timestamp information will us the `has_ts` flag and fill in the timestamp value.
+
+
+### 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_CUSTOM ###
+__packet fields optional__: `extended_data -> ptr_extended_data`,_any others_
+
+Custom protocol decoders can use this packet type to provide protocol specific information. 
+
+Standard fields may be used for similar purposes as defined above, or the extended data pointer can reference
+other data.
+
+--------------------------------------------------------------------------------------------------
+
+Generic Trace Packets - Notes on interpretation.
+------------------------------------------------
+
+The interpretation of the trace output should always be done with reference to the underlying protocol 
+specifications. 
+
+While the output packets are in general protocol agnostic, there are some inevitable 
+differences related to the underlying protocol that stem from the development of the trace hardware over time.
+
+### OCSD ranges and Trace Atom Packets ###
+The most common raw trace packet in all the protocols is the Atom packet, and this packet is the basis for most of
+the `OCSD_GEN_TRC_ELEM_INSTR_RANGE` packets output from the library. A trace range will be output for each atom 
+in the raw trace stream - the `last_instr_exec` flag taking the value of the Atom - 1 for E, 0 for N.
+
+`OCSD_GEN_TRC_ELEM_INSTR_RANGE` packets can also be generated for non-atom packets, where flow changes - e.g.
+exceptions.
+
+
+### Multi feature OCSD output packets ###
+Where a raw trace packet contains additional information on top of the basic packet data, then this additional
+information will be added to the OCSD output packet and flagged accordingly (in the `flag_bits` union in the
+packet structure).
+
+Typically this will be atom+cycle count packets in ETMv3 and PTM protocols. For efficiency and to retain
+the coupling between the information an `OCSD_GEN_TRC_ELEM_INSTR_RANGE` packet will be output in this case
+with a `has_cc` flag set and the `cycle_count` value filled.
+
+ETMv3 and PTM can add a cycle count to a number of packets, or explicitly emit a cycle count only packet. By
+contrast ETMv4 only emits cycle count only packets.
+
+Clients processing the library output must be aware of these optional additions to the base packet. The 
+OCSD packet descriptions above outline where the additional information can occur.
+
+### Cycle counts ###
+
+Cycle counts are cumulative, and represent cycles since the last cycle count output.
+Explicit cycle count packets are associated with the previous range event, otherwise where a 
+packet includes a cycle count as additional information, then the count is associated with that
+specific packet - which will often be a range packet.
+
+The only exception to this is where the underlying protocol is ETMv4, and a cycle count is included
+in a timestamp packet. Here the cycle count represents that number of cycles since the last cycle count
+packet that occurred before the timestamp packet was emitted. This cycle count is not part of the cumulative 
+count. See the ETMv4 specification for further details.
+
+
+### Correlation - timestamps and cycle counts ###
+
+Different trace streams can be correlated using either timestamps, or timestamps plus cycle counts. 
+
+Both timestamps and cycle counts are enabled by programming ETM control registers, and it is also possible 
+to control the frequency that timestamps appear, or the threshold at which cycle count packets are emitted by
+additional programming. 
+
+The output of timestamps and cycle counts increases the amount of trace generated, very significantly when cycle 
+counts are present, so the choice of generating these elements needs to be balanced against the requirement
+for their use.
+
+Decent correlation can be gained by the use of timestamps alone - especially if the source is programmed to 
+produce them more frequently than the default timestamp events. More precise correllation can be performed if
+the 'gaps' between timestamps can be resolved using cycle counts. 
+
+Correlation is performed by identifying the same/close timestamp values in two separate trace streams. Cycle counts 
+if present can then be used to resolve the correlation with additional accuracy. 
+
+
+
+
+
+
+
+
+
+
+
diff --git a/decoder/docs/prog_guide/prog_guide_main.md b/decoder/docs/prog_guide/prog_guide_main.md
new file mode 100644
index 0000000..9504bdc
--- /dev/null
+++ b/decoder/docs/prog_guide/prog_guide_main.md
@@ -0,0 +1,611 @@
+OpenCSD Library - Programmers Guide    {#prog_guide}	
+===================================
+
+@brief  A guide to programming the OpenCSD library.
+
+Introduction and review of Coresight Hardware 
+---------------------------------------------
+
+The OpenCSD trace decode library is designed to allow programmers to decode ARM CoreSight trace
+data. This guide will describe the various stages of configuring and programming a decoder instance 
+for a given CoreSight system.
+
+The diagram below shows a typical Coresight trace hardware arrangement
+
+![Example CoreSight Trace Capture Hardware](cs_trace_hw.jpg)
+
+The design shown has four Cortex cores, each with an ETM, along with a system STM all of which generate trace into the
+trace funnel. The output of the funnel is fed into a trace sink, which might be an ETB or ETR, saving the trace
+which is multiplexed into CoreSight trace frames in the trace sink memory. The colours represent the sources 
+of trace data, each of which will be tagged with a CoreSight Trace ID.
+
+### CoreSight Trace ID ###
+The CoreSight Trace ID - also referred to as the Trace Source Channel ID - is a unique 8 bit number programmed
+into each trace source in a system (ETM,PTM,STM) which identifies the source to both the hardware components 
+downstream and the software trace decoders. This ID is used 
+
+Overview of Configuration and Decode
+------------------------------------
+
+The OpenCSD library will take the trace data from the trace sink, and when correctly configured and programmed, will
+demultiplex and decode each of the trace sources.
+
+The library supports ETMV3, PTM, ETMv4 and STM trace protocols. The decode occurs in three stages:
+- __Demultiplex__ - the combined trace streams in CoreSight trace frame format are split into their constituent streams according to the CoreSight trace ID.
+- __Packet Processing__ - the individual trace ID streams are resolved into discrete trace packets.
+- __Packet Decode__ - the trace packets are interpreted to produce a decoded representation of instructions executed.
+
+There are input configuration requirements for each stage of the decode process - these allow the decode process to correctly 
+interpret the incoming byte stream.
+- __Demultiplex__ - Input flags are set to indicate if the frames are 16 byte aligned or if the stream contains alignment 
+bytes between frames.
+- __Packet Processing__ - The hardware configuration of the trace source must be provided. This consists of a sub-set of the
+hardware register values for the source.  Each protocol has differing requirements, represented by an input structure of the 
+register values.
+- __Packet Decode__ - For ETM/PTM packet decode, this stage requires the memory images of the code executed in order 
+to determine the path through the code. These are provided either as memory dumps, or as links to binary code files.
+
+_Note_ : STM, being a largely software generated data trace, does not require memory images to recover the data written by the source
+processors.
+
+The diagram below shows the basic stages of decode for the library when used in a client application:
+
+![Example Library Usage for Trace Decode](lib_usage.jpg)
+
+The DecodeTree object is a representation of the structure of the CoreSight hardware, but in reverse in that the data is pushed into the 
+tree, through the demultiplexor and then along the individual trace stream decode paths till the output decode packets are produced.
+
+These outpup packets are referred to as Generic Trace packets, and are at this stage protocol independent. They consist primarily of
+PE context information and address ranges representing the instructions processed.
+
+### Decode Tree ###
+
+The DecodeTree is the principal wrapper for all the decoders the library supports. This provides a programming 
+API which allows the creation of protocol packet processors and decoders. 
+
+The API allows the client application to configure the de-multiplexor, create and connect packet processors and 
+packet decoders to the trace data streams and collect the output generic decoded trace packets. The DecodeTree 
+provides a built in instruction decoder to allow correct trace decode, and an additional API through a memory 
+access handler to allow the client applications to provide the images of the traced code in file or memory dump  
+format. 
+
+Once a DecodeTree is configured, then it can be re-used for multiple sets of captured trace data where the same
+set of applications has been traced, or by changing only the supplied memory images, different traced applications
+on the same hardware configuration.
+
+The process for programming a decode tree for a specific set of trace hardware is as follows;-
+1. Create the decode tree and specify the de-multiplexor options.
+2. For each trace protocol of interest, use the API to create a decoder, providing the hardware configuration, 
+including the CoreSight trace ID for that trace stream. Specify packet processing only, or full decode. Client
+program must know the correct protocol to use for each trace stream.
+3. Attach callback(s) to receive the decoded generic trace output (ITrcGenElemIn).
+4. Provide the memory images if using full decode.
+
+The DecodeTree can now be used to process the trace data by pushing the captured trace data through the trace
+ data input API call (ITrcDataIn) and analyzing as required the resulting decoded trace (ITrcGenElemIn).
+ 
+ The objects and connections used for a single trace stream are shown below.
+ 
+ ![Decode Tree objects - single trace stream](dt_components.jpg)
+ 
+ All these components can be created and used outside of a DecodeTree, but that is beyond the scope of this
+ guide and expected to be used for custom implementations only.
+
+Programming Examples - decoder configuration.
+---------------------------------------------
+
+The remainder of this programming guide will provide programming exceprts for each of the required stages
+to get a working decode tree, capable of processing trace data.
+
+The guide will be based on an ETMv4 system, similar to the example above, using the C++ interface, but 
+equivalent calls from the C-API wrapper library will also be provided.
+
+The source code for the two test applications `trc_pkt_lister` and `c_api_pkt_print_test` may be used as 
+further programming guidance.
+
+### Create the decode tree ###
+
+The first step is to create the decode tree. Key choices here are the flags defining expected trace data
+input format and de-mux operations.
+
+~~~{.cpp}
+	uint32_t formatterCfgFlags = OCSD_DFRMTR_FRAME_MEM_ALIGN; /* basic operational mode for on-chip captured trace */
+	DecodeTree *pTree = DecodeTree::CreateDecodeTree(OCSD_TRC_SRC_FRAME_FORMATTED, formatterCfgFlags);
+~~~
+
+This creates a decode tree that is usable in the majority of cases - that is for trace captured in on chip
+RAM via ETB or ETR. Additional flags are available if a TPIU is used that will indicate to the frame de-mux
+that additional frame synchronisation data is present.
+
+In limited cases where the hardware has a single trace source, or only a single source is being used, then
+it is possible to switch off the hardware frame formatter in the ETB/ETR/TPIU. In this case @ref OCSD_TRC_SRC_SINGLE
+ (from enum @ref ocsd_dcd_tree_src_t) may be defined as the first parameter to the function.
+ 
+C-API version of above code:
+~~~{.c}
+	dcd_tree_handle_t dcdtree_handle = ocsd_create_dcd_tree(OCSD_TRC_SRC_FRAME_FORMATTED, OCSD_DFRMTR_FRAME_MEM_ALIGN);
+~~~
+
+### Error loggers and printers ###
+
+The library defines a standard error logging interface ITraceErrorLog which many of the key components can register 
+with to output errors. The process of registering the source means that errors can be tied to a particular component, 
+or CoreSight Trace ID. The library provides a standard error logger object - ocsdDefaultErrorLogger - which 
+keeps a copy of the last error logged, plus a copy of the last error logged for each data stream associated 
+with a CoreSight trace ID. 
+
+The error logger can be attached to an output logger - ocsdMsgLogger - which can print text versions of the
+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 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
+passed through to the decode tree.
+
+Code excerpts below (trc_pkt_lister.cpp):
+
+~~~{.cpp}
+	static ocsdMsgLogger logger;
+	static int logOpts = ocsdMsgLogger::OUT_STDOUT | ocsdMsgLogger::OUT_FILE;
+	static std::string logfileName = "trc_pkt_lister.ppl";
+	
+	// ** other vars
+	
+	main() {
+		
+		// ** some init code
+	
+	    logger.setLogOpts(logOpts);
+		logger.setLogFileName(logfileName.c_str());	
+
+
+		ocsdDefaultErrorLogger err_log;
+		err_log.initErrorLogger(OCSD_ERR_SEV_INFO);
+		err_log.setOutputLogger(&logger);
+		
+		// pass err_log reference into snapshot library code
+		SnapShotReader ss_reader;
+		ss_reader.setErrorLogger(&err_log);
+		
+		// ** rest of program 
+	}
+~~~
+	
+In the library code for the snapshot reader (ss_to_dcd_tree.cpp):
+
+~~~{.cpp}	
+	bool CreateDcdTreeFromSnapShot::createDecodeTree()
+	{
+		// ** create a decode tree
+		
+	    // use our error logger - don't use the tree default.
+        m_pDecodeTree->setAlternateErrorLogger(m_pErrLogInterface);
+	}
+	
+~~~
+
+__Note__:  The Snapshot reader library is test code designed to allow the test application read trace snapshots 
+which are in the form defined by the open specification in `./decoder/docs/specs/ARM Trace and Debug Snapshot file format 0v2.pdf`
+
+This format is used in ARM's DS-5 debugger, and the open source CoreSight Access Library (CSAL).
+
+### Configuring decoders ###
+
+The next task is to configure the requried decoders. The client program must know the type of ETM/PTM in use
+to correctly set the decoder configuration.
+
+Each class of trace source has a specific set of register values that the decoder requires to correctly interpret the 
+raw trace data and convert it to packets then fully decode.
+
+Configuration of an ETMv4 decoder requires initialisation of the EtmV4Config class, which is achieved by filling in a 
+@ref ocsd_etmv4_cfg structure:-
+
+~~~{.c}
+	typedef struct _ocsd_etmv4_cfg 
+	{
+		uint32_t                reg_idr0;    /**< ID0 register */
+		uint32_t                reg_idr1;    /**< ID1 register */
+		uint32_t                reg_idr2;    /**< ID2 register */
+		uint32_t                reg_idr8;
+		uint32_t                reg_idr9;   
+		uint32_t                reg_idr10;
+		uint32_t                reg_idr11;
+		uint32_t                reg_idr12;
+		uint32_t                reg_idr13;
+		uint32_t                reg_configr;  /**< Config Register */
+		uint32_t                reg_traceidr;  /**< Trace Stream ID register */
+		ocsd_arch_version_t    arch_ver;   /**< Architecture version */
+		ocsd_core_profile_t    core_prof;  /**< Core Profile */
+	} ocsd_etmv4_cfg;
+~~~
+
+The structure contains a number of read-only ID registers, and key programmable control registers that define
+the trace output features - such as if the ETM will output timestamps or cycle counts - and the CoreSight Trace ID.
+
+Once this structure is filled in then the decoder can be configured in the decode tree:-
+
+~~~{.cpp}
+	ocsd_etmv4_cfg config;
+	
+	// ...
+	// code to fill in config from programmed registers and id registers
+	// ...
+	
+	EtmV4Config configObj(&config);		// initialise decoder config class 
+	std::string decoderName(OCSD_BUILTIN_DCD_ETMV4I);  // use built in ETMv4 instruction decoder.
+	int decoderCreateFlags = OCSD_CREATE_FLG_FULL_DECODER; // decoder type to create - OCSD_CREATE_FLG_PACKET_PROC for packet processor only
+	ocsd_err_t err = pDecodeTree->createDecoder(decoderName, decoderCreateFlags,&configObj);
+~~~
+
+This code creates a full trace decoder for an ETMv4 source, which consists of a packet processor and packet decoder pair. The decoder is automatically associated with the 
+CoreSight Trace ID programmed into the register provided in the `config` structure. 
+
+It is also possible to create a packet processor only decoder if the `OCSD_CREATE_FLG_PACKET_PROC` flag is 
+used instead. These packet only decoders can be used to create a dump of the raw trace as discrete trace packets.
+
+All decoders a registered with the library using a name - the standard ARM protocols are considered built in
+decoders and are registered automatically. The library contains defined names for these decoders - `OCSD_BUILTIN_DCD_ETMV4I`
+ being the name used for ETMv4 protocol.
+
+The C-API uses the call create_generic_decoder() with the same configuration structure:-
+
+~~~{.c}
+	ocsd_etmv4_cfg config;
+	
+	// ...
+	// code to fill in config from programmed registers and id registers
+	// ...
+	
+	const char * decoderName = OCSD_BUILTIN_DCD_ETMV4I);  // use built in ETMv4 instruction decoder.
+	int decoderCreateFlags = OCSD_CREATE_FLG_FULL_DECODER; // decoder type to create - OCSD_CREATE_FLG_PACKET_PROC for packet processor only
+	void *p_context =  // <some_client_context>
+	ocsd_err_t err = create_generic_decoder(dcdtree_handle,decoderName,(void *)&config,p_context);	
+~~~
+
+The configuration must be completed for each trace source in the decode tree which requires decoding.
+
+The different trace source types have different configuration structures, classes and names
+
+| 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    |
+| __STM__   | @ref ocsd_stm_cfg   | STMConfig   | @ref OCSD_BUILTIN_DCD_STM    |
+
+### Adding in Memory Images ###
+
+Memory images are needed when a full trace decode is required. Memory images consist of a base address and length, and 
+contain instruction opcodes that may be executed during the operation of the traced program. The images are used by 
+the decoder to follow the path of the traced program by interpreting the information contained within the trace that 
+defines which program branches are taken and the target addresses of those branches.
+
+The library defined memory image accessor objects, which can be simple memory buffers, files containing the binary
+code image, or a callback that allows the client to handle memory accesses directly. When files are used, the 
+ object may contain a set of base addresses and lengths, with offsets into the file - allowing the decoder 
+ to directly access multiple code segments in executable image files.
+
+Memory image objects are collated by a memory mapper. This interfaces to the decoder through the ITargetMemAccess interface,
+and selects the correct image object for the address requested by the decoder. The memory mapper will also validate image 
+objects as they are added to the decoder, and will not permit overlapping images. 
+
+![Memory Mapper and Memory Images](memacc_objs.jpg)
+
+The client can add memory images to the decoder via API calls to the decode tree. These methods add memory image accessors of various
+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 
+overlaps across memory spaces do not occur. In these cases, and for general use (including Linux trace decode),  @ref OCSD_MEM_SPACE_ANY should be used.
+
+The C-API contains a similar set of calls to set up memory access objects:-
+
+~~~{.c}
+	OCSD_C_API ocsd_err_t ocsd_dt_add_buffer_mem_acc(const dcd_tree_handle_t handle, 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_C_API ocsd_err_t ocsd_dt_add_binfile_mem_acc(const dcd_tree_handle_t handle, const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const char *filepath); 
+	OCSD_C_API ocsd_err_t ocsd_dt_add_binfile_region_mem_acc(const dcd_tree_handle_t handle, const ocsd_file_mem_region_t *region_array, const int num_regions, const ocsd_mem_space_acc_t mem_space, const char *filepath); 
+	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 ###
+
+The decoded trace output ia collect by the client application through callback functions registered with the library.
+
+Depending on the decode configuration chosen, this can be in the form of the fully decoded trace output as generic trace
+packets, or discrete trace packets for each trace stream ID.
+
+__Full Decode__
+
+When full decode is chosen then all output is via the generic packet interface:
+
+~~~{.cpp}
+	class ITrcGenElemIn
+	{
+		///...
+		
+		virtual ocsd_datapath_resp_t TraceElemIn(const ocsd_trc_index_t index_sop,
+                                              const uint8_t trc_chan_id,
+                                              const OcsdTraceElement &el);
+    }
+~~~
+
+The client application registers a callback class or function with this signature. 
+
+For each output packet the libary calls the registered function,  providing the byte index into the raw trace for the first 
+byte of the trace protocol packet that resulted in its generation, plus the CoreSight trace ID of the source stream, 
+#and the output packet itself.
+
+The client callback must process the packet before returning the call - the reference to the packet data is only 
+valid for the duration of the call. This means that the client will either have to copy and buffer packets for later
+processing if required, process immediately, or use an appropriate combination, dependent on the requirements of the
+client.
+
+The client callback provides a ocsd_datapath_resp_t response code to indicate to the input side of the library if decoding is to continue.
+
+~~~{.cpp}
+	DecodeTree *pTree;
+	TrcGenericElementPrinter genElemPrinter; // derived from ITrcGenElemIn, overrides TraceElemIn() to print incoming packet to logger.
+	
+	///...
+	
+	pTree->setGenTraceElemOutI(genElemPrinter);
+	
+~~~
+
+Alternatively in C-API, the callback function pointer type is defined:-
+
+~~~{.c}
+	typedef ocsd_datapath_resp_t (* FnTraceElemIn)( const void *p_context, 
+													const ocsd_trc_index_t index_sop, 
+													const uint8_t trc_chan_id, 
+													const ocsd_generic_trace_elem *elem); 	
+~~~
+
+giving API calls to set up:-
+
+~~~{.c}
+	FnTraceElemIn gen_pkt_fn = &gen_trace_elem_analyze; // set to function matching signature.
+	dcd_tree_handle_t dcdtree_handle;
+	
+	// ...
+	
+	ret = ocsd_dt_set_gen_elem_outfn(dcdtree_handle, gen_pkt_fn, 0);
+~~~
+
+The output packets and their intepretatation are described here [prog_guide_generic_pkts.md](@ref generic_pkts).
+
+__Packet Process only, or Monitor packets in Full Decode__
+
+The client can set up the library for packet processing only, in which case the library output is 
+the trace packets only, so these packets need a sink callback for each channel being output.
+
+When full decode is in operation, then the principle output is the generic packets that are output for
+all channels in operation to the single callback mentioned above. Additional callbacks can be added to 
+each of the trace channels to monitor the packet processing stage as it happens at point that the packets 
+are passed to the full decoder.
+
+Both methods of processing the discrete trace packets require callbacks to be registered on a 
+per Trace ID / channel basis. The specifics of the callback and the resulting packet will vary according to 
+the protocol of the trace source.
+
+The .cpp interface registers a packet sink / packet monitor object with the relevant decoder object. 
+
+This sink object is based on the tempated IPktDataIn interface.
+
+~~~{.cpp}
+template<class P> class IPktDataIn : public ITrcTypedBase {
+	// ...
+	    virtual ocsd_datapath_resp_t PacketDataIn( const ocsd_datapath_op_t op,
+                                                const ocsd_trc_index_t index_sop,
+                                                const P *p_packet_in) = 0;
+}
+~~~
+
+The template type parameter will be the protocol type for the trace source in question - e.g. EtmV4ITrcPacket.
+This interface contains a method that will be called with trace packets. 
+
+The monitor object must be based on the IPktRawDataMon class, with a similarly typed template parameter and callback
+function. 
+
+~~~{.cpp}
+template<class P> class IPktRawDataMon : public ITrcTypedBase {
+	// ...
+	    virtual void RawPacketDataMon( const ocsd_datapath_op_t op,
+                                   const ocsd_trc_index_t index_sop,
+                                   const P *pkt,
+                                   const uint32_t size,
+                                   const uint8_t *p_data) = 0;
+}
+~~~
+
+Given a suitable callback object the process for attaching to the decode is as follows:-
+
+~~~{.cpp}
+	// client custom packet sink for ETMv4 - derived from IPktDataIn 
+	class MyTracePacketSinkETMv4 : public IPktDataIn<EtmV4ITrcPacket> {
+		// ...
+	};
+
+	uint8_t CSID;	
+	DecodeTree *pTree;	// pointer to decode tree
+    MyTracePacketSinkETMv4 *pSink;     
+ 
+	// ... obtain CSID and decode tree object
+ 
+	// decode trees manage decode elements using a tree element object, registered against CSID.
+    DecodeTreeElement *pElement = pTree->getDecoderElement(CSID);
+	pSink = new MyTracePacketSinkETMv4();
+	if (pElement && pSink)
+		err = pElement->getDecoderMngr()->attachPktSink(pElement->getDecoderHandle(), pSink);
+            
+~~~
+
+The decode tree object is used to obtain the decode tree element associated with the Coresight trace ID. 
+The IDecoderMngr interface on this object is used to attach the packet sink object to the required decoder.
+
+For monitor objects use an attachPktMonitor() call with a suitably derived monitor sink object.
+
+The key difference between the packet sink, and the packet monitor is that the monitor is not in the trace decode 
+data path, so does not return ocsd_datapath_resp_t values. The monitor callback also provides the raw trace byte 
+data for the packet.
+
+Device tree call for registering a callback in C-API and the function signatures for each type of shown below..
+The C-API code contains underlying managment code that connects the callback with the correct packet decoder object.
+
+~~~{.c}
+OCSD_C_API ocsd_err_t ocsd_dt_attach_packet_callback(  const dcd_tree_handle_t handle,    // decode tree handle
+                                                const unsigned char CSID,				  // trace channel ID
+                                                const ocsd_c_api_cb_types callback_type,  // defines packet only processing sink or monitor function signature.
+                                                void *p_fn_callback_data,                 // pointer to the callback function for the packet data.
+                                                const void *p_context);				      // opaque context to use inside the callback.
+~~~
+
+Callback definition for packet only sink callback type:
+~~~{.c}
+/** function pointer type for packet processor packet output sink, packet analyser/decoder input - generic declaration */
+typedef ocsd_datapath_resp_t (* FnDefPktDataIn)(const void *p_context, 
+                                                const ocsd_datapath_op_t op, 
+                                                const ocsd_trc_index_t index_sop, 
+                                                const void *p_packet_in
+												);
+~~~
+
+Callback  definition for packet monitor callback type
+~~~{.c}
+/** function pointer type for packet processor packet monitor sink, raw packet monitor / display input - generic declaration */
+typedef void (* FnDefPktDataMon)(const void *p_context,
+                                 const ocsd_datapath_op_t op,
+                                 const ocsd_trc_index_t index_sop,
+                                 const void *p_packet_in,
+                                 const uint32_t size,
+                                 const uint8_t *p_data
+								 );
+~~~
+
+As with the `.cpp` code, the monitor callback does not have a return value, but also has the raw trace bytes for the packet as part of
+the monitor.
+
+In both cases in the C-API, the `void *p_packet_in` must be cast to packet structure appropriate to the trace protocol associated with the 
+CSID value. e.g. for ETMv4 this would be @ref ocsd_etmv4_i_pkt. 
+
+
+Programming Examples - using the configured Decode Tree.
+--------------------------------------------------------
+ 
+Once the decode tree has been configured then data raw trace data can be processed through the decode tree.
+
+The client program will require two functions to use the library. The first is on the input side of the library 
+which must be driven with raw data, until the data is complete, or an error occurs. This processing routine must 
+check the library returns and respond appropriately.
+
+The second consists of output callback(s) which process the decoded generic packets, or trace packets. 
+This routine will return response codes according to the needs of the client.
+
+![Trace Data call and response path](decode_data_path_resp.jpg)
+ 
+The diagram shows the data input and response path. The data is driven into the decoding library by the client raw data input 
+routine on the left. Processed packets are received by the client packet callback(s) on the right, and push response codes back
+through the library.
+
+The raw data input routine calls the standard ITrcDataIn interface with an operation code, and if appropriate some raw 
+trace data. The input operation code will define how the library treats the input parameters.
+
+
+| Operation          | Description                                                      | Trace Data provided |
+|:-------------------|:-----------------------------------------------------------------|:--------------------|
+| @ref OCSD_OP_DATA  | Process data provided by data pointer parameters.                | Yes                 |
+| @ref OCSD_OP_FLUSH | Call after prior wait response - finish processing previous data | No                  |
+| @ref OCSD_OP_EOT   | End of trace data. Library will complete any pending decode.     | No                  |
+| @ref OCSD_OP_RESET | Hard reset of decoder state - use current config for new data    | No                  |
+
+A set of standard responses is used to indicate to the raw data input whether it should continue to push data through the library, 
+pause and then flush, or if a fatal processing error has occurred. 
+
+The response codes can come from the internal library decoder, or from the part of the client that is handling the processing of the 
+output packets on the right of the diagram. 
+
+_Response Codes_: The are contained in the @ref _ocsd_datapath_resp_t enum.
+
+- __OCSD_RESP_CONT, OCSD_RESP_CONT_xxx__: 	Indicates that processing is to continue. Generated either internally by the library if more data 
+										is needed to generate an output packet, or by the output packet processors to indicate processing 
+										is to continue.
+- __OCSD_RESP_WAIT, OCSD_RESP_WAIT_xxx:__   Sent by the client processors to pause processing. This will freeze the internal state of the library
+									    and cause the WAIT response to be propogated through to the input side, with an indication of the number
+									    of bytes processed. After a WAIT, the input side must respond with flush operations, until a CONT is 
+										seen again and further data can then be input into the library.
+- __OCSR_RESP_FATAL_xxx__:                  Fatal processing error. No further processing can take place. See error response logger for reason.
+                                        Normally the result of corrupt or incorrect trace data.
+
+The user should note that the client program controls routines on both the input and output side of the library. The output routine may be buffering 
+output packets, and when the buffer is full, returns a WAIT ressponse. This will be propgated through to the input routine. This should now terminate
+data processing, saving state and the client will run a routine to empty / process the full packet buffer. Once the necessary processing is done, 
+then the input routine can be restarted, but __must__ follow the FLUSH operational rule described above.
+
+Excerpts from the data input routine used by the `trc_pkt_lister` program are shown below:
+
+~~~{.cpp}
+                   // process the current buffer load until buffer done, or fatal error occurs
+                    while((nBuffProcessed < nBuffRead) && !OCSD_DATA_RESP_IS_FATAL(dataPathResp))
+                    {
+                        if(OCSD_DATA_RESP_IS_CONT(dataPathResp))
+                        {
+                            dataPathResp = dcd_tree->TraceDataIn(
+                                OCSD_OP_DATA,
+                                trace_index,
+                                (uint32_t)(nBuffRead - nBuffProcessed),
+                                &(trace_buffer[0])+nBuffProcessed,
+                                &nUsedThisTime);
+
+                            nBuffProcessed += nUsedThisTime;
+                            trace_index += nUsedThisTime;
+
+                        }
+                        else // last response was _WAIT
+                        {
+                            // may need to acknowledge a wait from the gen elem printer
+                            if(genElemPrinter->needAckWait())
+                                genElemPrinter->ackWait();
+
+                            // dataPathResp not continue or fatal so must be wait...
+                            dataPathResp = dcd_tree->TraceDataIn(OCSD_OP_FLUSH,0,0,0,0);
+                        }
+                    }
+					
+~~~
+
+_Note_: in this test program, the WAIT response is an artificial test condition, so the input routine does not terminate on seeing it - it is cleared down
+and FLUSH is immediately sent. Normal client routines would most likely drop out of the processing loop, take actions to clear the WAIT condition, then
+resume processing with a FLUSH.
+
+See the `trc_pkt_lister` and `c_api_pkt_print_test` test program source code for further examples of driving data through the library.