contrib/opencsd/decoder/include/opencsd/c_api/ocsd_c_api_custom.h

   1 /*
   2  * \file       ocsd_c_api_custom.h
   3  * \brief      OpenCSD : Custom decoder interface types and structures
   4  *
   5  * \copyright  Copyright (c) 2016, 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 #ifndef ARM_OCSD_C_API_CUSTOM_H_INCLUDED
  35 #define ARM_OCSD_C_API_CUSTOM_H_INCLUDED
  36
  37 #include "ocsd_c_api_types.h"
  38
  39
  40  /** @defgroup ocsd_ext_dcd OpenCSD Library : Custom External Decoder C-API
  41  @brief Set of types, structures and interfaces for attaching custom decoders via the C-API
  42
  43  These types, functions and structures define the required API between a custom external decoder
  44  and the library, which will allow the decoder to interact with the library and use library
  45  resources in the same way as the built-in decoders.
  46
  47  The external decoder must implement:-
  48  - A set of factory functions that allow the creation and destruction of decoder instances.
  49  - A set of call-in and call-back functions plus data structures allowing interaction with the library.
  50
  51  @{*/
  52
  53
  54 /**@name External decoder - Input Interfaces
  55 @{*/
  56
  57 /* Custom decoder C-API interface types. */
  58
  59 /** Raw trace data input function - a decoder must have one of these
  60     Implements ITrcDataIn with the addition of a decoder handle to provide context in the decoder.
  61  */
  62 typedef ocsd_datapath_resp_t (* fnTraceDataIn)( const void *decoder_handle,
  63                                                 const ocsd_datapath_op_t op,
  64                                                 const ocsd_trc_index_t index,
  65                                                 const uint32_t dataBlockSize,
  66                                                 const uint8_t *pDataBlock,
  67                                                 uint32_t *numBytesProcessed);
  68
  69 /** Function to update the in-use flags for the packet sinks
  70
  71     Defines if the fnPktMonCB or fnPktDataSinkCB callbacks are in use by the library.
  72     If so then it is expected that the decoder should call them when trace protocol packets are generated.
  73
  74     This function must be implemented in the decoder.
  75
  76     @param decoder_handle : handle for decoder accessed by this call.
  77     @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 */
  79 typedef void (* fnUpdatePktMonFlags)(const void *decoder_handle, const int flags);
  80
  81
  82
  83 /** Flag to indicate the the packet monitor (fnPktMonCB) is in use in the library */
  84 #define OCSD_CUST_DCD_PKT_CB_USE_MON  0x1
  85
  86 /** Flag to indicate the the packet sink (fnPktDataSinkCB) is in use in the library - only if trace packet processing only mode. */
  87 #define OCSD_CUST_DCD_PKT_CB_USE_SINK 0x2
  88
  89 /** Owned by the library instance object, this structure is filled in by the ocsd_extern_dcd_fact_t createDecoder() function. */
  90 typedef struct _ocsd_extern_dcd_inst {
  91     /* Mandatory decoder call back functions - library initialisation will fail without these. */
  92     fnTraceDataIn       fn_data_in;         /**< raw trace data input function to decoder */
  93     fnUpdatePktMonFlags fn_update_pkt_mon;  /**< update the packet monitor / sink usage flags */
  94
  95                                             /* Decoder instance data */
  96     void *decoder_handle;   /**< Instance handle for the decoder  - used by library to call the decoder call in functions */
  97     char *p_decoder_name;   /**< type name of the decoder - may be used in logging */
  98     uint8_t cs_id;          /**< Coresight ID for the instance - extracted from the config on creation. */
  99
 100 } ocsd_extern_dcd_inst_t;
 101
 102 /** @}*/
 103
 104
 105 /**@name External decoder - Callback Interfaces
 106 @{*/
 107
 108
 109 /** callback function to connect into the generic element output point
 110   Implements ITrcGenElemIn::TraceElemIn with addition of library context pointer.
 111   */
 112 typedef ocsd_datapath_resp_t (* fnGenElemOpCB)( const void *lib_context,
 113                                                 const ocsd_trc_index_t index_sop,
 114                                                 const uint8_t trc_chan_id,
 115                                                 const ocsd_generic_trace_elem *elem);
 116
 117 /** callback functions to connect into the library error logging mechanism
 118     Implements ITraceErrorLog::LogError with addition of library context pointer.
 119 */
 120 typedef void (* fnLogErrorCB)(  const void *lib_context,
 121                                 const ocsd_err_severity_t filter_level,
 122                                 const ocsd_err_t code,
 123                                 const ocsd_trc_index_t idx,
 124                                 const uint8_t chan_id,
 125                                 const char *pMsg);
 126
 127 /** callback functions to connect into the library error logging mechanism
 128     Implements ITraceErrorLog::LogMessage with addition of library context pointer.
 129 */
 130 typedef void (* fnLogMsgCB)(const void *lib_context, const ocsd_err_severity_t filter_level, const char *msg);
 131
 132 /** callback function to connect an ARM instruction decoder
 133     Implements IInstrDecode::DecodeInstruction with addition of library context pointer.
 134 */
 135 typedef ocsd_err_t (* fnDecodeArmInstCB)(const void *lib_context, ocsd_instr_info *instr_info);
 136
 137 /** callback function to connect the memory accessor interface
 138     Implements ITargetMemAccess::ReadTargetMemory with addition of library context pointer.
 139 */
 140 typedef ocsd_err_t (* fnMemAccessCB)(const void *lib_context,
 141                                      const ocsd_vaddr_t address,
 142                                      const uint8_t cs_trace_id,
 143                                      const ocsd_mem_space_acc_t mem_space,
 144                                      uint32_t *num_bytes,
 145                                      uint8_t *p_buffer);
 146
 147 /** callback function to connect to the packet monitor interface of the packet processor
 148     Implements IPktRawDataMon::RawPacketDataMon <void> with addition of library context pointer.
 149 */
 150 typedef void (* fnPktMonCB)(  const void *lib_context,
 151                               const ocsd_datapath_op_t op,
 152                               const ocsd_trc_index_t index_sop,
 153                               const void *pkt,
 154                               const uint32_t size,
 155                               const uint8_t *p_data);
 156
 157 /** callback function to connect to the packet sink interface, on the main decode
 158     data path - use if decoder created as packet processor only
 159
 160     Implements IPktDataIn::PacketDataIn <void> with addition of library context pointer.
 161 */
 162 typedef ocsd_datapath_resp_t (* fnPktDataSinkCB)( const void *lib_context,
 163                                                   const ocsd_datapath_op_t op,
 164                                                   const ocsd_trc_index_t index_sop,
 165                                                   const void *pkt);
 166
 167 /** 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 typedef struct _ocsd_extern_dcd_cb_fns {
 169 /* Callback functions */
 170     fnGenElemOpCB       fn_gen_elem_out;            /**< Callback to output a generic element. */
 171     fnLogErrorCB        fn_log_error;               /**< Callback to output an error.  */
 172     fnLogMsgCB          fn_log_msg;                 /**< Callback to output a message. */
 173     fnDecodeArmInstCB   fn_arm_instruction_decode;  /**< Callback to decode an ARM instruction. */
 174     fnMemAccessCB       fn_memory_access;           /**< Callback to access memory images related to the trace capture. */
 175     fnPktMonCB          fn_packet_mon;              /**< Callback to output trace packet to packet monitor. */
 176     fnPktDataSinkCB     fn_packet_data_sink;        /**< Callback to output trace packet to packet sink - if in pack processing only mode. */
 177 /* CB in use flags. */
 178     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 /* library context */
 180     const void *lib_context;  /**< library context pointer - use in callbacks to allow the library to load the correct context data. */
 181 } ocsd_extern_dcd_cb_fns;
 182
 183 /** @}*/
 184
 185 /**@name External decoder - Decoder Factory
 186 @{*/
 187
 188 /** Function to create a decoder instance
 189
 190     Create a decoder instance according to the create_flags parameter and the supplied decoder_cfg structure.
 191     Fill in the p_decoder_inst structure, copy the p_lib_callbacks information for use in the decoder instance.
 192
 193     Create flags can be:
 194     - 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     - 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
 197     @param create_flags : Sets the decoder operating mode.
 198     @param *decoder_cfg : Hardware specific configuration for this trace element.
 199     @param *p_lib_callbacks : Library callbacks plus context pointer.
 200     @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
 202     @return ocsd_err_t  : Library error code -  RCDTL_OK if successful
 203 */
 204 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
 206 /** Function to destroy a decoder instance indicated by decoder handle.
 207
 208     @param decoder_handle : Instance handle for decoder.
 209
 210     @return ocsd_err_t  : Library error code -  RCDTL_OK if successful
 211 */
 212 typedef ocsd_err_t (* fnDestroyCustomDecoder)(const void *decoder_handle);
 213
 214 /** Function to extract the CoreSight Trace ID from the configuration structure.
 215
 216     @param *decoder_cfg : Hardware specific configuration for this trace element.
 217     @parma *p_csid : location to write CoreSight Trace ID value.
 218
 219     @return ocsd_err_t  : Library error code -  RCDTL_OK if successful
 220 */
 221 typedef ocsd_err_t (* fnGetCSIDFromConfig)(const void *decoder_cfg, unsigned char *p_csid);
 222
 223 /** Function to convert a protocol specific trace packet to human readable string
 224
 225     @param *trc_pkt : protocol specific packet structure.
 226     @param *buffer  : buffer to fill with string.
 227     @param  buflen  : length of string buffer.
 228
 229     @return ocsd_err_t  : Library error code -  RCDTL_OK if successful
 230 */
 231 typedef ocsd_err_t (* fnPacketToString)(const void *trc_pkt, char *buffer, const int buflen);
 232
 233 /** set of functions and callbacks to create an extern custom decoder in the library
 234     via the C API interface. This structure is registered with the library by name and
 235     then decoders of the type can be created on the decode tree.
 236 */
 237 typedef struct _ocsd_extern_dcd_fact {
 238     fnCreateCustomDecoder createDecoder;    /**< Function pointer to create a decoder instance. */
 239     fnDestroyCustomDecoder destroyDecoder;  /**< Function pointer to destroy a decoder instance. */
 240     fnGetCSIDFromConfig csidFromConfig;     /**< Function pointer to extract the CSID from a config structure */
 241     fnPacketToString pktToString;           /**< Function pointer to print a trace protocol packet in this decoder */
 242
 243     ocsd_trace_protocol_t protocol_id;  /**< protocol ID assigned during registration. */
 244 } ocsd_extern_dcd_fact_t;
 245
 246 /** @}*/
 247
 248 /** @}*/
 249
 250
 251 #endif // ARM_OCSD_C_API_CUSTOM_H_INCLUDED
 252
 253 /* End of File ocsd_c_api_custom.h */