1*c120c564SAndrew Turner /* 2*c120c564SAndrew Turner * \file ocsd_c_api_custom.h 3*c120c564SAndrew Turner * \brief OpenCSD : Custom decoder interface types and structures 4*c120c564SAndrew Turner * 5*c120c564SAndrew Turner * \copyright Copyright (c) 2016, ARM Limited. All Rights Reserved. 6*c120c564SAndrew Turner */ 7*c120c564SAndrew Turner 8*c120c564SAndrew Turner /* 9*c120c564SAndrew Turner * Redistribution and use in source and binary forms, with or without modification, 10*c120c564SAndrew Turner * are permitted provided that the following conditions are met: 11*c120c564SAndrew Turner * 12*c120c564SAndrew Turner * 1. Redistributions of source code must retain the above copyright notice, 13*c120c564SAndrew Turner * this list of conditions and the following disclaimer. 14*c120c564SAndrew Turner * 15*c120c564SAndrew Turner * 2. Redistributions in binary form must reproduce the above copyright notice, 16*c120c564SAndrew Turner * this list of conditions and the following disclaimer in the documentation 17*c120c564SAndrew Turner * and/or other materials provided with the distribution. 18*c120c564SAndrew Turner * 19*c120c564SAndrew Turner * 3. Neither the name of the copyright holder nor the names of its contributors 20*c120c564SAndrew Turner * may be used to endorse or promote products derived from this software without 21*c120c564SAndrew Turner * specific prior written permission. 22*c120c564SAndrew Turner * 23*c120c564SAndrew Turner * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND 24*c120c564SAndrew Turner * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 25*c120c564SAndrew Turner * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 26*c120c564SAndrew Turner * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 27*c120c564SAndrew Turner * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 28*c120c564SAndrew Turner * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 29*c120c564SAndrew Turner * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 30*c120c564SAndrew Turner * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 31*c120c564SAndrew Turner * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 32*c120c564SAndrew Turner * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33*c120c564SAndrew Turner */ 34*c120c564SAndrew Turner #ifndef ARM_OCSD_C_API_CUSTOM_H_INCLUDED 35*c120c564SAndrew Turner #define ARM_OCSD_C_API_CUSTOM_H_INCLUDED 36*c120c564SAndrew Turner 37*c120c564SAndrew Turner #include "ocsd_c_api_types.h" 38*c120c564SAndrew Turner 39*c120c564SAndrew Turner 40*c120c564SAndrew Turner /** @defgroup ocsd_ext_dcd OpenCSD Library : Custom External Decoder C-API 41*c120c564SAndrew Turner @brief Set of types, structures and interfaces for attaching custom decoders via the C-API 42*c120c564SAndrew Turner 43*c120c564SAndrew Turner These types, functions and structures define the required API between a custom external decoder 44*c120c564SAndrew Turner and the library, which will allow the decoder to interact with the library and use library 45*c120c564SAndrew Turner resources in the same way as the built-in decoders. 46*c120c564SAndrew Turner 47*c120c564SAndrew Turner The external decoder must implement:- 48*c120c564SAndrew Turner - A set of factory functions that allow the creation and destruction of decoder instances. 49*c120c564SAndrew Turner - A set of call-in and call-back functions plus data structures allowing interaction with the library. 50*c120c564SAndrew Turner 51*c120c564SAndrew Turner @{*/ 52*c120c564SAndrew Turner 53*c120c564SAndrew Turner 54*c120c564SAndrew Turner /**@name External decoder - Input Interfaces 55*c120c564SAndrew Turner @{*/ 56*c120c564SAndrew Turner 57*c120c564SAndrew Turner /* Custom decoder C-API interface types. */ 58*c120c564SAndrew Turner 59*c120c564SAndrew Turner /** Raw trace data input function - a decoder must have one of these 60*c120c564SAndrew Turner Implements ITrcDataIn with the addition of a decoder handle to provide context in the decoder. 61*c120c564SAndrew Turner */ 62*c120c564SAndrew Turner typedef ocsd_datapath_resp_t (* fnTraceDataIn)( const void *decoder_handle, 63*c120c564SAndrew Turner const ocsd_datapath_op_t op, 64*c120c564SAndrew Turner const ocsd_trc_index_t index, 65*c120c564SAndrew Turner const uint32_t dataBlockSize, 66*c120c564SAndrew Turner const uint8_t *pDataBlock, 67*c120c564SAndrew Turner uint32_t *numBytesProcessed); 68*c120c564SAndrew Turner 69*c120c564SAndrew Turner /** Function to update the in-use flags for the packet sinks 70*c120c564SAndrew Turner 71*c120c564SAndrew Turner Defines if the fnPktMonCB or fnPktDataSinkCB callbacks are in use by the library. 72*c120c564SAndrew Turner If so then it is expected that the decoder should call them when trace protocol packets are generated. 73*c120c564SAndrew Turner 74*c120c564SAndrew Turner This function must be implemented in the decoder. 75*c120c564SAndrew Turner 76*c120c564SAndrew Turner @param decoder_handle : handle for decoder accessed by this call. 77*c120c564SAndrew Turner @param flags: Values indicating interfaces in use / not in use. [ OCSD_CUST_DCD_PKT_CB_USE_MON or OCSD_CUST_DCD_PKT_CB_USE_SINK] 78*c120c564SAndrew Turner */ 79*c120c564SAndrew Turner typedef void (* fnUpdatePktMonFlags)(const void *decoder_handle, const int flags); 80*c120c564SAndrew Turner 81*c120c564SAndrew Turner 82*c120c564SAndrew Turner 83*c120c564SAndrew Turner /** Flag to indicate the the packet monitor (fnPktMonCB) is in use in the library */ 84*c120c564SAndrew Turner #define OCSD_CUST_DCD_PKT_CB_USE_MON 0x1 85*c120c564SAndrew Turner 86*c120c564SAndrew Turner /** Flag to indicate the the packet sink (fnPktDataSinkCB) is in use in the library - only if trace packet processing only mode. */ 87*c120c564SAndrew Turner #define OCSD_CUST_DCD_PKT_CB_USE_SINK 0x2 88*c120c564SAndrew Turner 89*c120c564SAndrew Turner /** Owned by the library instance object, this structure is filled in by the ocsd_extern_dcd_fact_t createDecoder() function. */ 90*c120c564SAndrew Turner typedef struct _ocsd_extern_dcd_inst { 91*c120c564SAndrew Turner /* Mandatory decoder call back functions - library initialisation will fail without these. */ 92*c120c564SAndrew Turner fnTraceDataIn fn_data_in; /**< raw trace data input function to decoder */ 93*c120c564SAndrew Turner fnUpdatePktMonFlags fn_update_pkt_mon; /**< update the packet monitor / sink usage flags */ 94*c120c564SAndrew Turner 95*c120c564SAndrew Turner /* Decoder instance data */ 96*c120c564SAndrew Turner void *decoder_handle; /**< Instance handle for the decoder - used by library to call the decoder call in functions */ 97*c120c564SAndrew Turner char *p_decoder_name; /**< type name of the decoder - may be used in logging */ 98*c120c564SAndrew Turner uint8_t cs_id; /**< Coresight ID for the instance - extracted from the config on creation. */ 99*c120c564SAndrew Turner 100*c120c564SAndrew Turner } ocsd_extern_dcd_inst_t; 101*c120c564SAndrew Turner 102*c120c564SAndrew Turner /** @}*/ 103*c120c564SAndrew Turner 104*c120c564SAndrew Turner 105*c120c564SAndrew Turner /**@name External decoder - Callback Interfaces 106*c120c564SAndrew Turner @{*/ 107*c120c564SAndrew Turner 108*c120c564SAndrew Turner 109*c120c564SAndrew Turner /** callback function to connect into the generic element output point 110*c120c564SAndrew Turner Implements ITrcGenElemIn::TraceElemIn with addition of library context pointer. 111*c120c564SAndrew Turner */ 112*c120c564SAndrew Turner typedef ocsd_datapath_resp_t (* fnGenElemOpCB)( const void *lib_context, 113*c120c564SAndrew Turner const ocsd_trc_index_t index_sop, 114*c120c564SAndrew Turner const uint8_t trc_chan_id, 115*c120c564SAndrew Turner const ocsd_generic_trace_elem *elem); 116*c120c564SAndrew Turner 117*c120c564SAndrew Turner /** callback functions to connect into the library error logging mechanism 118*c120c564SAndrew Turner Implements ITraceErrorLog::LogError with addition of library context pointer. 119*c120c564SAndrew Turner */ 120*c120c564SAndrew Turner typedef void (* fnLogErrorCB)( const void *lib_context, 121*c120c564SAndrew Turner const ocsd_err_severity_t filter_level, 122*c120c564SAndrew Turner const ocsd_err_t code, 123*c120c564SAndrew Turner const ocsd_trc_index_t idx, 124*c120c564SAndrew Turner const uint8_t chan_id, 125*c120c564SAndrew Turner const char *pMsg); 126*c120c564SAndrew Turner 127*c120c564SAndrew Turner /** callback functions to connect into the library error logging mechanism 128*c120c564SAndrew Turner Implements ITraceErrorLog::LogMessage with addition of library context pointer. 129*c120c564SAndrew Turner */ 130*c120c564SAndrew Turner typedef void (* fnLogMsgCB)(const void *lib_context, const ocsd_err_severity_t filter_level, const char *msg); 131*c120c564SAndrew Turner 132*c120c564SAndrew Turner /** callback function to connect an ARM instruction decoder 133*c120c564SAndrew Turner Implements IInstrDecode::DecodeInstruction with addition of library context pointer. 134*c120c564SAndrew Turner */ 135*c120c564SAndrew Turner typedef ocsd_err_t (* fnDecodeArmInstCB)(const void *lib_context, ocsd_instr_info *instr_info); 136*c120c564SAndrew Turner 137*c120c564SAndrew Turner /** callback function to connect the memory accessor interface 138*c120c564SAndrew Turner Implements ITargetMemAccess::ReadTargetMemory with addition of library context pointer. 139*c120c564SAndrew Turner */ 140*c120c564SAndrew Turner typedef ocsd_err_t (* fnMemAccessCB)(const void *lib_context, 141*c120c564SAndrew Turner const ocsd_vaddr_t address, 142*c120c564SAndrew Turner const uint8_t cs_trace_id, 143*c120c564SAndrew Turner const ocsd_mem_space_acc_t mem_space, 144*c120c564SAndrew Turner uint32_t *num_bytes, 145*c120c564SAndrew Turner uint8_t *p_buffer); 146*c120c564SAndrew Turner 147*c120c564SAndrew Turner /** callback function to connect to the packet monitor interface of the packet processor 148*c120c564SAndrew Turner Implements IPktRawDataMon::RawPacketDataMon <void> with addition of library context pointer. 149*c120c564SAndrew Turner */ 150*c120c564SAndrew Turner typedef void (* fnPktMonCB)( const void *lib_context, 151*c120c564SAndrew Turner const ocsd_datapath_op_t op, 152*c120c564SAndrew Turner const ocsd_trc_index_t index_sop, 153*c120c564SAndrew Turner const void *pkt, 154*c120c564SAndrew Turner const uint32_t size, 155*c120c564SAndrew Turner const uint8_t *p_data); 156*c120c564SAndrew Turner 157*c120c564SAndrew Turner /** callback function to connect to the packet sink interface, on the main decode 158*c120c564SAndrew Turner data path - use if decoder created as packet processor only 159*c120c564SAndrew Turner 160*c120c564SAndrew Turner Implements IPktDataIn::PacketDataIn <void> with addition of library context pointer. 161*c120c564SAndrew Turner */ 162*c120c564SAndrew Turner typedef ocsd_datapath_resp_t (* fnPktDataSinkCB)( const void *lib_context, 163*c120c564SAndrew Turner const ocsd_datapath_op_t op, 164*c120c564SAndrew Turner const ocsd_trc_index_t index_sop, 165*c120c564SAndrew Turner const void *pkt); 166*c120c564SAndrew Turner 167*c120c564SAndrew Turner /** 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. */ 168*c120c564SAndrew Turner typedef struct _ocsd_extern_dcd_cb_fns { 169*c120c564SAndrew Turner /* Callback functions */ 170*c120c564SAndrew Turner fnGenElemOpCB fn_gen_elem_out; /**< Callback to output a generic element. */ 171*c120c564SAndrew Turner fnLogErrorCB fn_log_error; /**< Callback to output an error. */ 172*c120c564SAndrew Turner fnLogMsgCB fn_log_msg; /**< Callback to output a message. */ 173*c120c564SAndrew Turner fnDecodeArmInstCB fn_arm_instruction_decode; /**< Callback to decode an ARM instruction. */ 174*c120c564SAndrew Turner fnMemAccessCB fn_memory_access; /**< Callback to access memory images related to the trace capture. */ 175*c120c564SAndrew Turner fnPktMonCB fn_packet_mon; /**< Callback to output trace packet to packet monitor. */ 176*c120c564SAndrew Turner fnPktDataSinkCB fn_packet_data_sink; /**< Callback to output trace packet to packet sink - if in pack processing only mode. */ 177*c120c564SAndrew Turner /* CB in use flags. */ 178*c120c564SAndrew Turner int packetCBFlags; /**< Flags to indicate if the packet sink / packet monitor callbacks are in use. ( OCSD_CUST_DCD_PKT_CB_USE_MON / OCSD_CUST_DCD_PKT_CB_USE_SINK) */ 179*c120c564SAndrew Turner /* library context */ 180*c120c564SAndrew Turner const void *lib_context; /**< library context pointer - use in callbacks to allow the library to load the correct context data. */ 181*c120c564SAndrew Turner } ocsd_extern_dcd_cb_fns; 182*c120c564SAndrew Turner 183*c120c564SAndrew Turner /** @}*/ 184*c120c564SAndrew Turner 185*c120c564SAndrew Turner /**@name External decoder - Decoder Factory 186*c120c564SAndrew Turner @{*/ 187*c120c564SAndrew Turner 188*c120c564SAndrew Turner /** Function to create a decoder instance 189*c120c564SAndrew Turner 190*c120c564SAndrew Turner Create a decoder instance according to the create_flags parameter and the supplied decoder_cfg structure. 191*c120c564SAndrew Turner Fill in the p_decoder_inst structure, copy the p_lib_callbacks information for use in the decoder instance. 192*c120c564SAndrew Turner 193*c120c564SAndrew Turner Create flags can be: 194*c120c564SAndrew Turner - 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. 195*c120c564SAndrew Turner - 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. 196*c120c564SAndrew Turner 197*c120c564SAndrew Turner @param create_flags : Sets the decoder operating mode. 198*c120c564SAndrew Turner @param *decoder_cfg : Hardware specific configuration for this trace element. 199*c120c564SAndrew Turner @param *p_lib_callbacks : Library callbacks plus context pointer. 200*c120c564SAndrew Turner @param *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. 201*c120c564SAndrew Turner 202*c120c564SAndrew Turner @return ocsd_err_t : Library error code - RCDTL_OK if successful 203*c120c564SAndrew Turner */ 204*c120c564SAndrew Turner 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); 205*c120c564SAndrew Turner 206*c120c564SAndrew Turner /** Function to destroy a decoder instance indicated by decoder handle. 207*c120c564SAndrew Turner 208*c120c564SAndrew Turner @param decoder_handle : Instance handle for decoder. 209*c120c564SAndrew Turner 210*c120c564SAndrew Turner @return ocsd_err_t : Library error code - RCDTL_OK if successful 211*c120c564SAndrew Turner */ 212*c120c564SAndrew Turner typedef ocsd_err_t (* fnDestroyCustomDecoder)(const void *decoder_handle); 213*c120c564SAndrew Turner 214*c120c564SAndrew Turner /** Function to extract the CoreSight Trace ID from the configuration structure. 215*c120c564SAndrew Turner 216*c120c564SAndrew Turner @param *decoder_cfg : Hardware specific configuration for this trace element. 217*c120c564SAndrew Turner @parma *p_csid : location to write CoreSight Trace ID value. 218*c120c564SAndrew Turner 219*c120c564SAndrew Turner @return ocsd_err_t : Library error code - RCDTL_OK if successful 220*c120c564SAndrew Turner */ 221*c120c564SAndrew Turner typedef ocsd_err_t (* fnGetCSIDFromConfig)(const void *decoder_cfg, unsigned char *p_csid); 222*c120c564SAndrew Turner 223*c120c564SAndrew Turner /** Function to convert a protocol specific trace packet to human readable string 224*c120c564SAndrew Turner 225*c120c564SAndrew Turner @param *trc_pkt : protocol specific packet structure. 226*c120c564SAndrew Turner @param *buffer : buffer to fill with string. 227*c120c564SAndrew Turner @param buflen : length of string buffer. 228*c120c564SAndrew Turner 229*c120c564SAndrew Turner @return ocsd_err_t : Library error code - RCDTL_OK if successful 230*c120c564SAndrew Turner */ 231*c120c564SAndrew Turner typedef ocsd_err_t (* fnPacketToString)(const void *trc_pkt, char *buffer, const int buflen); 232*c120c564SAndrew Turner 233*c120c564SAndrew Turner /** set of functions and callbacks to create an extern custom decoder in the library 234*c120c564SAndrew Turner via the C API interface. This structure is registered with the library by name and 235*c120c564SAndrew Turner then decoders of the type can be created on the decode tree. 236*c120c564SAndrew Turner */ 237*c120c564SAndrew Turner typedef struct _ocsd_extern_dcd_fact { 238*c120c564SAndrew Turner fnCreateCustomDecoder createDecoder; /**< Function pointer to create a decoder instance. */ 239*c120c564SAndrew Turner fnDestroyCustomDecoder destroyDecoder; /**< Function pointer to destroy a decoder instance. */ 240*c120c564SAndrew Turner fnGetCSIDFromConfig csidFromConfig; /**< Function pointer to extract the CSID from a config structure */ 241*c120c564SAndrew Turner fnPacketToString pktToString; /**< Function pointer to print a trace protocol packet in this decoder */ 242*c120c564SAndrew Turner 243*c120c564SAndrew Turner ocsd_trace_protocol_t protocol_id; /**< protocol ID assigned during registration. */ 244*c120c564SAndrew Turner } ocsd_extern_dcd_fact_t; 245*c120c564SAndrew Turner 246*c120c564SAndrew Turner /** @}*/ 247*c120c564SAndrew Turner 248*c120c564SAndrew Turner /** @}*/ 249*c120c564SAndrew Turner 250*c120c564SAndrew Turner 251*c120c564SAndrew Turner #endif // ARM_OCSD_C_API_CUSTOM_H_INCLUDED 252*c120c564SAndrew Turner 253*c120c564SAndrew Turner /* End of File ocsd_c_api_custom.h */ 254