OpenCSD - CoreSight Trace Decode Library  0.14.1
opencsd_c_api.h
Go to the documentation of this file.
1 
8 /*
9  * Redistribution and use in source and binary forms, with or without modification,
10  * are permitted provided that the following conditions are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright notice,
13  * this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  *
19  * 3. Neither the name of the copyright holder nor the names of its contributors
20  * may be used to endorse or promote products derived from this software without
21  * specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
24  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
25  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
26  * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
27  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
28  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
30  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
32  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  */
34 
35 #ifndef ARM_OPENCSD_C_API_H_INCLUDED
36 #define ARM_OPENCSD_C_API_H_INCLUDED
37 
46 /* ensure C bindings */
47 
48 #if defined(WIN32) /* windows bindings */
49 
50  #ifdef _OCSD_C_API_DLL_EXPORT
51  #ifdef __cplusplus
52  #define OCSD_C_API extern "C" __declspec(dllexport)
53  #else
54  #define OCSD_C_API __declspec(dllexport)
55  #endif
56  #else
57 
58  #if defined(_LIB) || defined(OCSD_USE_STATIC_C_API)
59  #ifdef __cplusplus
60  #define OCSD_C_API extern "C"
61  #else
62  #define OCSD_C_API
63  #endif
64  #else
65 
66  #ifdef __cplusplus
67  #define OCSD_C_API extern "C" __declspec(dllimport)
68  #else
69  #define OCSD_C_API __declspec(dllimport)
70  #endif
71  #endif
72  #endif
73 #else /* linux bindings */
74  #ifdef __cplusplus
75  #define OCSD_C_API extern "C"
76  #else
77  #define OCSD_C_API
78  #endif
79 #endif
80 
81 #include "ocsd_c_api_types.h"
82 #include "ocsd_c_api_custom.h"
83 
88 OCSD_C_API uint32_t ocsd_get_version(void);
89 
91 OCSD_C_API const char * ocsd_get_version_str(void);
94 /*---------------------- Trace Decode Tree ----------------------------------------------------------------------------------*/
95 
107 OCSD_C_API dcd_tree_handle_t ocsd_create_dcd_tree(const ocsd_dcd_tree_src_t src_type, const uint32_t deformatterCfgFlags);
108 
117 
133  const ocsd_datapath_op_t op,
134  const ocsd_trc_index_t index,
135  const uint32_t dataBlockSize,
136  const uint8_t *pDataBlock,
137  uint32_t *numBytesProcessed);
138 
139 
140 /*---------------------- Generic Trace Element Output --------------------------------------------------------------*/
141 
156 OCSD_C_API ocsd_err_t ocsd_dt_set_gen_elem_outfn(const dcd_tree_handle_t handle, FnTraceElemIn pFn, const void *p_context);
157 
158 /*---------------------- Trace Decoders ----------------------------------------------------------------------------------*/
174  const char *decoder_name,
175  const int create_flags,
176  const void *decoder_cfg,
177  unsigned char *pCSID
178  );
179 
189  const unsigned char CSID);
190 
191 
207  const unsigned char CSID,
208  const ocsd_c_api_cb_types callback_type,
209  void *p_fn_callback_data,
210  const void *p_context);
211 
212 
213 
214 
215 
216 
218 /*---------------------- Memory Access for traced opcodes ----------------------------------------------------------------------------------*/
239 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);
240 
258 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);
259 
271 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);
272 
273 
287 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);
288 
289 
303 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);
304 
305 
315 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);
316 
317 /*
318  * Print the mapped memory accessor ranges to the configured logger.
319  *
320  * @param handle : Handle to decode tree.
321  */
323 
334 /*---------------------- Library Logging and debug ----------------------------------------------------------------------------------*/
345 OCSD_C_API ocsd_err_t ocsd_def_errlog_init(const ocsd_err_severity_t verbosity, const int create_output_logger);
346 
356 OCSD_C_API ocsd_err_t ocsd_def_errlog_config_output(const int output_flags, const char *log_file_name);
357 
367 
374 OCSD_C_API void ocsd_def_errlog_msgout(const char *msg);
375 
376 
395 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);
396 
406 OCSD_C_API ocsd_err_t ocsd_gen_elem_str(const ocsd_generic_trace_elem *p_pkt, char *buffer, const int buffer_size);
407 
408 
413 
435 
444 
455 OCSD_C_API ocsd_err_t ocsd_dt_set_pkt_protocol_printer(const dcd_tree_handle_t handle, uint8_t cs_id, int monitor);
456 
472 
478 
493 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);
494 
500 #endif // ARM_OPENCSD_C_API_H_INCLUDED
501 
502 /* End of File opencsd_c_api.h */
ocsd_get_version_str
const OCSD_C_API char * ocsd_get_version_str(void)
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)
ocsd_datapath_resp_t
enum _ocsd_datapath_resp_t ocsd_datapath_resp_t
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)
ocsd_destroy_dcd_tree
OCSD_C_API void ocsd_destroy_dcd_tree(const dcd_tree_handle_t handle)
Fn_MemAcc_CB
uint32_t(* Fn_MemAcc_CB)(const void *p_context, const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const uint32_t reqBytes, uint8_t *byteBuffer)
Definition: ocsd_if_types.h:460
ocsd_dt_set_gen_elem_printer
OCSD_C_API ocsd_err_t ocsd_dt_set_gen_elem_printer(const dcd_tree_handle_t handle)
FnDefLoggerPrintStrCB
void(* FnDefLoggerPrintStrCB)(const void *p_context, const char *psz_msg_str, const int str_len)
Definition: ocsd_c_api_types.h:94
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)
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)
ocsd_deregister_decoders
OCSD_C_API ocsd_err_t ocsd_deregister_decoders(void)
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)
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)
ocsd_dcd_tree_src_t
enum _ocsd_dcd_tree_src_t ocsd_dcd_tree_src_t
FnTraceElemIn
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)
Definition: ocsd_c_api_types.h:74
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)
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)
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)
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)
_ocsd_generic_trace_elem
Definition: trc_gen_elem_types.h:89
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)
ocsd_c_api_types.h
OpenCSD : Trace Decoder "C" API types.
ocsd_vaddr_t
uint64_t ocsd_vaddr_t
Definition: ocsd_if_types.h:308
ocsd_err_t
enum _ocsd_err_t ocsd_err_t
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)
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)
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)
ocsd_datapath_op_t
enum _ocsd_datapath_op_t ocsd_datapath_op_t
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)
ocsd_tl_log_mapped_mem_ranges
OCSD_C_API void ocsd_tl_log_mapped_mem_ranges(const dcd_tree_handle_t handle)
_ocsd_extern_dcd_fact
Definition: ocsd_c_api_custom.h:237
ocsd_gen_trc_elem_t
enum _ocsd_gen_trc_elem_t ocsd_gen_trc_elem_t
Fn_MemAccID_CB
uint32_t(* Fn_MemAccID_CB)(const void *p_context, const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const uint8_t trcID, const uint32_t reqBytes, uint8_t *byteBuffer)
Definition: ocsd_if_types.h:484
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)
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)
dcd_tree_handle_t
void * dcd_tree_handle_t
Definition: ocsd_c_api_types.h:57
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)
OCSD_C_API
#define OCSD_C_API
Definition: opencsd_c_api.h:77
ocsd_trc_index_t
uint32_t ocsd_trc_index_t
Definition: ocsd_if_types.h:67
ocsd_err_severity_t
enum _ocsd_err_severity_t ocsd_err_severity_t
ocsd_get_version
OCSD_C_API uint32_t ocsd_get_version(void)
ocsd_def_errlog_msgout
OCSD_C_API void ocsd_def_errlog_msgout(const char *msg)
ocsd_mem_space_acc_t
enum _ocsd_mem_space_acc_t ocsd_mem_space_acc_t
_ocsd_file_mem_region
Definition: ocsd_if_types.h:488
ocsd_c_api_cb_types
enum _ocsd_c_api_cb_types ocsd_c_api_cb_types
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)
ocsd_dt_remove_decoder
OCSD_C_API ocsd_err_t ocsd_dt_remove_decoder(const dcd_tree_handle_t handle, const unsigned char CSID)
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)
ocsd_trace_protocol_t
enum _ocsd_trace_protocol_t ocsd_trace_protocol_t
ocsd_c_api_custom.h
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)