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

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

## 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.
  flags | Values 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

typedef struct _ocsd_extern_dcd_cb_fns 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

typedef struct _ocsd_extern_dcd_fact 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

typedef struct _ocsd_extern_dcd_inst 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.