1 /*! 2 * \file ocsd_dcd_tree.h 3 * \brief OpenCSD : Trace Decode Tree. 4 * 5 * \copyright Copyright (c) 2015, ARM Limited. All Rights Reserved. 6 */ 7 8 9 /* 10 * Redistribution and use in source and binary forms, with or without modification, 11 * are permitted provided that the following conditions are met: 12 * 13 * 1. Redistributions of source code must retain the above copyright notice, 14 * this list of conditions and the following disclaimer. 15 * 16 * 2. Redistributions in binary form must reproduce the above copyright notice, 17 * this list of conditions and the following disclaimer in the documentation 18 * and/or other materials provided with the distribution. 19 * 20 * 3. Neither the name of the copyright holder nor the names of its contributors 21 * may be used to endorse or promote products derived from this software without 22 * specific prior written permission. 23 * 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND 25 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 26 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 27 * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 28 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 29 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 31 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 32 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34 */ 35 36 #ifndef ARM_OCSD_DCD_TREE_H_INCLUDED 37 #define ARM_OCSD_DCD_TREE_H_INCLUDED 38 39 #include <vector> 40 #include <list> 41 42 #include "opencsd.h" 43 #include "ocsd_dcd_tree_elem.h" 44 45 /** @defgroup dcd_tree OpenCSD Library : Trace Decode Tree. 46 @brief Create a multi source decode tree for a single trace capture buffer. 47 48 Use to create a connected set of decoder objects to decode a trace buffer. 49 There may be multiple trace sources within the capture buffer. 50 51 @{*/ 52 53 /*! 54 * @class DecodeTree 55 * @brief Class to manage the decoding of data from a single trace sink . 56 * 57 * Provides functionality to build a tree of decode objects capable of decoding 58 * multiple trace sources within a single trace sink (capture buffer). 59 * 60 */ 61 class DecodeTree : public ITrcDataIn 62 { 63 public: 64 /** @name Creation and Destruction 65 @{*/ 66 DecodeTree(); //!< default constructor 67 ~DecodeTree(); //!< default destructor 68 69 /*! 70 * @brief Create a decode tree. 71 * Automatically creates a trace frame deformatter if required and a default error log component. 72 * 73 * @param src_type : Data stream source type, can be CoreSight frame formatted trace, or single demuxed trace data stream, 74 * @param formatterCfgFlags : Configuration flags for trace de-formatter. 75 * 76 * @return DecodeTree * : pointer to the decode tree, 0 if creation failed. 77 */ 78 static DecodeTree *CreateDecodeTree(const ocsd_dcd_tree_src_t src_type, const uint32_t formatterCfgFlags); 79 80 /** @brief Destroy a decode tree */ 81 static void DestroyDecodeTree(DecodeTree *p_dcd_tree); 82 83 /** @}*/ 84 85 86 /** @name Error and element Logging 87 @{*/ 88 /** @brief The library default error logger */ getDefaultErrorLogger()89 static ocsdDefaultErrorLogger* getDefaultErrorLogger() { return &s_error_logger; }; 90 91 /** the current error logging interface in use */ getCurrentErrorLogI()92 static ITraceErrorLog *getCurrentErrorLogI() { return s_i_error_logger; }; 93 94 /** set an alternate error logging interface. */ 95 static void setAlternateErrorLogger(ITraceErrorLog *p_error_logger); 96 97 /** get the list of packet printers for this decode tree */ getPrinterList()98 std::vector<ItemPrinter *> &getPrinterList() { return m_printer_list; }; 99 100 /** add a protocol packet printer */ 101 ocsd_err_t addPacketPrinter(uint8_t CSID, bool bMonitor, ItemPrinter **ppPrinter); 102 103 /** add a raw frame printer */ 104 ocsd_err_t addRawFramePrinter(RawFramePrinter **ppPrinter, uint32_t flags); 105 106 /** add a generic element output printer */ 107 ocsd_err_t addGenElemPrinter(TrcGenericElementPrinter **ppPrinter); 108 109 110 111 /** @}*/ 112 113 114 /** @name Trace Data Path 115 @{*/ 116 /** @brief Trace Data input interface (ITrcDataIn) 117 118 Decode tree implements the data in interface : ITrcDataIn . 119 Captured raw trace data is passed into the deformatter and decoders via this method. 120 */ 121 virtual ocsd_datapath_resp_t TraceDataIn( const ocsd_datapath_op_t op, 122 const ocsd_trc_index_t index, 123 const uint32_t dataBlockSize, 124 const uint8_t *pDataBlock, 125 uint32_t *numBytesProcessed); 126 127 /*! 128 * @brief Decoded Trace output. 129 * 130 * Client trace analysis program attaches a generic trace element interface to 131 * receive the output from the trace decode operations. 132 * 133 * @param *i_gen_trace_elem : Pointer to the interface. 134 */ 135 void setGenTraceElemOutI(ITrcGenElemIn *i_gen_trace_elem); 136 137 /*! @brief Return the connected generic element interface */ getGenTraceElemOutI()138 ITrcGenElemIn *getGenTraceElemOutI() const { return m_i_gen_elem_out; }; 139 140 /** @}*/ 141 142 /** @name Decoder Management 143 @{*/ 144 145 /*! 146 * Creates a decoder that is registered with the library under the supplied name. 147 * createFlags determine if a full packet processor / packet decoder pair or 148 * packet processor only is created. 149 * Uses the supplied configuration structure. 150 * 151 * @param &decoderName : registered name of decoder 152 * @param createFlags : Decoder creation options. 153 * @param *pConfig : Pointer to a valid configuration structure for the named decoder. 154 * 155 * @return ocsd_err_t : Library error code or OCSD_OK if successful. 156 */ 157 ocsd_err_t createDecoder(const std::string &decoderName, const int createFlags, const CSConfig *pConfig); 158 159 /* */ 160 /*! 161 * Remove a decoder / packet processor attached to an Trace ID output on the frame de-mux. 162 * 163 * Once removed another decoder can be created that has a CSConfig using that ID. 164 * 165 * @param CSID : Trace ID to remove. 166 * 167 * @return ocsd_err_t : Library error code or OCSD_OK if successful. 168 */ 169 ocsd_err_t removeDecoder(const uint8_t CSID); 170 171 /*! 172 * Get the stats block for the channel indicated. 173 * Caller must check p_stats_block->version to esure that the block 174 * is filled in a compatible manner. 175 * 176 * @param CSID : Configured CoreSight trace ID for the decoder. 177 * @param p_stats_block: block pointer to set to reference the stats block. 178 * 179 * @return ocsd_err_t : Library error code - OCSD_OK if valid block pointer returned, 180 * OCSD_ERR_NOTINIT if decoder does not support stats counting. 181 */ 182 ocsd_err_t getDecoderStats(const uint8_t CSID, ocsd_decode_stats_t **p_stats_block); 183 184 /*! 185 * Reset the stats block for the chosens decode channel. 186 * stats block is reset independently of the decoder reset to allow counts across 187 * multiple decode runs. 188 * 189 * @param handle : Handle to decode tree. 190 * @param CSID : Configured CoreSight trace ID for the decoder. 191 * 192 * @return ocsd_err_t : Library error code - OCSD_OK if successful. 193 */ 194 ocsd_err_t resetDecoderStats(const uint8_t CSID); 195 196 /* get decoder elements currently in use */ 197 198 /*! 199 * Find a decode tree element associated with a specific CoreSight trace ID. * 200 */ 201 DecodeTreeElement *getDecoderElement(const uint8_t CSID) const; 202 /* iterate decoder elements */ 203 204 /*! 205 * Decode tree iteration. Return the first tree element 0 if no elements avaiable. 206 * 207 * @param &elemID : CoreSight Trace ID associated with this element 208 */ 209 DecodeTreeElement *getFirstElement(uint8_t &elemID); 210 /*! 211 * Return the next tree element - or 0 if no futher elements avaiable. 212 * 213 * @param &elemID : CoreSight Trace ID associated with this element 214 */ 215 DecodeTreeElement *getNextElement(uint8_t &elemID); 216 217 /* set key interfaces - attach / replace on any existing tree components */ 218 219 /*! 220 * Set an ARM instruction opcode decoder. 221 * 222 * @param *i_instr_decode : Pointer to the interface. 223 */ 224 void setInstrDecoder(IInstrDecode *i_instr_decode); 225 /*! 226 * Set a target memory access interface - used to access program image memory for instruction 227 * trace decode. 228 * 229 * @param *i_mem_access : Pointer to the interface. 230 */ 231 void setMemAccessI(ITargetMemAccess *i_mem_access); 232 233 234 /** @}*/ 235 236 /** @name Memory Access Mapper 237 238 A memory mapper is used to organise a collection of memory accessor objects that contain the 239 memory images for different areas of traced instruction memory. These areas could be the executed 240 program and a set of loaded .so libraries for example - each of which would have code sections in 241 different memory locations. 242 243 A memory accessor represents a snapshot of an area of memory as it appeared during trace capture, 244 for a given memory space. Memory spaces are described by the ocsd_mem_space_acc_t enum. The most 245 general memory space is OCSD_MEM_SPACE_ANY. This represents memory that can be secure or none-secure, 246 available at any exception level. 247 248 The memory mapper will not allow two accessors to overlap in the same memory space. 249 250 The trace decdoer will access memory with a memory space parameter that represents the current core 251 state - the mapper will find the closest memory space match for the address. 252 253 e.g. if the core is accessing secure EL3, then the most specialised matching space will be accessed. 254 If an EL3 space matches that will be used, otherwise the any secure, and finally _ANY. 255 256 It is no necessary for clients to register memory accessors for all spaces - _ANY will be sufficient 257 in many cases. 258 259 260 @{*/ 261 262 /* */ 263 /*! 264 * This creates a memory mapper within the decode tree. 265 * 266 * @param type : defaults to MEMACC_MAP_GLOBAL (only type available at present) 267 * 268 * @return ocsd_err_t : Library error code or OCSD_OK if successful. 269 */ 270 ocsd_err_t createMemAccMapper(memacc_mapper_t type = MEMACC_MAP_GLOBAL); 271 272 /*! 273 * Get a pointer to the memory mapper. Allows a client to add memory accessors directly to the mapper. 274 * @return TrcMemAccMapper : Pointer to the mapper. 275 */ getMemAccMapper()276 TrcMemAccMapper *getMemAccMapper() const { return m_default_mapper; }; 277 278 /*! 279 * Set an external mapper rather than create a mapper in the decode tree. 280 * Setting this will also destroy any internal mapper that was previously created. 281 * 282 * @param pMapper : pointer to the mapper to add. 283 */ 284 void setExternMemAccMapper(TrcMemAccMapper * pMapper); 285 286 /*! 287 * Return true if a mapper has been set (internal or external 288 */ hasMemAccMapper()289 const bool hasMemAccMapper() const { return (bool)(m_default_mapper != 0); }; 290 291 void logMappedRanges(); //!< Log the mapped memory ranges to the default message logger. 292 293 /*! Memory accessor cacheing 294 * 295 * Memory accessor uses caching to reduce the number of calls / callbacks for memory images 296 * This allows controlling / disabling of cacheing mechanisms. 297 * Error returned if cache limits exceeded (4096 byte page, 256 pages) 298 */ 299 ocsd_err_t setMemAccCacheing(const bool enable, const uint16_t page_size, const int nr_pages); 300 301 /** @}*/ 302 303 /** @name Memory Accessors 304 A memory accessor represents a snapshot of an area of memory as it appeared during trace capture. 305 306 Memory spaces represent either common global memory, or Secure / none-secure and EL specific spaces. 307 308 @{*/ 309 310 /*! 311 * Creates a memory accessor for a memory block in the supplied buffer and adds to the current mapper. 312 * 313 * @param address : Start address for the memory block in the memory map. 314 * @param mem_space : Memory space 315 * @param *p_mem_buffer : start of the buffer. 316 * @param mem_length : length of the buffer. 317 * 318 * @return ocsd_err_t : Library error code or OCSD_OK if successful. 319 */ 320 ocsd_err_t addBufferMemAcc(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const uint8_t *p_mem_buffer, const uint32_t mem_length); 321 322 /*! 323 * Creates a memory accessor for a memory block supplied as a contiguous binary data file, and adds to the current mapper. 324 * 325 * @param address : Start address for the memory block in the memory map. 326 * @param mem_space : Memory space 327 * @param &filepath : Path to the binary data file 328 * 329 * @return ocsd_err_t : Library error code or OCSD_OK if successful. 330 */ 331 ocsd_err_t addBinFileMemAcc(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const std::string &filepath); 332 333 /*! 334 * Creates a memory accessor for a memory block supplied as a one or more memory regions in a binary file. 335 * Region structures are created that describe the memory start address, the offset within the binary file 336 * for that address, and the length of the region. This accessor can be used to point to the code section 337 * in a program file for example. 338 * 339 * @param *region_array : array of valid memory regions in the file. 340 * @param num_regions : number of regions 341 * @param mem_space : Memory space 342 * @param &filepath : Path to the binary data file 343 * 344 * @return ocsd_err_t : Library error code or OCSD_OK if successful. 345 */ 346 ocsd_err_t addBinFileRegionMemAcc(const ocsd_file_mem_region_t *region_array, const int num_regions, const ocsd_mem_space_acc_t mem_space, const std::string &filepath); 347 348 349 /*! 350 * Updates/adds to a memory accessor for a memory block supplied as a one or more memory regions in a binary file. 351 * Region structures are created that describe the memory start address, the offset within the binary file 352 * for that address, and the length of the region. This accessor can be used to point to the code section 353 * in a program file for example. 354 * 355 * @param *region_array : array of valid memory regions in the file. 356 * @param num_regions : number of regions 357 * @param mem_space : Memory space 358 * @param &filepath : Path to the binary data file 359 * 360 * @return ocsd_err_t : Library error code or OCSD_OK if successful. 361 */ 362 ocsd_err_t updateBinFileRegionMemAcc(const ocsd_file_mem_region_t *region_array, const int num_regions, const ocsd_mem_space_acc_t mem_space, const std::string &filepath); 363 364 /*! 365 * This memory accessor allows the client to supply a callback function for the region 366 * defined by the start and end addresses. This can be used to supply a custom memory accessor, 367 * or to directly access memory if the decode is running live on a target system. 368 * 369 * @param st_address : start address of region. 370 * @param en_address : end address of region. 371 * @param mem_space : Memory space 372 * @param p_cb_func : Callback function 373 * @param *p_context : client supplied context information 374 * 375 * @return ocsd_err_t : Library error code or OCSD_OK if successful. 376 */ 377 ocsd_err_t addCallbackMemAcc(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); 378 ocsd_err_t addCallbackIDMemAcc(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); 379 380 /*! 381 * Remove the memory accessor from the map, that begins at the given address, for the memory space provided. 382 * 383 * @param address : Start address of the memory accessor. 384 * @param mem_space : Memory space for the memory accessor. 385 * 386 * @return ocsd_err_t : Library error code or OCSD_OK if successful. 387 */ 388 ocsd_err_t removeMemAccByAddress(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space); 389 390 /** @}*/ 391 392 /** @name CoreSight Trace Frame De-mux 393 @{*/ 394 395 //! Get the Trace Frame de-mux. getFrameDeformatter()396 TraceFormatterFrameDecoder *getFrameDeformatter() const { return m_frame_deformatter_root; }; 397 398 399 /*! @brief ID filtering - sets the output filter on the trace deformatter. 400 401 Only supplied IDs will be decoded. 402 403 No effect if no decoder attached for the ID 404 405 @param ids : Vector of CS Trace IDs 406 */ 407 ocsd_err_t setIDFilter(std::vector<uint8_t> &ids); // only supplied IDs will be decoded 408 409 ocsd_err_t clearIDFilter(); //!< remove filter, all IDs will be decoded 410 411 /** @}*/ 412 413 private: 414 bool initialise(const ocsd_dcd_tree_src_t type, uint32_t formatterCfgFlags); usingFormatter()415 const bool usingFormatter() const { return (bool)(m_dcd_tree_type == OCSD_TRC_SRC_FRAME_FORMATTED); }; 416 void setSingleRoot(TrcPktProcI *pComp); 417 ocsd_err_t createDecodeElement(const uint8_t CSID); 418 void destroyDecodeElement(const uint8_t CSID); 419 void destroyMemAccMapper(); 420 ocsd_err_t initCallbackMemAcc(const ocsd_vaddr_t st_address, const ocsd_vaddr_t en_address, 421 const ocsd_mem_space_acc_t mem_space, void *p_cb_func, bool IDfn, const void *p_context); 422 TrcPktProcI *getPktProcI(const uint8_t CSID); 423 424 ocsd_dcd_tree_src_t m_dcd_tree_type; 425 426 IInstrDecode *m_i_instr_decode; 427 ITargetMemAccess *m_i_mem_access; 428 ITrcGenElemIn *m_i_gen_elem_out; //!< Output interface for generic elements from decoder. 429 430 ITrcDataIn* m_i_decoder_root; /*!< root decoder object interface - either deformatter or single packet processor */ 431 432 TraceFormatterFrameDecoder *m_frame_deformatter_root; 433 434 DecodeTreeElement *m_decode_elements[0x80]; 435 436 uint8_t m_decode_elem_iter; 437 438 TrcMemAccMapper *m_default_mapper; //!< the mem acc mapper to use 439 bool m_created_mapper; //!< true if created by decode tree object 440 441 std::vector<ItemPrinter *> m_printer_list; //!< list of packet printers. 442 443 /* global error logger - all sources */ 444 static ITraceErrorLog *s_i_error_logger; 445 static std::list<DecodeTree *> s_trace_dcd_trees; 446 447 /**! default error logger */ 448 static ocsdDefaultErrorLogger s_error_logger; 449 450 /**! default instruction decoder */ 451 static TrcIDecode s_instruction_decoder; 452 453 /**! demux stats block */ 454 ocsd_demux_stats_t m_demux_stats; 455 }; 456 457 /** @}*/ 458 459 #endif // ARM_OCSD_DCD_TREE_H_INCLUDED 460 461 /* End of File ocsd_dcd_tree.h */ 462