OpenCSD - CoreSight Trace Decode Library  1.3.3
Classes
OpenCSD Library : Custom External Decoder C-API

Set of types, structures and interfaces for attaching custom decoders via the C-API. More...

Classes

struct  _ocsd_extern_dcd_inst
 
struct  _ocsd_extern_dcd_cb_fns
 
struct  _ocsd_extern_dcd_fact
 

External decoder - Input Interfaces

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)
 
typedef void(* fnUpdatePktMonFlags) (const void *decoder_handle, const int flags)
 
typedef struct _ocsd_extern_dcd_inst ocsd_extern_dcd_inst_t
 
#define OCSD_CUST_DCD_PKT_CB_USE_MON   0x1
 
#define OCSD_CUST_DCD_PKT_CB_USE_SINK   0x2
 

External decoder - Callback Interfaces

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)
 
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)
 
typedef void(* fnLogMsgCB) (const void *lib_context, const ocsd_err_severity_t filter_level, const char *msg)
 
typedef ocsd_err_t(* fnDecodeArmInstCB) (const void *lib_context, ocsd_instr_info *instr_info)
 
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)
 
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)
 
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)
 
typedef struct _ocsd_extern_dcd_cb_fns ocsd_extern_dcd_cb_fns
 

External decoder - Decoder Factory

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)
 
typedef ocsd_err_t(* fnDestroyCustomDecoder) (const void *decoder_handle)
 
typedef ocsd_err_t(* fnGetCSIDFromConfig) (const void *decoder_cfg, unsigned char *p_csid)
 
typedef ocsd_err_t(* fnPacketToString) (const void *trc_pkt, char *buffer, const int buflen)
 
typedef struct _ocsd_extern_dcd_fact ocsd_extern_dcd_fact_t
 

Detailed Description

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:-

Macro Definition Documentation

◆ OCSD_CUST_DCD_PKT_CB_USE_MON

#define OCSD_CUST_DCD_PKT_CB_USE_MON   0x1

Flag to indicate the the packet monitor (fnPktMonCB) is in use in the library

Definition at line 84 of file ocsd_c_api_custom.h.

◆ OCSD_CUST_DCD_PKT_CB_USE_SINK

#define OCSD_CUST_DCD_PKT_CB_USE_SINK   0x2

Flag to indicate the the packet sink (fnPktDataSinkCB) is in use in the library - only if trace packet processing only mode.

Definition at line 87 of file ocsd_c_api_custom.h.

Typedef Documentation

◆ fnCreateCustomDecoder

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 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.
Parameters
create_flags: Sets the decoder operating mode.
*decoder_cfg: Hardware specific configuration for this trace element.
*p_lib_callbacks: Library callbacks plus context pointer.
*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.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful

Definition at line 204 of file ocsd_c_api_custom.h.

◆ fnDecodeArmInstCB

typedef ocsd_err_t(* fnDecodeArmInstCB) (const void *lib_context, ocsd_instr_info *instr_info)

callback function to connect an ARM instruction decoder Implements IInstrDecode::DecodeInstruction with addition of library context pointer.

Definition at line 135 of file ocsd_c_api_custom.h.

◆ fnDestroyCustomDecoder

typedef ocsd_err_t(* fnDestroyCustomDecoder) (const void *decoder_handle)

Function to destroy a decoder instance indicated by decoder handle.

Parameters
decoder_handle: Instance handle for decoder.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful

Definition at line 212 of file ocsd_c_api_custom.h.

◆ fnGenElemOpCB

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 function to connect into the generic element output point Implements ITrcGenElemIn::TraceElemIn with addition of library context pointer.

Definition at line 112 of file ocsd_c_api_custom.h.

◆ fnGetCSIDFromConfig

typedef ocsd_err_t(* fnGetCSIDFromConfig) (const void *decoder_cfg, unsigned char *p_csid)

Function to extract the CoreSight Trace ID from the configuration structure.

Parameters
*decoder_cfg: Hardware specific configuration for this trace element. @parma *p_csid : location to write CoreSight Trace ID value.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful

Definition at line 221 of file ocsd_c_api_custom.h.

◆ fnLogErrorCB

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::LogError with addition of library context pointer.

Definition at line 120 of file ocsd_c_api_custom.h.

◆ fnLogMsgCB

typedef void(* fnLogMsgCB) (const void *lib_context, const ocsd_err_severity_t filter_level, const char *msg)

callback functions to connect into the library error logging mechanism Implements ITraceErrorLog::LogMessage with addition of library context pointer.

Definition at line 130 of file ocsd_c_api_custom.h.

◆ fnMemAccessCB

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 the memory accessor interface Implements ITargetMemAccess::ReadTargetMemory with addition of library context pointer.

Definition at line 140 of file ocsd_c_api_custom.h.

◆ fnPacketToString

typedef ocsd_err_t(* fnPacketToString) (const void *trc_pkt, char *buffer, const int buflen)

Function to convert a protocol specific trace packet to human readable string

Parameters
*trc_pkt: protocol specific packet structure.
*buffer: buffer to fill with string.
buflen: length of string buffer.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful

Definition at line 231 of file ocsd_c_api_custom.h.

◆ fnPktDataSinkCB

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)

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.

Definition at line 162 of file ocsd_c_api_custom.h.

◆ fnPktMonCB

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 monitor interface of the packet processor Implements IPktRawDataMon::RawPacketDataMon <void> with addition of library context pointer.

Definition at line 150 of file ocsd_c_api_custom.h.

◆ fnTraceDataIn

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)

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.

Definition at line 62 of file ocsd_c_api_custom.h.

◆ fnUpdatePktMonFlags

typedef void(* fnUpdatePktMonFlags) (const void *decoder_handle, const int flags)

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.

Parameters
decoder_handle: handle for decoder accessed by this call.
flagsValues indicating interfaces in use / not in use. [ OCSD_CUST_DCD_PKT_CB_USE_MON or OCSD_CUST_DCD_PKT_CB_USE_SINK]

Definition at line 79 of file ocsd_c_api_custom.h.

◆ ocsd_extern_dcd_cb_fns

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.

◆ ocsd_extern_dcd_fact_t

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.

◆ ocsd_extern_dcd_inst_t

Owned by the library instance object, this structure is filled in by the ocsd_extern_dcd_fact_t createDecoder() function.