aboutsummaryrefslogtreecommitdiffstats
path: root/decoder/include/opencsd/c_api
diff options
context:
space:
mode:
authorRuslan Bukin <br@FreeBSD.org>2018-04-04 12:33:46 +0000
committerRuslan Bukin <br@FreeBSD.org>2018-04-04 12:33:46 +0000
commita6157d81121ac9559d806dafa346039199598442 (patch)
tree74bb8dac03bea2e41b98a242951cee587339288a /decoder/include/opencsd/c_api
downloadsrc-a6157d81121ac9559d806dafa346039199598442.tar.gz
src-a6157d81121ac9559d806dafa346039199598442.zip
Import OpenCSD -- an ARM CoreSight Trace Decode library.vendor/opencsd/900407e9d6400f6541138d6c2e483a9fc2d699a4
Git ID 900407e9d6400f6541138d6c2e483a9fc2d699a4 Sponsored by: DARPA, AFRL
Notes
Notes: svn path=/vendor/opencsd/dist/; revision=332012 svn path=/vendor/opencsd/900407e9d6400f6541138d6c2e483a9fc2d699a4/; revision=332013; tag=vendor/opencsd/900407e9d6400f6541138d6c2e483a9fc2d699a4
Diffstat (limited to 'decoder/include/opencsd/c_api')
-rw-r--r--decoder/include/opencsd/c_api/ocsd_c_api_cust_fact.h54
-rw-r--r--decoder/include/opencsd/c_api/ocsd_c_api_cust_impl.h158
-rw-r--r--decoder/include/opencsd/c_api/ocsd_c_api_custom.h253
-rw-r--r--decoder/include/opencsd/c_api/ocsd_c_api_types.h105
-rw-r--r--decoder/include/opencsd/c_api/opencsd_c_api.h485
5 files changed, 1055 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 000000000000..f9e6a95104cc
--- /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 000000000000..245ce162752e
--- /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 000000000000..ada0a68cb3db
--- /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 000000000000..ca61e0aaed32
--- /dev/null
+++ b/decoder/include/opencsd/c_api/ocsd_c_api_types.h
@@ -0,0 +1,105 @@
+/*!
+ * \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/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"
+
+/** @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 000000000000..f9f4ed4b8613
--- /dev/null
+++ b/decoder/include/opencsd/c_api/opencsd_c_api.h
@@ -0,0 +1,485 @@
+/*!
+ * \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 verison, 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);
+
+
+
+
+
+
+/** @}*/
+/*---------------------- 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);
+
+/*!
+ * 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);
+
+
+/** @}*/
+
+/** @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 */