1 /*! 2 * \file opencsd_c_api.h 3 * \brief OpenCSD : "C" API 4 * 5 * \copyright Copyright (c) 2015, ARM Limited. All Rights Reserved. 6 */ 7 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 38 /** @defgroup lib_c_api OpenCSD Library : Library "C" API. 39 @brief "C" API for the OpenCSD Library 40 41 Set of "C" wrapper functions for the OpenCSD library. 42 43 Defines API, functions and callback types. 44 @{*/ 45 46 /* ensure C bindings */ 47 48 #if defined(WIN32) /* windows bindings */ 49 /** Building the C-API DLL **/ 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 /** building or using the static C-API library **/ 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 /** using the C-API DLL **/ 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 84 /** @name Library Version API 85 86 @{*/ 87 /** Get Library version. Return a 32 bit version in form MMMMnnpp - MMMM = major version, nn = minor version, pp = patch version */ 88 OCSD_C_API uint32_t ocsd_get_version(void); 89 90 /** Get library version string */ 91 OCSD_C_API const char * ocsd_get_version_str(void); 92 /** @}*/ 93 94 /*---------------------- Trace Decode Tree ----------------------------------------------------------------------------------*/ 95 96 /** @name Library Decode Tree API 97 @{*/ 98 99 /*! 100 * Create a decode tree. 101 * 102 * @param src_type : Type of tree - formatted input, or single source input 103 * @param deformatterCfgFlags : Formatter flags - determine presence of frame syncs etc. 104 * 105 * @return dcd_tree_handle_t : Handle to the decode tree. Handle value set to 0 if creation failed. 106 */ 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 109 /*! 110 * Destroy a decode tree. 111 * 112 * Also destroys all the associated processors and decoders for the tree. 113 * 114 * @param handle : Handle for decode tree to destroy. 115 */ 116 OCSD_C_API void ocsd_destroy_dcd_tree(const dcd_tree_handle_t handle); 117 118 /*! 119 * Input trace data into the decoder. 120 * 121 * Large trace source buffers can be broken down into smaller fragments. 122 * 123 * @param handle : Handle to decode tree. 124 * @param op : Datapath operation. 125 * @param index : Trace buffer byte index for the start of the supplied data block. 126 * @param dataBlockSize : Size of data block. 127 * @param *pDataBlock : Pointer to data block. 128 * @param *numBytesProcessed : Number of bytes actually processed by the decoder. 129 * 130 * @return ocsd_datapath_resp_t : Datapath response code (CONT/WAIT/FATAL) 131 */ 132 OCSD_C_API ocsd_datapath_resp_t ocsd_dt_process_data(const dcd_tree_handle_t handle, 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 142 /*! 143 * Set the trace element output callback function. 144 * 145 * This function will be called for each decoded generic trace element generated by 146 * any full trace decoder in the decode tree. 147 * 148 * A single function is used for all trace source IDs in the decode tree. 149 * 150 * @param handle : Handle to decode tree. 151 * @param pFn : Pointer to the callback function. 152 * @param p_context : opaque context pointer value used in callback function. 153 * 154 * @return ocsd_err_t : Library error code - OCSD_OK if successful. 155 */ 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 ----------------------------------------------------------------------------------*/ 159 /*! 160 * Creates a decoder that is registered with the library under the supplied name. 161 * Flags determine if a full packet processor / packet decoder pair or 162 * packet processor only is created. 163 * Uses the supplied configuration structure. 164 * 165 * @param handle : Handle to decode tree. 166 * @param *decoder_name : Registered name of the decoder to create. 167 * @param create_flags : Decoder creation options. 168 * @param *decoder_cfg : Pointer to a valid configuration structure for the named decoder. 169 * @param *pCSID : Pointer to location to return the configured CoreSight trace ID for the decoder. 170 * 171 * @return ocsd_err_t : Library error code - OCSD_OK if successful. 172 */ 173 OCSD_C_API ocsd_err_t ocsd_dt_create_decoder(const dcd_tree_handle_t handle, 174 const char *decoder_name, 175 const int create_flags, 176 const void *decoder_cfg, 177 unsigned char *pCSID 178 ); 179 180 /*! 181 * Remove a decoder from the tree and destroy it. 182 * 183 * @param handle : Handle to decode tree. 184 * @param CSID : Configured CoreSight trace ID for the decoder. 185 * 186 * @return ocsd_err_t : Library error code - OCSD_OK if successful. 187 */ 188 OCSD_C_API ocsd_err_t ocsd_dt_remove_decoder( const dcd_tree_handle_t handle, 189 const unsigned char CSID); 190 191 192 /*! 193 * Attach a callback function to the packet processor. 194 * 195 * The callback_type defines the attachment point, either the main packet output 196 * (only if no decoder attached), or the packet monitor. 197 * 198 * @param handle : Handle to decode tree. 199 * @param CSID : Configured CoreSight trace ID for the decoder. 200 * @param callback_type : Attachment point 201 * @param p_fn_pkt_data_in : Pointer to the callback function. 202 * @param p_context : Opaque context pointer value used in callback function. 203 * 204 * @return ocsd_err_t : Library error code - OCSD_OK if successful. 205 */ 206 OCSD_C_API ocsd_err_t ocsd_dt_attach_packet_callback( const dcd_tree_handle_t handle, 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 * Get the stats block for the channel indicated. 215 * Caller must check p_stats_block->version to esure that the block 216 * is filled in a compatible manner. 217 * 218 * @param handle : Handle to decode tree. 219 * @param CSID : Configured CoreSight trace ID for the decoder. 220 * @param p_stats_block: block pointer to set to reference the stats block. 221 * 222 * @return ocsd_err_t : Library error code - OCSD_OK if valid block pointer returned, 223 * OCSD_ERR_NOTINIT if decoder does not support stats counting. 224 */ 225 OCSD_C_API ocsd_err_t ocsd_dt_get_decode_stats( const dcd_tree_handle_t handle, 226 const unsigned char CSID, 227 ocsd_decode_stats_t **p_stats_block); 228 229 230 /*! 231 * Reset the stats block for the chosens decode channel. 232 * stats block is reset independently of the decoder reset to allow counts across 233 * multiple decode runs. 234 * 235 * @param handle : Handle to decode tree. 236 * @param CSID : Configured CoreSight trace ID for the decoder. 237 * 238 * @return ocsd_err_t : Library error code - OCSD_OK if successful. 239 */ 240 OCSD_C_API ocsd_err_t ocsd_dt_reset_decode_stats( const dcd_tree_handle_t handle, 241 const unsigned char CSID); 242 243 /** @}*/ 244 /*---------------------- Memory Access for traced opcodes ----------------------------------------------------------------------------------*/ 245 /** @name Library Memory Accessor configuration on decode tree. 246 @brief Configure the memory regions available for decode. 247 248 Full decode requires memory regions set up to allow access to the traced 249 opcodes. Add memory buffers or binary file regions to a map of regions. 250 251 @{*/ 252 253 /*! 254 * Add a binary file based memory range accessor to the decode tree. 255 * 256 * Adds the entire binary file as a memory space to be accessed 257 * 258 * @param handle : Handle to decode tree. 259 * @param address : Start address of memory area. 260 * @param mem_space : Associated memory space. 261 * @param *filepath : Path to binary data file. 262 * 263 * @return ocsd_err_t : Library error code - RCDTL_OK if successful. 264 */ 265 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); 266 267 /*! 268 * Add a binary file based memory range accessor to the decode tree. 269 * 270 * Add a binary file that contains multiple regions of memory with differing 271 * offsets wihtin the file. 272 * 273 * A linked list of file_mem_region_t structures is supplied. Each structure contains an 274 * offset into the binary file, the start address for this offset and the size of the region. 275 * 276 * @param handle : Handle to decode tree. 277 * @param region_list : Array of memory regions in the file. 278 * @param num_regions : Size of region array 279 * @param mem_space : Associated memory space. 280 * @param *filepath : Path to binary data file. 281 * 282 * @return ocsd_err_t : Library error code - RCDTL_OK if successful. 283 */ 284 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); 285 286 /*! 287 * Add a memory buffer based memory range accessor to the decode tree. 288 * 289 * @param handle : Handle to decode tree. 290 * @param address : Start address of memory area. 291 * @param mem_space : Associated memory space. 292 * @param *p_mem_buffer : pointer to memory buffer. 293 * @param mem_length : Size of memory buffer. 294 * 295 * @return ocsd_err_t : Library error code - RCDTL_OK if successful. 296 */ 297 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); 298 299 300 /*! 301 * Add a memory access callback function. The decoder will call the function for opcode addresses in the 302 * address range supplied for the memory spaces covered. 303 * 304 * @param handle : Handle to decode tree. 305 * @param st_address : Start address of memory area covered by the callback. 306 * @param en_address : End address of the memory area covered by the callback. (inclusive) 307 * @param mem_space : Memory space(s) covered by the callback. 308 * @param p_cb_func : Callback function 309 * @param p_context : opaque context pointer value used in callback function. 310 * 311 * @return OCSD_C_API ocsd_err_t : Library error code - RCDTL_OK if successful. 312 */ 313 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); 314 315 316 /*! 317 * Add a memory access callback function. The decoder will call the function for opcode addresses in the 318 * address range supplied for the memory spaces covered. 319 * 320 * @param handle : Handle to decode tree. 321 * @param st_address : Start address of memory area covered by the callback. 322 * @param en_address : End address of the memory area covered by the callback. (inclusive) 323 * @param mem_space : Memory space(s) covered by the callback. 324 * @param p_cb_func : Callback function - Signature for CB with Trace ID passed to client. 325 * @param p_context : opaque context pointer value used in callback function. 326 * 327 * @return OCSD_C_API ocsd_err_t : Library error code - RCDTL_OK if successful. 328 */ 329 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); 330 331 332 /*! 333 * Remove a memory accessor by address and memory space. 334 * 335 * @param handle : Handle to decode tree. 336 * @param st_address : Start address of memory accessor. 337 * @param mem_space : Memory space(s) covered by the accessor. 338 * 339 * @return OCSD_C_API ocsd_err_t : Library error code - RCDTL_OK if successful. 340 */ 341 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); 342 343 /* 344 * Print the mapped memory accessor ranges to the configured logger. 345 * 346 * @param handle : Handle to decode tree. 347 */ 348 OCSD_C_API void ocsd_tl_log_mapped_mem_ranges(const dcd_tree_handle_t handle); 349 350 /** @}*/ 351 352 /** @name Library Default Error Log Object API 353 @brief Configure the default error logging object in the library. 354 355 Objects created by the decode trees will use this error logger. Configure for 356 desired error severity, and to enable print or logfile output. 357 358 @{*/ 359 360 /*---------------------- Library Logging and debug ----------------------------------------------------------------------------------*/ 361 /*! 362 * Initialise the library error logger. 363 * 364 * Choose severity of errors logger, and if the errors will be logged to screen and / or logfile. 365 * 366 * @param verbosity : Severity of errors that will be logged. 367 * @param create_output_logger : Set to none-zero to create an output printer. 368 * 369 * @return ocsd_err_t : Library error code - RCDTL_OK if successful. 370 */ 371 OCSD_C_API ocsd_err_t ocsd_def_errlog_init(const ocsd_err_severity_t verbosity, const int create_output_logger); 372 373 /*! 374 * Configure the output logger. Choose STDOUT, STDERR and/or log to file. 375 * Optionally provide a log file name. 376 * 377 * @param output_flags : OR combination of required C_API_MSGLOGOUT_FLG_* flags. 378 * @param *log_file_name : optional filename if logging to file. Set to NULL if not needed. 379 * 380 * @return OCSD_C_API ocsd_err_t : Library error code - RCDTL_OK if successful. 381 */ 382 OCSD_C_API ocsd_err_t ocsd_def_errlog_config_output(const int output_flags, const char *log_file_name); 383 384 /*! 385 * Configure the library default error logger to send all strings it is outputting back to the client 386 * to allow printing within the client application. This is in additional to any other log destinations 387 * set in ocsd_def_errlog_init(). 388 * 389 * @param *p_context : opaque context pointer 390 * @param p_str_print_cb : client callback function to "print" logstring. 391 */ 392 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); 393 394 /*! 395 * Print a message via the library output printer - if enabled. 396 * 397 * @param *msg : Message to output. 398 * 399 */ 400 OCSD_C_API void ocsd_def_errlog_msgout(const char *msg); 401 402 /*! 403 * Convert an error code into a string. 404 * 405 * @param err : error code. 406 * @param buffer : buffer for return string 407 * @param buffer_size : length of buffer. 408 */ 409 OCSD_C_API void ocsd_err_str(const ocsd_err_t err, char *buffer, const int buffer_size); 410 411 /*! 412 * returns the last error logged by the system, with the related trace byte index, trace channel id, 413 * and any error message related string. 414 * If index or channel ID are not valid these will return OCSD_BAD_TRC_INDEX and OCSD_BAD_CS_SRC_ID. 415 * 416 * return value is the error code of the last logged error, OCSD_OK for no error available. 417 * 418 * @param index : returns trace byte index relating to error, or OCSD_BAD_TRC_INDEX 419 * @param chan_id : returns trace channel ID relating to error, or OCSD_BAD_CS_SRC_ID 420 * @param message : buffer to copy the last error message. 421 * @param message_len: length of message buffer. 422 */ 423 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); 424 425 /** @}*/ 426 427 /** @name Packet to string interface 428 429 @{*/ 430 431 /*! 432 * Take a packet structure and render a string representation of the packet data. 433 * 434 * Returns a '0' terminated string of (buffer_size - 1) length or less. 435 * 436 * @param pkt_protocol : Packet protocol type - used to interpret the packet pointer 437 * @param *p_pkt : pointer to a valid packet structure of protocol type. cast to void *. 438 * @param *buffer : character buffer for string. 439 * @param buffer_size : size of character buffer. 440 * 441 * @return ocsd_err_t : Library error code - RCDTL_OK if successful. 442 */ 443 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); 444 445 /*! 446 * Get a string representation of the generic trace element. 447 * 448 * @param *p_pkt : pointer to valid generic element structure. 449 * @param *buffer : character buffer for string. 450 * @param buffer_size : size of character buffer. 451 * 452 * @return ocsd_err_t : Library error code - RCDTL_OK if successful. 453 */ 454 OCSD_C_API ocsd_err_t ocsd_gen_elem_str(const ocsd_generic_trace_elem *p_pkt, char *buffer, const int buffer_size); 455 456 457 /*! 458 * Init a generic element with type, clearing any flags etc. 459 */ 460 OCSD_C_API void ocsd_gen_elem_init(ocsd_generic_trace_elem *p_pkt, const ocsd_gen_trc_elem_t elem_type); 461 462 /** @}*/ 463 464 /** @name Library packet and data printer control API 465 @brief Allows client to use libraries packet and data printers to log packets etc rather than attach callbacks 466 to packet output and use packet to string calls. 467 @{*/ 468 469 /*! 470 * Set a raw frame printer on the trace frame demuxer. Allows inspection of raw trace data frames for debug. 471 * Prints via the library default error logging mechanisms. 472 * 473 * The flags input determines the data printed. OR combination of one or both of: 474 * OCSD_DFRMTR_PACKED_RAW_OUT : Output the undemuxed raw data frames. 475 * OCSD_DFRMTR_UNPACKED_RAW_OUT : Output the raw data by trace ID after unpacking the frame. 476 * 477 * @param handle : Handle to decode tree. 478 * @param flags : indicates type of raw frames to print. 479 * 480 * @return ocsd_err_t : Library error code - RCDTL_OK if successful. 481 */ 482 OCSD_C_API ocsd_err_t ocsd_dt_set_raw_frame_printer(const dcd_tree_handle_t handle, int flags); 483 484 /*! 485 * Set a library printer on the generic element output of a full decoder. 486 * 487 * @param handle : Handle to decode tree. 488 * 489 * @return ocsd_err_t : Library error code - RCDTL_OK if successful. 490 */ 491 OCSD_C_API ocsd_err_t ocsd_dt_set_gen_elem_printer(const dcd_tree_handle_t handle); 492 493 /*! 494 * Attach a library printer to the packet processor. May be attached to the main packet output, or the monitor 495 * output if the main packet output is to be attached to a packet decoder in the datapath. 496 * 497 * @param handle : Handle to decode tree. 498 * @param cs_id : Coresight trace ID for stream to print. 499 * @param monitor: 0 to attach printer directly to datapath packet output, 1 to attach to packet monitor output 500 * 501 * @return ocsd_err_t : Library error code - RCDTL_OK if successful. 502 */ 503 OCSD_C_API ocsd_err_t ocsd_dt_set_pkt_protocol_printer(const dcd_tree_handle_t handle, uint8_t cs_id, int monitor); 504 505 /** @}*/ 506 507 508 /** @name Custom Decoder API functions 509 510 @{*/ 511 512 /** Register a custom decoder with the library 513 514 @param *name : Name under which to register the decoder. 515 @param *p_dcd_fact : Custom decoder factory structure. 516 517 @return ocsd_err_t : Library error code - RCDTL_OK if successful. 518 */ 519 OCSD_C_API ocsd_err_t ocsd_register_custom_decoder(const char *name, ocsd_extern_dcd_fact_t *p_dcd_fact); 520 521 /** Clear all registered decoders - library cleanup 522 523 @return ocsd_err_t : Library error code - RCDTL_OK if successful. 524 */ 525 OCSD_C_API ocsd_err_t ocsd_deregister_decoders(void); 526 527 /** Get a string representation of a custom protocol packet. 528 529 Specific function to extract the packet string for a custom protocol ID only. Custom IDs are allocated to decoder factories 530 during the ocsd_register_custom_decoder() process. 531 532 This function is called by ocsd_pkt_str() when the incoming protocol is a custom ID. 533 534 @param pkt_protocol : Packet protocol type - must be in the custom ID range ( >= OCSD_PROTOCOL_CUSTOM_0, < OCSD_PROTOCOL_END) 535 @param *p_pkt : pointer to a valid packet structure of protocol type. cast to void *. 536 @param *buffer : character buffer for string. 537 @param buffer_size : size of character buffer. 538 539 @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. 540 */ 541 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); 542 543 /** @}*/ 544 545 546 /** @}*/ 547 548 #endif // ARM_OPENCSD_C_API_H_INCLUDED 549 550 /* End of File opencsd_c_api.h */ 551