Adding upstream version 1.3.3.upstream/1.3.3upstream

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

5 files changed, 1122 insertions, 0 deletions

diff --git a/decoder/include/opencsd/c_api/ocsd_c_api_cust_fact.h b/decoder/include/opencsd/c_api/ocsd_c_api_cust_fact.h
new file mode 100644
index 0000000..f9e6a95
--- /dev/null
+++ b/decoder/include/opencsd/c_api/ocsd_c_api_cust_fact.h
@@ -0,0 +1,54 @@
+/*
+* \file       ocsd_c_api_cust_fact.h
+* \brief      OpenCSD : Custom decoder factory API functions
+*
+* \copyright  Copyright (c) 2016, ARM Limited. All Rights Reserved.
+*/
+
+/*
+* Redistribution and use in source and binary forms, with or without modification,
+* are permitted provided that the following conditions are met:
+*
+* 1. Redistributions of source code must retain the above copyright notice,
+* this list of conditions and the following disclaimer.
+*
+* 2. Redistributions in binary form must reproduce the above copyright notice,
+* this list of conditions and the following disclaimer in the documentation
+* and/or other materials provided with the distribution.
+*
+* 3. Neither the name of the copyright holder nor the names of its contributors
+* may be used to endorse or promote products derived from this software without
+* specific prior written permission.
+*
+* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND
+* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+* IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+#ifndef ARM_OCSD_C_API_CUST_FACT_H_INCLUDED
+#define ARM_OCSD_C_API_CUST_FACT_H_INCLUDED
+
+#include "ocsd_c_api_types.h"
+#include "ocsd_c_api_custom.h"
+
+/* Declarations for the functions implemented in the custom decoder factory. */
+
+/** Required function to create a decoder instance - fills in the decoder struct supplied. */
+ocsd_err_t CreateCustomDecoder(const int create_flags, const void *decoder_cfg, ocsd_extern_dcd_inst_t *p_decoder_inst);
+
+/** Required Function to destroy a decoder instance - indicated by decoder handle */
+ocsd_err_t DestroyCustomDecoder(const void *decoder_handle);
+
+/** Required Function to extract the CoreSight Trace ID from the configuration structure */
+ocsd_err_t GetCSIDFromConfig(const void *decoder_cfg, unsigned char *p_csid);
+
+/** Optional Function to convert a protocol specific trace packet to human readable string */
+ocsd_err_t PacketToString(const void *trc_pkt, char *buffer, const int buflen);
+
+#endif /* ARM_OCSD_C_API_CUST_FACT_H_INCLUDED */
diff --git a/decoder/include/opencsd/c_api/ocsd_c_api_cust_impl.h b/decoder/include/opencsd/c_api/ocsd_c_api_cust_impl.h
new file mode 100644
index 0000000..245ce16
--- /dev/null
+++ b/decoder/include/opencsd/c_api/ocsd_c_api_cust_impl.h
@@ -0,0 +1,158 @@
+/*
+* \file       ocsd_c_api_cust_impl.h
+* \brief      OpenCSD : Custom decoder implementation common API definitions
+*
+* \copyright  Copyright (c) 2016, ARM Limited. All Rights Reserved.
+*/
+
+/*
+* Redistribution and use in source and binary forms, with or without modification,
+* are permitted provided that the following conditions are met:
+*
+* 1. Redistributions of source code must retain the above copyright notice,
+* this list of conditions and the following disclaimer.
+*
+* 2. Redistributions in binary form must reproduce the above copyright notice,
+* this list of conditions and the following disclaimer in the documentation
+* and/or other materials provided with the distribution.
+*
+* 3. Neither the name of the copyright holder nor the names of its contributors
+* may be used to endorse or promote products derived from this software without
+* specific prior written permission.
+*
+* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND
+* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+* IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+#ifndef ARM_OCSD_C_API_CUST_IMPL_H_INCLUDED
+#define ARM_OCSD_C_API_CUST_IMPL_H_INCLUDED
+
+#include "opencsd/c_api/ocsd_c_api_types.h"
+#include "opencsd/c_api/ocsd_c_api_custom.h"
+
+/** @addtogroup ocsd_ext_dcd
+@{*/
+
+/**@name External decoder - Inline utility functions.
+   @brief inline functions used in decoders to call the various library callback functionality.
+
+   Functions manipulate and use the ocsd_extern_dcd_cb_fns structure to call into the library, 
+   with appropriate checking for initialisation and usage flags.
+
+@{*/
+
+static inline ocsd_datapath_resp_t lib_cb_GenElemOp(const ocsd_extern_dcd_cb_fns *callbacks,
+    const ocsd_trc_index_t index_sop,
+    const uint8_t trc_chan_id,
+    const ocsd_generic_trace_elem *elem)
+{
+    if (callbacks->fn_gen_elem_out)
+        return callbacks->fn_gen_elem_out(callbacks->lib_context, index_sop, trc_chan_id, elem);
+    return OCSD_RESP_FATAL_NOT_INIT;
+}
+
+static inline ocsd_err_t lib_cb_LogError(const ocsd_extern_dcd_cb_fns *callbacks,
+    const ocsd_err_severity_t filter_level,
+    const ocsd_err_t code,
+    const ocsd_trc_index_t idx,
+    const uint8_t chan_id,
+    const char *pMsg)
+{
+    if (callbacks->fn_log_error)
+    {
+        callbacks->fn_log_error(callbacks->lib_context, filter_level, code, idx, chan_id, pMsg);
+        return OCSD_OK;
+    }
+    return OCSD_ERR_NOT_INIT;
+}
+
+static inline ocsd_err_t lib_cb_LogMsg(const ocsd_extern_dcd_cb_fns *callbacks,
+    const ocsd_err_severity_t filter_level,
+    const char *pMsg)
+{
+    if (callbacks->fn_log_msg)
+    {
+        callbacks->fn_log_msg(callbacks->lib_context, filter_level, pMsg);
+        return OCSD_OK;
+    }
+    return OCSD_ERR_NOT_INIT;
+}
+
+static inline ocsd_err_t lib_cb_DecodeArmInst(const ocsd_extern_dcd_cb_fns *callbacks,
+    ocsd_instr_info *instr_info)
+{
+    if (callbacks->fn_arm_instruction_decode)
+        return callbacks->fn_arm_instruction_decode(callbacks->lib_context, instr_info);
+    return OCSD_ERR_NOT_INIT;
+}
+
+static inline ocsd_err_t lib_cb_MemAccess(const ocsd_extern_dcd_cb_fns *callbacks,
+    const ocsd_vaddr_t address,
+    const uint8_t cs_trace_id,
+    const ocsd_mem_space_acc_t mem_space,
+    uint32_t *num_bytes,
+    uint8_t *p_buffer)
+{
+    if (callbacks->fn_memory_access)
+        return callbacks->fn_memory_access(callbacks->lib_context, address, cs_trace_id, mem_space, num_bytes, p_buffer);
+    return OCSD_ERR_NOT_INIT;
+}
+
+static inline void lib_cb_PktMon(const ocsd_extern_dcd_cb_fns *callbacks,
+    const ocsd_datapath_op_t op,
+    const ocsd_trc_index_t index_sop,
+    const void *pkt,
+    const uint32_t size,
+    const uint8_t *p_data)
+{
+    if (callbacks->packetCBFlags & OCSD_CUST_DCD_PKT_CB_USE_MON)
+    {
+        if (callbacks->fn_packet_mon)
+            callbacks->fn_packet_mon(callbacks->lib_context, op, index_sop, pkt, size, p_data);
+    }
+}
+
+static inline int lib_cb_usePktMon(const ocsd_extern_dcd_cb_fns *callbacks)
+{
+    return (callbacks->packetCBFlags & OCSD_CUST_DCD_PKT_CB_USE_MON);
+}
+
+/* callback function to connect to the packet sink interface, on the main decode
+data path - used if decoder created as packet processor only */
+static inline ocsd_datapath_resp_t lib_cb_PktDataSink(const ocsd_extern_dcd_cb_fns *callbacks,
+    const ocsd_datapath_op_t op,
+    const ocsd_trc_index_t index_sop,
+    const void *pkt)
+{
+    if (callbacks->packetCBFlags & OCSD_CUST_DCD_PKT_CB_USE_SINK)
+    {
+        if (callbacks->fn_packet_data_sink)
+            return callbacks->fn_packet_data_sink(callbacks->lib_context, op, index_sop, pkt);
+        else
+            return OCSD_RESP_FATAL_NOT_INIT;
+    }
+    return OCSD_RESP_CONT;
+}
+
+static inline int lib_cb_usePktSink(const ocsd_extern_dcd_cb_fns *callbacks)
+{
+    return (callbacks->packetCBFlags & OCSD_CUST_DCD_PKT_CB_USE_SINK);
+}
+
+static inline void lib_cb_updatePktCBFlags(ocsd_extern_dcd_cb_fns *callbacks, const int newFlags)
+{
+    callbacks->packetCBFlags = newFlags;
+}
+
+/** @}*/
+
+/** @}*/
+
+#endif /* ARM_OCSD_C_API_CUST_IMPL_H_INCLUDED */
diff --git a/decoder/include/opencsd/c_api/ocsd_c_api_custom.h b/decoder/include/opencsd/c_api/ocsd_c_api_custom.h
new file mode 100644
index 0000000..ada0a68
--- /dev/null
+++ b/decoder/include/opencsd/c_api/ocsd_c_api_custom.h
@@ -0,0 +1,253 @@
+/*
+ * \file       ocsd_c_api_custom.h
+ * \brief      OpenCSD : Custom decoder interface types and structures
+ * 
+ * \copyright  Copyright (c) 2016, ARM Limited. All Rights Reserved.
+ */
+
+/* 
+ * Redistribution and use in source and binary forms, with or without modification, 
+ * are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice, 
+ * this list of conditions and the following disclaimer.
+ * 
+ * 2. Redistributions in binary form must reproduce the above copyright notice, 
+ * this list of conditions and the following disclaimer in the documentation 
+ * and/or other materials provided with the distribution. 
+ * 
+ * 3. Neither the name of the copyright holder nor the names of its contributors 
+ * may be used to endorse or promote products derived from this software without 
+ * specific prior written permission. 
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND 
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
+ * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
+ * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
+ */ 
+#ifndef ARM_OCSD_C_API_CUSTOM_H_INCLUDED
+#define ARM_OCSD_C_API_CUSTOM_H_INCLUDED
+
+#include "ocsd_c_api_types.h"
+
+
+ /** @defgroup ocsd_ext_dcd OpenCSD Library : Custom External Decoder C-API
+ @brief Set of types, structures and interfaces for attaching custom decoders via the C-API
+
+ These types, functions and structures define the required API between a custom external decoder
+ and the library, which will allow the decoder to interact with the library and use library 
+ resources in the same way as the built-in decoders.
+
+ The external decoder must implement:-
+ - A set of factory functions that allow the creation and destruction of decoder instances.
+ - A set of call-in and call-back functions plus data structures allowing interaction with the library.
+ 
+ @{*/
+
+
+/**@name External decoder - Input Interfaces 
+@{*/
+
+/* Custom decoder C-API interface types. */
+
+/** Raw trace data input function - a decoder must have one of these 
+    Implements ITrcDataIn with the addition of a decoder handle to provide context in the decoder.
+ */
+typedef ocsd_datapath_resp_t (* fnTraceDataIn)( const void *decoder_handle, 
+                                                const ocsd_datapath_op_t op,
+                                                const ocsd_trc_index_t index,
+                                                const uint32_t dataBlockSize,
+                                                const uint8_t *pDataBlock,
+                                                uint32_t *numBytesProcessed);
+
+/** Function to update the in-use flags for the packet sinks
+
+    Defines if the fnPktMonCB or fnPktDataSinkCB callbacks are in use by the library.
+    If so then it is expected that the decoder should call them when trace protocol packets are generated.
+
+    This function must be implemented in the decoder.
+
+    @param decoder_handle : handle for decoder accessed by this call.
+    @param flags: Values indicating interfaces in use / not in use. [ OCSD_CUST_DCD_PKT_CB_USE_MON or  OCSD_CUST_DCD_PKT_CB_USE_SINK]
+*/
+typedef void (* fnUpdatePktMonFlags)(const void *decoder_handle, const int flags);
+
+
+
+/** Flag to indicate the the packet monitor (fnPktMonCB) is in use in the library */
+#define OCSD_CUST_DCD_PKT_CB_USE_MON  0x1
+
+/** Flag to indicate the the packet sink (fnPktDataSinkCB) is in use in the library - only if trace packet processing only mode. */
+#define OCSD_CUST_DCD_PKT_CB_USE_SINK 0x2
+
+/** Owned by the library instance object, this structure is filled in by the ocsd_extern_dcd_fact_t createDecoder() function. */
+typedef struct _ocsd_extern_dcd_inst {
+    /* Mandatory decoder call back functions - library initialisation will fail without these. */
+    fnTraceDataIn       fn_data_in;         /**< raw trace data input function to decoder */
+    fnUpdatePktMonFlags fn_update_pkt_mon;  /**< update the packet monitor / sink usage flags */
+
+                                            /* Decoder instance data */
+    void *decoder_handle;   /**< Instance handle for the decoder  - used by library to call the decoder call in functions */
+    char *p_decoder_name;   /**< type name of the decoder - may be used in logging */
+    uint8_t cs_id;          /**< Coresight ID for the instance - extracted from the config on creation. */
+
+} ocsd_extern_dcd_inst_t;
+
+/** @}*/
+
+
+/**@name External decoder - Callback Interfaces
+@{*/
+
+
+/** callback function to connect into the generic element output point 
+  Implements ITrcGenElemIn::TraceElemIn with addition of library context pointer.
+  */
+typedef ocsd_datapath_resp_t (* fnGenElemOpCB)( const void *lib_context,
+                                                const ocsd_trc_index_t index_sop, 
+                                                const uint8_t trc_chan_id, 
+                                                const ocsd_generic_trace_elem *elem); 
+ 
+/** callback functions to connect into the library error logging mechanism
+    Implements ITraceErrorLog::LogError with addition of library context pointer.
+*/
+typedef void (* fnLogErrorCB)(  const void *lib_context, 
+                                const ocsd_err_severity_t filter_level, 
+                                const ocsd_err_t code, 
+                                const ocsd_trc_index_t idx, 
+                                const uint8_t chan_id, 
+                                const char *pMsg);
+
+/** callback functions to connect into the library error logging mechanism
+    Implements ITraceErrorLog::LogMessage with addition of library context pointer.
+*/
+typedef void (* fnLogMsgCB)(const void *lib_context, const ocsd_err_severity_t filter_level, const char *msg);
+
+/** callback function to connect an ARM instruction decoder
+    Implements IInstrDecode::DecodeInstruction with addition of library context pointer.
+*/
+typedef ocsd_err_t (* fnDecodeArmInstCB)(const void *lib_context, ocsd_instr_info *instr_info);
+
+/** callback function to connect the memory accessor interface 
+    Implements ITargetMemAccess::ReadTargetMemory with addition of library context pointer.
+*/
+typedef ocsd_err_t (* fnMemAccessCB)(const void *lib_context,
+                                     const ocsd_vaddr_t address, 
+                                     const uint8_t cs_trace_id, 
+                                     const ocsd_mem_space_acc_t mem_space, 
+                                     uint32_t *num_bytes, 
+                                     uint8_t *p_buffer);
+
+/** callback function to connect to the packet monitor interface of the packet processor 
+    Implements IPktRawDataMon::RawPacketDataMon <void> with addition of library context pointer.
+*/
+typedef void (* fnPktMonCB)(  const void *lib_context,
+                              const ocsd_datapath_op_t op,
+                              const ocsd_trc_index_t index_sop,
+                              const void *pkt,
+                              const uint32_t size,
+                              const uint8_t *p_data);
+
+/** callback function to connect to the packet sink interface, on the main decode 
+    data path - use if decoder created as packet processor only 
+    
+    Implements IPktDataIn::PacketDataIn <void> with addition of library context pointer.
+*/
+typedef ocsd_datapath_resp_t (* fnPktDataSinkCB)( const void *lib_context,
+                                                  const ocsd_datapath_op_t op,
+                                                  const ocsd_trc_index_t index_sop,
+                                                  const void *pkt);
+
+/** an instance of this is owned by the decoder, filled in by the library - allows the CB fns in the library decode tree to be called. */
+typedef struct _ocsd_extern_dcd_cb_fns {
+/* Callback functions */
+    fnGenElemOpCB       fn_gen_elem_out;            /**< Callback to output a generic element. */
+    fnLogErrorCB        fn_log_error;               /**< Callback to output an error.  */
+    fnLogMsgCB          fn_log_msg;                 /**< Callback to output a message. */
+    fnDecodeArmInstCB   fn_arm_instruction_decode;  /**< Callback to decode an ARM instruction. */
+    fnMemAccessCB       fn_memory_access;           /**< Callback to access memory images related to the trace capture. */
+    fnPktMonCB          fn_packet_mon;              /**< Callback to output trace packet to packet monitor. */
+    fnPktDataSinkCB     fn_packet_data_sink;        /**< Callback to output trace packet to packet sink - if in pack processing only mode. */
+/* CB in use flags. */
+    int packetCBFlags;  /**< Flags to indicate if the packet sink / packet monitor callbacks are in use. ( OCSD_CUST_DCD_PKT_CB_USE_MON / OCSD_CUST_DCD_PKT_CB_USE_SINK) */
+/* library context */
+    const void *lib_context;  /**< library context pointer - use in callbacks to allow the library to load the correct context data. */
+} ocsd_extern_dcd_cb_fns;
+
+/** @}*/
+
+/**@name External decoder - Decoder Factory
+@{*/
+
+/** Function to create a decoder instance
+
+    Create a decoder instance according to the create_flags parameter and the supplied decoder_cfg structure.
+    Fill in the p_decoder_inst structure, copy the p_lib_callbacks information for use in the decoder instance.
+
+    Create flags can be:
+    - OCSD_CREATE_FLG_PACKET_PROC: decoder will split the incoming trace into trace protocol packets and not further decode them. fnPktDataSinkCB likely to be in use.
+    - OCSD_CREATE_FLG_FULL_DECODER: decoder will split the incoming trace into trace protocol packets and further decode them to recreate program flow or other generic trace output.
+
+    @param create_flags : Sets the decoder operating mode.
+    @param *decoder_cfg : Hardware specific configuration for this trace element. 
+    @param *p_lib_callbacks : Library callbacks plus context pointer.
+    @param *p_decoder_inst : Structure representing the new decoder instance being created. Filled in by create function to contain handle and call-in functions for the library.
+
+    @return ocsd_err_t  : Library error code -  RCDTL_OK if successful
+*/
+typedef ocsd_err_t (* fnCreateCustomDecoder)(const int create_flags, const void *decoder_cfg, const ocsd_extern_dcd_cb_fns *p_lib_callbacks, ocsd_extern_dcd_inst_t *p_decoder_inst);
+
+/** Function to destroy a decoder instance indicated by decoder handle.
+
+    @param decoder_handle : Instance handle for decoder.
+
+    @return ocsd_err_t  : Library error code -  RCDTL_OK if successful
+*/
+typedef ocsd_err_t (* fnDestroyCustomDecoder)(const void *decoder_handle);
+
+/** Function to extract the CoreSight Trace ID from the configuration structure.
+
+    @param *decoder_cfg : Hardware specific configuration for this trace element.
+    @parma *p_csid : location to write CoreSight Trace ID value.
+
+    @return ocsd_err_t  : Library error code -  RCDTL_OK if successful
+*/
+typedef ocsd_err_t (* fnGetCSIDFromConfig)(const void *decoder_cfg, unsigned char *p_csid);
+
+/** Function to convert a protocol specific trace packet to human readable string 
+
+    @param *trc_pkt : protocol specific packet structure.
+    @param *buffer  : buffer to fill with string.
+    @param  buflen  : length of string buffer.
+
+    @return ocsd_err_t  : Library error code -  RCDTL_OK if successful
+*/
+typedef ocsd_err_t (* fnPacketToString)(const void *trc_pkt, char *buffer, const int buflen);
+
+/** set of functions and callbacks to create an extern custom decoder in the library 
+    via the C API interface. This structure is registered with the library by name and 
+    then decoders of the type can be created on the decode tree.    
+*/
+typedef struct _ocsd_extern_dcd_fact {
+    fnCreateCustomDecoder createDecoder;    /**< Function pointer to create a decoder instance. */
+    fnDestroyCustomDecoder destroyDecoder;  /**< Function pointer to destroy a decoder instance. */
+    fnGetCSIDFromConfig csidFromConfig;     /**< Function pointer to extract the CSID from a config structure */
+    fnPacketToString pktToString;           /**< Function pointer to print a trace protocol packet in this decoder */
+
+    ocsd_trace_protocol_t protocol_id;  /**< protocol ID assigned during registration. */
+} ocsd_extern_dcd_fact_t; 
+
+/** @}*/
+
+/** @}*/
+
+
+#endif // ARM_OCSD_C_API_CUSTOM_H_INCLUDED
+
+/* End of File ocsd_c_api_custom.h */
diff --git a/decoder/include/opencsd/c_api/ocsd_c_api_types.h b/decoder/include/opencsd/c_api/ocsd_c_api_types.h
new file mode 100644
index 0000000..7f9b4ba
--- /dev/null
+++ b/decoder/include/opencsd/c_api/ocsd_c_api_types.h
@@ -0,0 +1,107 @@
+/*!
+ * \file       ocsd_c_api_types.h
+ * \brief      OpenCSD : Trace Decoder "C" API types.
+ * 
+ * \copyright  Copyright (c) 2015, ARM Limited. All Rights Reserved.
+ */
+
+/* 
+ * Redistribution and use in source and binary forms, with or without modification, 
+ * are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice, 
+ * this list of conditions and the following disclaimer.
+ * 
+ * 2. Redistributions in binary form must reproduce the above copyright notice, 
+ * this list of conditions and the following disclaimer in the documentation 
+ * and/or other materials provided with the distribution. 
+ * 
+ * 3. Neither the name of the copyright holder nor the names of its contributors 
+ * may be used to endorse or promote products derived from this software without 
+ * specific prior written permission. 
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND 
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
+ * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
+ * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
+ */ 
+
+#ifndef ARM_OCSD_C_API_TYPES_H_INCLUDED
+#define ARM_OCSD_C_API_TYPES_H_INCLUDED
+
+/* select the library types that are C compatible - the interface data types */
+#include "opencsd/ocsd_if_types.h"
+#include "opencsd/ocsd_if_version.h"
+#include "opencsd/trc_gen_elem_types.h"
+#include "opencsd/trc_pkt_types.h"
+
+/* pull in the protocol decoder types. */
+#include "opencsd/etmv3/trc_pkt_types_etmv3.h"
+#include "opencsd/etmv4/trc_pkt_types_etmv4.h"
+#include "opencsd/ptm/trc_pkt_types_ptm.h"
+#include "opencsd/stm/trc_pkt_types_stm.h"
+#include "opencsd/ete/trc_pkt_types_ete.h"
+
+/** @ingroup lib_c_api
+@{*/
+
+
+/* Specific C-API only types */
+
+/** Handle to decode tree */
+typedef void * dcd_tree_handle_t;
+
+/** define invalid handle value for decode tree handle */
+#define C_API_INVALID_TREE_HANDLE (dcd_tree_handle_t)0
+
+/** Logger output printer - no output. */
+#define C_API_MSGLOGOUT_FLG_NONE   0x0
+/** Logger output printer - output to file. */
+#define C_API_MSGLOGOUT_FLG_FILE   0x1
+/** Logger output printer - output to stderr. */
+#define C_API_MSGLOGOUT_FLG_STDERR 0x2
+/** Logger output printer - output to stdout. */
+#define C_API_MSGLOGOUT_FLG_STDOUT 0x4
+/** Logger output printer - mask of valid flags. */
+#define C_API_MSGLOGOUT_MASK       0x7
+
+/** 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); 
+
+/** 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);
+
+/** 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);
+
+/** function pointer tyee for library default logger output to allow client to print zero terminated output string */
+typedef void (* FnDefLoggerPrintStrCB)(const void *p_context, const char *psz_msg_str, const int str_len);
+
+/** Callback interface type when attaching monitor/sink to packet processor */
+typedef enum _ocsd_c_api_cb_types {
+    OCSD_C_API_CB_PKT_SINK, /** Attach to the packet processor primary packet output (CB fn is FnDefPktDataIn) */
+    OCSD_C_API_CB_PKT_MON,  /** Attach to the packet processor packet monitor output (CB fn is FnDefPktDataMon) */
+} ocsd_c_api_cb_types;
+
+/** @}*/
+
+#endif // ARM_OCSD_C_API_TYPES_H_INCLUDED
+
+/* End of File ocsd_c_api_types.h */
diff --git a/decoder/include/opencsd/c_api/opencsd_c_api.h b/decoder/include/opencsd/c_api/opencsd_c_api.h
new file mode 100644
index 0000000..ebbba87
--- /dev/null
+++ b/decoder/include/opencsd/c_api/opencsd_c_api.h
@@ -0,0 +1,550 @@
+/*!
+ * \file       opencsd_c_api.h
+ * \brief      OpenCSD : "C" API
+ * 
+ * \copyright  Copyright (c) 2015, ARM Limited. All Rights Reserved.
+ */
+
+/* 
+ * Redistribution and use in source and binary forms, with or without modification, 
+ * are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, 
+ * this list of conditions and the following disclaimer.
+ * 
+ * 2. Redistributions in binary form must reproduce the above copyright notice, 
+ * this list of conditions and the following disclaimer in the documentation 
+ * and/or other materials provided with the distribution.
+ * 
+ * 3. Neither the name of the copyright holder nor the names of its contributors 
+ * may be used to endorse or promote products derived from this software without 
+ * specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
+ * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
+ * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef ARM_OPENCSD_C_API_H_INCLUDED
+#define ARM_OPENCSD_C_API_H_INCLUDED
+
+/** @defgroup lib_c_api OpenCSD Library : Library "C" API.
+    @brief  "C" API for the OpenCSD Library
+
+    Set of "C" wrapper functions for the OpenCSD library.
+
+    Defines API, functions and callback types.
+@{*/
+
+/* ensure C bindings */
+
+#if defined(WIN32)  /* windows bindings */
+    /** Building the C-API DLL **/
+    #ifdef _OCSD_C_API_DLL_EXPORT
+        #ifdef __cplusplus
+            #define OCSD_C_API extern "C" __declspec(dllexport)
+        #else
+            #define OCSD_C_API __declspec(dllexport)
+        #endif
+    #else   
+        /** building or using the static C-API library **/
+        #if defined(_LIB) || defined(OCSD_USE_STATIC_C_API)
+            #ifdef __cplusplus
+                #define OCSD_C_API extern "C"
+            #else
+                #define OCSD_C_API
+            #endif
+        #else
+        /** using the C-API DLL **/
+            #ifdef __cplusplus
+                #define OCSD_C_API extern "C" __declspec(dllimport)
+            #else
+                #define OCSD_C_API __declspec(dllimport)
+            #endif
+        #endif
+    #endif
+#else           /* linux bindings */
+    #ifdef __cplusplus
+        #define OCSD_C_API extern "C"
+    #else
+        #define OCSD_C_API
+    #endif
+#endif
+
+#include "ocsd_c_api_types.h"
+#include "ocsd_c_api_custom.h"
+
+/** @name Library Version API
+
+@{*/
+/** Get Library version. Return a 32 bit version in form MMMMnnpp - MMMM = major version, nn = minor version, pp = patch version */
+OCSD_C_API uint32_t ocsd_get_version(void);
+
+/** Get library version string */
+OCSD_C_API const char * ocsd_get_version_str(void);
+/** @}*/
+
+/*---------------------- Trace Decode Tree ----------------------------------------------------------------------------------*/
+
+/** @name Library Decode Tree API
+@{*/
+
+/*!
+ * Create a decode tree. 
+ *
+ * @param src_type : Type of tree - formatted input, or single source input
+ * @param deformatterCfgFlags : Formatter flags - determine presence of frame syncs etc.
+ *
+ * @return dcd_tree_handle_t  : Handle to the decode tree. Handle value set to 0 if creation failed.
+ */
+OCSD_C_API dcd_tree_handle_t ocsd_create_dcd_tree(const ocsd_dcd_tree_src_t src_type, const uint32_t deformatterCfgFlags);
+
+/*!
+ * Destroy a decode tree.
+ *
+ * Also destroys all the associated processors and decoders for the tree.
+ *
+ * @param handle : Handle for decode tree to destroy.
+ */
+OCSD_C_API void ocsd_destroy_dcd_tree(const dcd_tree_handle_t handle);
+
+/*!
+ * Input trace data into the decoder. 
+ * 
+ * Large trace source buffers can be broken down into smaller fragments.
+ *
+ * @param handle : Handle to decode tree.
+ * @param op : Datapath operation.
+ * @param index : Trace buffer byte index for the start of the supplied data block.
+ * @param dataBlockSize : Size of data block.
+ * @param *pDataBlock : Pointer to data block.
+ * @param *numBytesProcessed : Number of bytes actually processed by the decoder.
+ *
+ * @return ocsd_datapath_resp_t  : Datapath response code (CONT/WAIT/FATAL)
+ */
+OCSD_C_API ocsd_datapath_resp_t ocsd_dt_process_data(const dcd_tree_handle_t handle,
+                                            const ocsd_datapath_op_t op,
+                                            const ocsd_trc_index_t index,
+                                            const uint32_t dataBlockSize,
+                                            const uint8_t *pDataBlock,
+                                            uint32_t *numBytesProcessed);
+
+
+/*---------------------- Generic Trace Element Output  --------------------------------------------------------------*/
+
+/*!
+ * Set the trace element output callback function. 
+ *
+ * This function will be called for each decoded generic trace element generated by 
+ * any full trace decoder in the decode tree.
+ *
+ * A single function is used for all trace source IDs in the decode tree.
+ *
+ * @param handle : Handle to decode tree.
+ * @param pFn : Pointer to the callback function.
+ * @param p_context : opaque context pointer value used in callback function.
+ *
+ * @return  ocsd_err_t  : Library error code -  OCSD_OK if successful.
+ */
+OCSD_C_API ocsd_err_t ocsd_dt_set_gen_elem_outfn(const dcd_tree_handle_t handle, FnTraceElemIn pFn, const void *p_context);
+
+/*---------------------- Trace Decoders ----------------------------------------------------------------------------------*/
+/*!
+* Creates a decoder that is registered with the library under the supplied name.
+* Flags determine if a full packet processor / packet decoder pair or 
+* packet processor only is created.
+* Uses the supplied configuration structure.
+*
+* @param handle : Handle to decode tree.
+* @param *decoder_name : Registered name of the decoder to create. 
+* @param create_flags : Decoder creation options. 
+* @param *decoder_cfg : Pointer to a valid configuration structure for the named decoder.
+* @param *pCSID : Pointer to location to return the configured CoreSight trace ID for the decoder.
+*
+* @return ocsd_err_t  : Library error code -  OCSD_OK if successful.
+*/
+OCSD_C_API ocsd_err_t ocsd_dt_create_decoder(const dcd_tree_handle_t handle,
+                                             const char *decoder_name,
+                                             const int create_flags,
+                                             const void *decoder_cfg,
+                                             unsigned char *pCSID
+                                             );
+
+/*!
+* Remove a decoder from the tree and destroy it.
+*
+* @param handle :  Handle to decode tree.
+* @param CSID : Configured CoreSight trace ID for the decoder.
+*
+* @return ocsd_err_t  : Library error code -  OCSD_OK if successful.
+*/
+OCSD_C_API ocsd_err_t ocsd_dt_remove_decoder(   const dcd_tree_handle_t handle, 
+                                                const unsigned char CSID);
+
+
+/*!
+* Attach a callback function to the packet processor.
+* 
+* The callback_type defines the attachment point, either the main packet output
+* (only if no decoder attached), or the packet monitor.
+* 
+* @param handle : Handle to decode tree.
+* @param CSID : Configured CoreSight trace ID for the decoder.
+* @param callback_type : Attachment point 
+* @param p_fn_pkt_data_in : Pointer to the callback function.
+* @param p_context : Opaque context pointer value used in callback function.
+*
+* @return ocsd_err_t  : Library error code -  OCSD_OK if successful.
+*/
+OCSD_C_API ocsd_err_t ocsd_dt_attach_packet_callback(  const dcd_tree_handle_t handle, 
+                                                const unsigned char CSID,
+                                                const ocsd_c_api_cb_types callback_type, 
+                                                void *p_fn_callback_data,
+                                                const void *p_context);
+
+
+/*!
+ * Get the stats block for the channel indicated. 
+ * Caller must check p_stats_block->version to esure that the block
+ * is filled in a compatible manner.
+ * 
+ * @param handle : Handle to decode tree.
+ * @param CSID : Configured CoreSight trace ID for the decoder.
+ * @param p_stats_block: block pointer to set to reference the stats block.
+ * 
+ * @return ocsd_err_t  : Library error code -  OCSD_OK if valid block pointer returned, 
+ *                      OCSD_ERR_NOTINIT if decoder does not support stats counting.
+ */
+OCSD_C_API ocsd_err_t ocsd_dt_get_decode_stats( const dcd_tree_handle_t handle,
+                                                const unsigned char CSID,
+                                                ocsd_decode_stats_t **p_stats_block);
+ 
+
+/*!
+ * Reset the stats block for the chosens decode channel. 
+ * stats block is reset independently of the decoder reset to allow counts across
+ * multiple decode runs.
+ *
+ * @param handle : Handle to decode tree.
+ * @param CSID : Configured CoreSight trace ID for the decoder.
+ *
+ * @return ocsd_err_t  : Library error code -  OCSD_OK if successful.
+ */
+OCSD_C_API ocsd_err_t ocsd_dt_reset_decode_stats( const dcd_tree_handle_t handle,
+                                                  const unsigned char CSID);
+
+/** @}*/
+/*---------------------- Memory Access for traced opcodes ----------------------------------------------------------------------------------*/
+/** @name Library Memory Accessor configuration on decode tree.
+    @brief Configure the memory regions available for decode.
+    
+    Full decode requires memory regions set up to allow access to the traced
+    opcodes. Add memory buffers or binary file regions to a map of regions.
+
+@{*/
+
+/*!
+ * Add a binary file based memory range accessor to the decode tree.
+ *
+ * Adds the entire binary file as a memory space to be accessed
+ *
+ * @param handle : Handle to decode tree.
+ * @param address : Start address of memory area.
+ * @param mem_space : Associated memory space.
+ * @param *filepath : Path to binary data file.
+ *
+ * @return ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+ */
+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); 
+
+/*!
+ * Add a binary file based memory range accessor to the decode tree.
+ * 
+ * Add a binary file that contains multiple regions of memory with differing 
+ * offsets wihtin the file.
+ * 
+ * A linked list of file_mem_region_t structures is supplied. Each structure contains an
+ * offset into the binary file, the start address for this offset and the size of the region.
+ * 
+ * @param handle : Handle to decode tree.
+ * @param region_list : Array of memory regions in the file.
+ * @param num_regions : Size of region array
+ * @param mem_space : Associated memory space.
+ * @param *filepath : Path to binary data file.
+ *
+ * @return ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+ */
+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); 
+
+/*!
+ * Add a memory buffer based memory range accessor to the decode tree.
+ *
+ * @param handle : Handle to decode tree.
+ * @param address : Start address of memory area.
+ * @param mem_space : Associated memory space.
+ * @param *p_mem_buffer : pointer to memory buffer.
+ * @param mem_length : Size of memory buffer.
+ *
+ * @return ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+ */
+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); 
+
+
+/*!
+ * Add a memory access callback function. The decoder will call the function for opcode addresses in the 
+ * address range supplied for the memory spaces covered.
+ *
+ * @param handle : Handle to decode tree.
+ * @param st_address :  Start address of memory area covered by the callback.
+ * @param en_address :  End address of the memory area covered by the callback. (inclusive)
+ * @param mem_space : Memory space(s) covered by the callback.
+ * @param p_cb_func : Callback function
+ * @param p_context : opaque context pointer value used in callback function.
+ *
+ * @return OCSD_C_API ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+ */
+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); 
+
+
+/*!
+ * Add a memory access callback function. The decoder will call the function for opcode addresses in the 
+ * address range supplied for the memory spaces covered.
+ *
+ * @param handle : Handle to decode tree.
+ * @param st_address :  Start address of memory area covered by the callback.
+ * @param en_address :  End address of the memory area covered by the callback. (inclusive)
+ * @param mem_space : Memory space(s) covered by the callback.
+ * @param p_cb_func : Callback function - Signature for CB with Trace ID passed to client.
+ * @param p_context : opaque context pointer value used in callback function.
+ *
+ * @return OCSD_C_API ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+ */
+OCSD_C_API ocsd_err_t ocsd_dt_add_callback_trcid_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_MemAccID_CB p_cb_func, const void *p_context);
+
+
+/*!
+ * Remove a memory accessor by address and memory space.
+ *
+ * @param handle : Handle to decode tree.
+ * @param st_address : Start address of memory accessor. 
+ * @param mem_space : Memory space(s) covered by the accessor.
+ *
+ * @return OCSD_C_API ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+ */
+OCSD_C_API ocsd_err_t ocsd_dt_remove_mem_acc(const dcd_tree_handle_t handle, const ocsd_vaddr_t st_address, const ocsd_mem_space_acc_t mem_space);
+
+/*
+ *  Print the mapped memory accessor ranges to the configured logger.
+ *
+ * @param handle : Handle to decode tree.
+ */
+OCSD_C_API void ocsd_tl_log_mapped_mem_ranges(const dcd_tree_handle_t handle);
+
+/** @}*/  
+
+/** @name Library Default Error Log Object API
+    @brief Configure the default error logging object in the library.
+
+    Objects created by the decode trees will use this error logger. Configure for 
+    desired error severity, and to enable print or logfile output.
+
+@{*/
+
+/*---------------------- Library Logging and debug ----------------------------------------------------------------------------------*/
+/*!
+ * Initialise the library error logger. 
+ *
+ * Choose severity of errors logger, and if the errors will be logged to screen and / or logfile.
+ *
+ * @param verbosity : Severity of errors that will be logged.
+ * @param create_output_logger : Set to none-zero to create an output printer.
+ *
+ * @return ocsd_err_t  : Library error code -  RCDTL_OK if successful. 
+ */
+OCSD_C_API ocsd_err_t ocsd_def_errlog_init(const ocsd_err_severity_t verbosity, const int create_output_logger);
+
+/*!
+ * Configure the output logger. Choose STDOUT, STDERR and/or log to file.
+ * Optionally provide a log file name.
+ *
+ * @param output_flags : OR combination of required  C_API_MSGLOGOUT_FLG_* flags.
+ * @param *log_file_name : optional filename if logging to file. Set to NULL if not needed.
+ *
+ * @return OCSD_C_API ocsd_err_t  : Library error code -  RCDTL_OK if successful. 
+ */
+OCSD_C_API ocsd_err_t ocsd_def_errlog_config_output(const int output_flags, const char *log_file_name);
+
+/*!
+ * Configure the library default error logger to send all strings it is outputting back to the client 
+ * to allow printing within the client application. This is in additional to any other log destinations
+ * set in ocsd_def_errlog_init().
+ *
+ * @param *p_context : opaque context pointer
+ * @param p_str_print_cb : client callback function to "print" logstring. 
+ */
+OCSD_C_API ocsd_err_t ocsd_def_errlog_set_strprint_cb(const dcd_tree_handle_t handle, void *p_context, FnDefLoggerPrintStrCB p_str_print_cb);
+
+/*!
+ * Print a message via the library output printer - if enabled.
+ *
+ * @param *msg : Message to output.
+ *
+ */
+OCSD_C_API void ocsd_def_errlog_msgout(const char *msg);
+
+/*!
+ * Convert an error code into a string.
+ *
+ * @param err         : error code.
+ * @param buffer      : buffer for return string
+ * @param buffer_size : length of buffer.
+ */
+OCSD_C_API void ocsd_err_str(const ocsd_err_t err, char *buffer, const int buffer_size);
+
+/*!
+ * returns the last error logged by the system, with the related trace byte index, trace channel id,
+ * and any error message related string.
+ * If index or channel ID are not valid these will return OCSD_BAD_TRC_INDEX and OCSD_BAD_CS_SRC_ID.
+ *
+ * return value is the error code of the last logged error, OCSD_OK for no error available.
+ *
+ * @param index      : returns trace byte index relating to error, or OCSD_BAD_TRC_INDEX
+ * @param chan_id    : returns trace channel ID relating to error, or OCSD_BAD_CS_SRC_ID
+ * @param message    : buffer to copy the last error message.
+ * @param message_len: length of message buffer.
+ */
+OCSD_C_API ocsd_err_t ocsd_get_last_err(ocsd_trc_index_t *index, uint8_t *chan_id, char *message, const int message_len);
+
+/** @}*/
+
+/** @name Packet to string interface
+
+@{*/
+
+/*!
+ * Take a packet structure and render a string representation of the packet data.
+ * 
+ * Returns a '0' terminated string of (buffer_size - 1) length or less.
+ *
+ * @param pkt_protocol : Packet protocol type - used to interpret the packet pointer
+ * @param *p_pkt : pointer to a valid packet structure of protocol type. cast to void *.
+ * @param *buffer : character buffer for string.
+ * @param buffer_size : size of character buffer.
+ *
+ * @return  ocsd_err_t  : Library error code -  RCDTL_OK if successful. 
+ */
+OCSD_C_API ocsd_err_t ocsd_pkt_str(const ocsd_trace_protocol_t pkt_protocol, const void *p_pkt, char *buffer, const int buffer_size);
+
+/*!
+ * Get a string representation of the generic trace element.
+ *
+ * @param *p_pkt : pointer to valid generic element structure.
+ * @param *buffer : character buffer for string.
+ * @param buffer_size : size of character buffer.
+ *
+ * @return ocsd_err_t  : Library error code -  RCDTL_OK if successful. 
+ */
+OCSD_C_API ocsd_err_t ocsd_gen_elem_str(const ocsd_generic_trace_elem *p_pkt, char *buffer, const int buffer_size);
+
+
+/*!
+ * Init a generic element with type, clearing any flags etc.
+ */
+OCSD_C_API void ocsd_gen_elem_init(ocsd_generic_trace_elem *p_pkt, const ocsd_gen_trc_elem_t elem_type);
+
+/** @}*/
+
+/** @name Library packet and data printer control API
+    @brief Allows client to use libraries packet and data printers to log packets etc rather than attach callbacks 
+    to packet output and use packet to string calls.
+@{*/
+
+/*!
+ * Set a raw frame printer on the trace frame demuxer. Allows inspection of raw trace data frames for debug.
+ * Prints via the library default error logging mechanisms.
+ *
+ * The flags input determines the data printed. OR combination of one or both of:
+ * OCSD_DFRMTR_PACKED_RAW_OUT   : Output the undemuxed raw data frames.
+ * OCSD_DFRMTR_UNPACKED_RAW_OUT : Output the raw data by trace ID after unpacking the frame.
+ *
+ * @param handle : Handle to decode tree.
+ * @param flags : indicates type of raw frames to print. 
+ *
+ * @return ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+ */
+OCSD_C_API ocsd_err_t ocsd_dt_set_raw_frame_printer(const dcd_tree_handle_t handle, int flags);
+
+/*!
+ * Set a library printer on the generic element output of a full decoder.
+ *
+ * @param handle : Handle to decode tree.
+ *
+ * @return ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+ */
+OCSD_C_API ocsd_err_t ocsd_dt_set_gen_elem_printer(const dcd_tree_handle_t handle);
+
+/*!
+ * Attach a library printer to the packet processor. May be attached to the main packet output, or the monitor
+ * output if the main packet output is to be attached to a packet decoder in the datapath.
+ *
+ * @param handle : Handle to decode tree.
+ * @param cs_id  : Coresight trace ID for stream to print.
+ * @param monitor: 0 to attach printer directly to datapath packet output, 1 to attach to packet monitor output  
+ *
+ * @return ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+ */
+OCSD_C_API ocsd_err_t ocsd_dt_set_pkt_protocol_printer(const dcd_tree_handle_t handle, uint8_t cs_id, int monitor);
+
+/** @}*/
+
+
+/** @name Custom Decoder API functions
+
+@{*/
+
+/** Register a custom decoder with the library 
+
+    @param *name : Name under which to register the decoder.
+    @param *p_dcd_fact : Custom decoder factory structure.
+
+    @return ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+*/
+OCSD_C_API ocsd_err_t ocsd_register_custom_decoder(const char *name, ocsd_extern_dcd_fact_t *p_dcd_fact);
+
+/** Clear all registered decoders - library cleanup 
+    
+    @return ocsd_err_t  : Library error code -  RCDTL_OK if successful.
+*/
+OCSD_C_API ocsd_err_t ocsd_deregister_decoders(void);
+
+/** Get a string representation of a custom protocol packet.
+
+    Specific function to extract the packet string for a custom protocol ID only. Custom IDs are allocated to decoder factories 
+    during the ocsd_register_custom_decoder() process.
+
+    This function is called by ocsd_pkt_str() when the incoming protocol is a custom ID.
+
+    @param pkt_protocol : Packet protocol type - must be in the custom ID range ( >= OCSD_PROTOCOL_CUSTOM_0, < OCSD_PROTOCOL_END) 
+    @param *p_pkt : pointer to a valid packet structure of protocol type. cast to void *.
+    @param *buffer : character buffer for string.
+    @param buffer_size : size of character buffer.
+
+    @return ocsd_err_t  : Library error code -  RCDTL_OK if successful, OCSD_ERR_NO_PROTOCOL if input ID not in custom range or not in use.
+*/
+OCSD_C_API ocsd_err_t ocsd_cust_protocol_to_str(const ocsd_trace_protocol_t pkt_protocol, const void *trc_pkt, char *buffer, const int buflen);
+
+/** @}*/
+
+
+/** @}*/
+
+#endif // ARM_OPENCSD_C_API_H_INCLUDED
+
+/* End of File opencsd_c_api.h */