OpenCSD - CoreSight Trace Decode Library  1.3.3
Macros
OpenCSD Library : Library "C" API.

"C" API for the OpenCSD Library More...

Macros

#define OCSD_C_API
 
typedef void * dcd_tree_handle_t
 

Library Version API

OCSD_C_API uint32_t ocsd_get_version (void)
 
OCSD_C_API const char * ocsd_get_version_str (void)
 

Library Decode Tree API

OCSD_C_API dcd_tree_handle_t ocsd_create_dcd_tree (const ocsd_dcd_tree_src_t src_type, const uint32_t deformatterCfgFlags)
 
OCSD_C_API void ocsd_destroy_dcd_tree (const dcd_tree_handle_t handle)
 
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)
 
OCSD_C_API ocsd_err_t ocsd_dt_set_gen_elem_outfn (const dcd_tree_handle_t handle, FnTraceElemIn pFn, const void *p_context)
 
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)
 
OCSD_C_API ocsd_err_t ocsd_dt_remove_decoder (const dcd_tree_handle_t handle, const unsigned char CSID)
 
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)
 
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)
 
OCSD_C_API ocsd_err_t ocsd_dt_reset_decode_stats (const dcd_tree_handle_t handle, const unsigned char CSID)
 

Library Memory Accessor configuration on decode tree.

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.

OCSD_C_API ocsd_err_t ocsd_dt_add_binfile_mem_acc (const dcd_tree_handle_t handle, const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const char *filepath)
 
OCSD_C_API ocsd_err_t ocsd_dt_add_binfile_region_mem_acc (const dcd_tree_handle_t handle, const ocsd_file_mem_region_t *region_array, const int num_regions, const ocsd_mem_space_acc_t mem_space, const char *filepath)
 
OCSD_C_API ocsd_err_t ocsd_dt_add_buffer_mem_acc (const dcd_tree_handle_t handle, const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const uint8_t *p_mem_buffer, const uint32_t mem_length)
 
OCSD_C_API ocsd_err_t ocsd_dt_add_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)
 
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)
 
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)
 
OCSD_C_API void ocsd_tl_log_mapped_mem_ranges (const dcd_tree_handle_t handle)
 

Library Default Error Log Object API

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.

OCSD_C_API ocsd_err_t ocsd_def_errlog_init (const ocsd_err_severity_t verbosity, const int create_output_logger)
 
OCSD_C_API ocsd_err_t ocsd_def_errlog_config_output (const int output_flags, const char *log_file_name)
 
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)
 
OCSD_C_API void ocsd_def_errlog_msgout (const char *msg)
 
OCSD_C_API void ocsd_err_str (const ocsd_err_t err, char *buffer, const int buffer_size)
 
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)
 

Packet to string interface

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)
 
OCSD_C_API ocsd_err_t ocsd_gen_elem_str (const ocsd_generic_trace_elem *p_pkt, char *buffer, const int buffer_size)
 
OCSD_C_API void ocsd_gen_elem_init (ocsd_generic_trace_elem *p_pkt, const ocsd_gen_trc_elem_t elem_type)
 

Library packet and data printer control API

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.

OCSD_C_API ocsd_err_t ocsd_dt_set_raw_frame_printer (const dcd_tree_handle_t handle, int flags)
 
OCSD_C_API ocsd_err_t ocsd_dt_set_gen_elem_printer (const dcd_tree_handle_t handle)
 
OCSD_C_API ocsd_err_t ocsd_dt_set_pkt_protocol_printer (const dcd_tree_handle_t handle, uint8_t cs_id, int monitor)
 

Custom Decoder API functions

OCSD_C_API ocsd_err_t ocsd_register_custom_decoder (const char *name, ocsd_extern_dcd_fact_t *p_dcd_fact)
 
OCSD_C_API ocsd_err_t ocsd_deregister_decoders (void)
 
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)
 

Detailed Description

"C" API for the OpenCSD Library

Set of "C" wrapper functions for the OpenCSD library.

Defines API, functions and callback types.

Macro Definition Documentation

◆ OCSD_C_API

#define OCSD_C_API

Definition at line 77 of file opencsd_c_api.h.

Typedef Documentation

◆ dcd_tree_handle_t

typedef void* dcd_tree_handle_t

Handle to decode tree

Definition at line 58 of file ocsd_c_api_types.h.

Function Documentation

◆ ocsd_create_dcd_tree()

OCSD_C_API dcd_tree_handle_t ocsd_create_dcd_tree ( const ocsd_dcd_tree_src_t  src_type,
const uint32_t  deformatterCfgFlags 
)

Create a decode tree.

Parameters
src_type: Type of tree - formatted input, or single source input
deformatterCfgFlags: Formatter flags - determine presence of frame syncs etc.
Returns
dcd_tree_handle_t : Handle to the decode tree. Handle value set to 0 if creation failed.

◆ ocsd_cust_protocol_to_str()

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 
)

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.

Parameters
pkt_protocol: Packet protocol type - must be in the custom ID range ( >= OCSD_PROTOCOL_CUSTOM_0, < OCSD_PROTOCOL_END)
*p_pkt: pointer to a valid packet structure of protocol type. cast to void *.
*buffer: character buffer for string.
buffer_size: size of character buffer.
Returns
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_def_errlog_config_output()

OCSD_C_API ocsd_err_t ocsd_def_errlog_config_output ( const int  output_flags,
const char *  log_file_name 
)

Configure the output logger. Choose STDOUT, STDERR and/or log to file. Optionally provide a log file name.

Parameters
output_flags: OR combination of required C_API_MSGLOGOUT_FLG_* flags.
*log_file_name: optional filename if logging to file. Set to NULL if not needed.
Returns
OCSD_C_API ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_def_errlog_init()

OCSD_C_API ocsd_err_t ocsd_def_errlog_init ( const ocsd_err_severity_t  verbosity,
const int  create_output_logger 
)

Initialise the library error logger.

Choose severity of errors logger, and if the errors will be logged to screen and / or logfile.

Parameters
verbosity: Severity of errors that will be logged.
create_output_logger: Set to none-zero to create an output printer.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_def_errlog_msgout()

OCSD_C_API void ocsd_def_errlog_msgout ( const char *  msg)

Print a message via the library output printer - if enabled.

Parameters
*msg: Message to output.

◆ ocsd_def_errlog_set_strprint_cb()

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 
)

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

Parameters
*p_context: opaque context pointer
p_str_print_cb: client callback function to "print" logstring.

◆ ocsd_deregister_decoders()

OCSD_C_API ocsd_err_t ocsd_deregister_decoders ( void  )

Clear all registered decoders - library cleanup

Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_destroy_dcd_tree()

OCSD_C_API void ocsd_destroy_dcd_tree ( const dcd_tree_handle_t  handle)

Destroy a decode tree.

Also destroys all the associated processors and decoders for the tree.

Parameters
handle: Handle for decode tree to destroy.

◆ ocsd_dt_add_binfile_mem_acc()

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.

Adds the entire binary file as a memory space to be accessed

Parameters
handle: Handle to decode tree.
address: Start address of memory area.
mem_space: Associated memory space.
*filepath: Path to binary data file.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_dt_add_binfile_region_mem_acc()

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

Parameters
handle: Handle to decode tree.
region_list: Array of memory regions in the file.
num_regions: Size of region array
mem_space: Associated memory space.
*filepath: Path to binary data file.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_dt_add_buffer_mem_acc()

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 buffer based memory range accessor to the decode tree.

Parameters
handle: Handle to decode tree.
address: Start address of memory area.
mem_space: Associated memory space.
*p_mem_buffer: pointer to memory buffer.
mem_length: Size of memory buffer.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_dt_add_callback_mem_acc()

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.

Parameters
handle: Handle to decode tree.
st_address: Start address of memory area covered by the callback.
en_address: End address of the memory area covered by the callback. (inclusive)
mem_space: Memory space(s) covered by the callback.
p_cb_func: Callback function
p_context: opaque context pointer value used in callback function.
Returns
OCSD_C_API ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_dt_add_callback_trcid_mem_acc()

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 
)

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.

Parameters
handle: Handle to decode tree.
st_address: Start address of memory area covered by the callback.
en_address: End address of the memory area covered by the callback. (inclusive)
mem_space: Memory space(s) covered by the callback.
p_cb_func: Callback function - Signature for CB with Trace ID passed to client.
p_context: opaque context pointer value used in callback function.
Returns
OCSD_C_API ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_dt_attach_packet_callback()

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 
)

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.

Parameters
handle: Handle to decode tree.
CSID: Configured CoreSight trace ID for the decoder.
callback_type: Attachment point
p_fn_pkt_data_in: Pointer to the callback function.
p_context: Opaque context pointer value used in callback function.
Returns
ocsd_err_t : Library error code - OCSD_OK if successful.

◆ ocsd_dt_create_decoder()

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 
)

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.

Parameters
handle: Handle to decode tree.
*decoder_name: Registered name of the decoder to create.
create_flags: Decoder creation options.
*decoder_cfg: Pointer to a valid configuration structure for the named decoder.
*pCSID: Pointer to location to return the configured CoreSight trace ID for the decoder.
Returns
ocsd_err_t : Library error code - OCSD_OK if successful.

◆ ocsd_dt_get_decode_stats()

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 
)

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.

Parameters
handle: Handle to decode tree.
CSID: Configured CoreSight trace ID for the decoder.
p_stats_blockblock pointer to set to reference the stats block.
Returns
ocsd_err_t : Library error code - OCSD_OK if valid block pointer returned, OCSD_ERR_NOTINIT if decoder does not support stats counting.

◆ ocsd_dt_process_data()

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 
)

Input trace data into the decoder.

Large trace source buffers can be broken down into smaller fragments.

Parameters
handle: Handle to decode tree.
op: Datapath operation.
index: Trace buffer byte index for the start of the supplied data block.
dataBlockSize: Size of data block.
*pDataBlock: Pointer to data block.
*numBytesProcessed: Number of bytes actually processed by the decoder.
Returns
ocsd_datapath_resp_t : Datapath response code (CONT/WAIT/FATAL)

◆ ocsd_dt_remove_decoder()

OCSD_C_API ocsd_err_t ocsd_dt_remove_decoder ( const dcd_tree_handle_t  handle,
const unsigned char  CSID 
)

Remove a decoder from the tree and destroy it.

Parameters
handle: Handle to decode tree.
CSID: Configured CoreSight trace ID for the decoder.
Returns
ocsd_err_t : Library error code - OCSD_OK if successful.

◆ ocsd_dt_remove_mem_acc()

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 
)

Remove a memory accessor by address and memory space.

Parameters
handle: Handle to decode tree.
st_address: Start address of memory accessor.
mem_space: Memory space(s) covered by the accessor.
Returns
OCSD_C_API ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_dt_reset_decode_stats()

OCSD_C_API ocsd_err_t ocsd_dt_reset_decode_stats ( const dcd_tree_handle_t  handle,
const unsigned char  CSID 
)

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.

Parameters
handle: Handle to decode tree.
CSID: Configured CoreSight trace ID for the decoder.
Returns
ocsd_err_t : Library error code - OCSD_OK if successful.

◆ ocsd_dt_set_gen_elem_outfn()

OCSD_C_API ocsd_err_t ocsd_dt_set_gen_elem_outfn ( const dcd_tree_handle_t  handle,
FnTraceElemIn  pFn,
const void *  p_context 
)

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.

Parameters
handle: Handle to decode tree.
pFn: Pointer to the callback function.
p_context: opaque context pointer value used in callback function.
Returns
ocsd_err_t : Library error code - OCSD_OK if successful.

◆ ocsd_dt_set_gen_elem_printer()

OCSD_C_API ocsd_err_t ocsd_dt_set_gen_elem_printer ( const dcd_tree_handle_t  handle)

Set a library printer on the generic element output of a full decoder.

Parameters
handle: Handle to decode tree.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_dt_set_pkt_protocol_printer()

OCSD_C_API ocsd_err_t ocsd_dt_set_pkt_protocol_printer ( const dcd_tree_handle_t  handle,
uint8_t  cs_id,
int  monitor 
)

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.

Parameters
handle: Handle to decode tree.
cs_id: Coresight trace ID for stream to print.
monitor0 to attach printer directly to datapath packet output, 1 to attach to packet monitor output
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_dt_set_raw_frame_printer()

OCSD_C_API ocsd_err_t ocsd_dt_set_raw_frame_printer ( const dcd_tree_handle_t  handle,
int  flags 
)

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.

Parameters
handle: Handle to decode tree.
flags: indicates type of raw frames to print.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_err_str()

OCSD_C_API void ocsd_err_str ( const ocsd_err_t  err,
char *  buffer,
const int  buffer_size 
)

Convert an error code into a string.

Parameters
err: error code.
buffer: buffer for return string
buffer_size: length of buffer.

◆ ocsd_gen_elem_init()

OCSD_C_API void ocsd_gen_elem_init ( ocsd_generic_trace_elem p_pkt,
const ocsd_gen_trc_elem_t  elem_type 
)

Init a generic element with type, clearing any flags etc.

◆ ocsd_gen_elem_str()

OCSD_C_API ocsd_err_t ocsd_gen_elem_str ( const ocsd_generic_trace_elem p_pkt,
char *  buffer,
const int  buffer_size 
)

Get a string representation of the generic trace element.

Parameters
*p_pkt: pointer to valid generic element structure.
*buffer: character buffer for string.
buffer_size: size of character buffer.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_get_last_err()

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 
)

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.

Parameters
index: returns trace byte index relating to error, or OCSD_BAD_TRC_INDEX
chan_id: returns trace channel ID relating to error, or OCSD_BAD_CS_SRC_ID
message: buffer to copy the last error message.
message_lenlength of message buffer.

◆ ocsd_get_version()

OCSD_C_API uint32_t ocsd_get_version ( void  )

Get Library version. Return a 32 bit version in form MMMMnnpp - MMMM = major version, nn = minor version, pp = patch version

◆ ocsd_get_version_str()

OCSD_C_API const char* ocsd_get_version_str ( void  )

Get library version string

◆ ocsd_pkt_str()

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 
)

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.

Parameters
pkt_protocol: Packet protocol type - used to interpret the packet pointer
*p_pkt: pointer to a valid packet structure of protocol type. cast to void *.
*buffer: character buffer for string.
buffer_size: size of character buffer.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_register_custom_decoder()

OCSD_C_API ocsd_err_t ocsd_register_custom_decoder ( const char *  name,
ocsd_extern_dcd_fact_t p_dcd_fact 
)

Register a custom decoder with the library

Parameters
*name: Name under which to register the decoder.
*p_dcd_fact: Custom decoder factory structure.
Returns
ocsd_err_t : Library error code - RCDTL_OK if successful.

◆ ocsd_tl_log_mapped_mem_ranges()

OCSD_C_API void ocsd_tl_log_mapped_mem_ranges ( const dcd_tree_handle_t  handle)