DecodeTree Class Reference
OpenCSD Library : Trace Decode Tree.

Class to manage the decoding of data from a single trace sink . More...

`#include <ocsd_dcd_tree.h>`

Inheritance diagram for DecodeTree:
[legend]
Collaboration diagram for DecodeTree:
[legend]

## Public Member Functions

Trace Data Path
virtual ocsd_datapath_resp_t | TraceDataIn (const ocsd_datapath_op_t op, const ocsd_trc_index_t index, const uint32_t dataBlockSize, const uint8_t *pDataBlock, uint32_t *numBytesProcessed)
| Trace Data input interface (ITrcDataIn) More...
void | setGenTraceElemOutI (ITrcGenElemIn *i_gen_trace_elem)
| Decoded Trace output. More...
ITrcGenElemIn * | getGenTraceElemOutI () const
| Return the connected generic element interface. More...
Decoder Management
ocsd_err_t | createDecoder (const std::string &decoderName, const int createFlags, const CSConfig *pConfig)
ocsd_err_t | removeDecoder (const uint8_t CSID)
ocsd_err_t | getDecoderStats (const uint8_t CSID, ocsd_decode_stats_t **p_stats_block)
ocsd_err_t | resetDecoderStats (const uint8_t CSID)
DecodeTreeElement * | getDecoderElement (const uint8_t CSID) const
DecodeTreeElement * | getFirstElement (uint8_t &elemID)
DecodeTreeElement * | getNextElement (uint8_t &elemID)
void | setInstrDecoder (IInstrDecode *i_instr_decode)
void | setMemAccessI (ITargetMemAccess *i_mem_access)
Memory Access Mapper

A memory mapper is used to organise a collection of memory accessor objects that contain the memory images for different areas of traced instruction memory. These areas could be the executed program and a set of loaded .so libraries for example - each of which would have code sections in different memory locations.

A memory accessor represents a snapshot of an area of memory as it appeared during trace capture, for a given memory space. Memory spaces are described by the ocsd_mem_space_acc_t enum. The most general memory space is OCSD_MEM_SPACE_ANY. This represents memory that can be secure or none-secure, available at any exception level.

The memory mapper will not allow two accessors to overlap in the same memory space.

The trace decdoer will access memory with a memory space parameter that represents the current core state - the mapper will find the closest memory space match for the address.

e.g. if the core is accessing secure EL3, then the most specialised matching space will be accessed. If an EL3 space matches that will be used, otherwise the any secure, and finally _ANY.

It is no necessary for clients to register memory accessors for all spaces - _ANY will be sufficient in many cases.

ocsd_err_t | createMemAccMapper (memacc_mapper_t type=MEMACC_MAP_GLOBAL)
TrcMemAccMapper * | getMemAccMapper () const
void | setExternMemAccMapper (TrcMemAccMapper *pMapper)
const bool | hasMemAccMapper () const
void | logMappedRanges ()
| Log the mapped memory ranges to the default message logger. More...
Memory Accessors
A memory accessor represents a snapshot of an area of memory as it appeared during trace capture. Memory spaces represent either common global memory, or Secure / none-secure and EL specific spaces.
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)
ocsd_err_t | addBinFileMemAcc (const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const std::string &filepath)
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)
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)
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)
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)
ocsd_err_t | removeMemAccByAddress (const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space)
CoreSight Trace Frame De-mux
TraceFormatterFrameDecoder * | getFrameDeformatter () const
| Get the Trace Frame de-mux. More...
ocsd_err_t | setIDFilter (std::vector< uint8_t > &ids)
| ID filtering - sets the output filter on the trace deformatter. More...
ocsd_err_t | clearIDFilter ()
| remove filter, all IDs will be decoded More...
Public Member Functions inherited from ITrcDataIn
| ITrcDataIn ()
virtual | ~ITrcDataIn ()

## Creation and Destruction

| DecodeTree ()
| default constructor More...
| ~DecodeTree ()
| default destructor More...
static DecodeTree * | CreateDecodeTree (const ocsd_dcd_tree_src_t src_type, const uint32_t formatterCfgFlags)
| Create a decode tree. Automatically creates a trace frame deformatter if required and a default error log component. More...
static void | DestroyDecodeTree (DecodeTree *p_dcd_tree)
| Destroy a decode tree. More...

## Error and element Logging

std::vector< ItemPrinter * > & | getPrinterList ()
ocsd_err_t | addPacketPrinter (uint8_t CSID, bool bMonitor, ItemPrinter **ppPrinter)
ocsd_err_t | addRawFramePrinter (RawFramePrinter **ppPrinter, uint32_t flags)
ocsd_err_t | addGenElemPrinter (TrcGenericElementPrinter **ppPrinter)
static ocsdDefaultErrorLogger * | getDefaultErrorLogger ()
| The library default error logger. More...
static ITraceErrorLog * | getCurrentErrorLogI ()
static void | setAlternateErrorLogger (ITraceErrorLog *p_error_logger)

## Detailed Description

Class to manage the decoding of data from a single trace sink .

Provides functionality to build a tree of decode objects capable of decoding multiple trace sources within a single trace sink (capture buffer).

Definition at line 61 of file ocsd_dcd_tree.h.

## Constructor & Destructor Documentation

## DecodeTree()

DecodeTree::DecodeTree | ( |  | ) |

default constructor

## ~DecodeTree()

DecodeTree::~DecodeTree | ( |  | ) |

default destructor

## Member Function Documentation

## addBinFileMemAcc()

ocsd_err_t DecodeTree::addBinFileMemAcc | ( | const ocsd_vaddr_t | address,
|  | const ocsd_mem_space_acc_t | mem_space,
|  | const std::string & | filepath
| ) |  |

Creates a memory accessor for a memory block supplied as a contiguous binary data file, and adds to the current mapper.

Parameters

  address | : Start address for the memory block in the memory map.
  mem_space | : Memory space
  &filepath | : Path to the binary data file

Returns
  ocsd_err_t : Library error code or OCSD_OK if successful.

## addBinFileRegionMemAcc()

ocsd_err_t DecodeTree::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
| ) |  |

Creates a memory accessor for a memory block supplied as a one or more memory regions in a binary file. Region structures are created that describe the memory start address, the offset within the binary file for that address, and the length of the region. This accessor can be used to point to the code section in a program file for example.

Parameters

  *region_array | : array of valid memory regions in the file.
  num_regions | : number of regions
  mem_space | : Memory space
  &filepath | : Path to the binary data file

Returns
  ocsd_err_t : Library error code or OCSD_OK if successful.

## addBufferMemAcc()

ocsd_err_t DecodeTree::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
| ) |  |

Creates a memory accessor for a memory block in the supplied buffer and adds to the current mapper.

Parameters

  address | : Start address for the memory block in the memory map.
  mem_space | : Memory space
  *p_mem_buffer | : start of the buffer.
  mem_length | : length of the buffer.

Returns
  ocsd_err_t : Library error code or OCSD_OK if successful.

## addCallbackIDMemAcc()

ocsd_err_t DecodeTree::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
| ) |  |

## addCallbackMemAcc()

ocsd_err_t DecodeTree::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
| ) |  |

This memory accessor allows the client to supply a callback function for the region defined by the start and end addresses. This can be used to supply a custom memory accessor, or to directly access memory if the decode is running live on a target system.

Parameters

  st_address | : start address of region.
  en_address | : end address of region.
  mem_space | : Memory space
  p_cb_func | : Callback function
  *p_context | : client supplied context information

Returns
  ocsd_err_t : Library error code or OCSD_OK if successful.

## addGenElemPrinter()

ocsd_err_t DecodeTree::addGenElemPrinter | ( | TrcGenericElementPrinter ** | ppPrinter | ) |

add a generic element output printer

## addPacketPrinter()

ocsd_err_t DecodeTree::addPacketPrinter | ( | uint8_t | CSID,
|  | bool | bMonitor,
|  | ItemPrinter ** | ppPrinter
| ) |  |

add a protocol packet printer

## addRawFramePrinter()

ocsd_err_t DecodeTree::addRawFramePrinter | ( | RawFramePrinter ** | ppPrinter,
|  | uint32_t | flags
| ) |  |

add a raw frame printer

## clearIDFilter()

ocsd_err_t DecodeTree::clearIDFilter | ( |  | ) |

remove filter, all IDs will be decoded

## createDecoder()

ocsd_err_t DecodeTree::createDecoder | ( | const std::string & | decoderName,
|  | const int | createFlags,
|  | const CSConfig * | pConfig
| ) |  |

Creates a decoder that is registered with the library under the supplied name. createFlags determine if a full packet processor / packet decoder pair or packet processor only is created. Uses the supplied configuration structure.

Parameters

  &decoderName | : registered name of decoder
  createFlags | : Decoder creation options.
  *pConfig | : Pointer to a valid configuration structure for the named decoder.

Returns
  ocsd_err_t : Library error code or OCSD_OK if successful.

## CreateDecodeTree()

static DecodeTree* DecodeTree::CreateDecodeTree | ( | const ocsd_dcd_tree_src_t | src_type,
|  | const uint32_t | formatterCfgFlags
| ) |  |

static

Create a decode tree. Automatically creates a trace frame deformatter if required and a default error log component.

Parameters

  src_type | : Data stream source type, can be CoreSight frame formatted trace, or single demuxed trace data stream,
  formatterCfgFlags | : Configuration flags for trace de-formatter.

Returns
  DecodeTree * : pointer to the decode tree, 0 if creation failed.

## createMemAccMapper()

ocsd_err_t DecodeTree::createMemAccMapper | ( | memacc_mapper_t | type = `MEMACC_MAP_GLOBAL` | ) |

This creates a memory mapper within the decode tree.

Parameters

  type | : defaults to MEMACC_MAP_GLOBAL (only type available at present)

Returns
  ocsd_err_t : Library error code or OCSD_OK if successful.

## DestroyDecodeTree()

static void DecodeTree::DestroyDecodeTree | ( | DecodeTree * | p_dcd_tree | ) |

static

Destroy a decode tree.

## getCurrentErrorLogI()

static ITraceErrorLog* DecodeTree::getCurrentErrorLogI | ( |  | ) |

inline static

the current error logging interface in use

Definition at line 92 of file ocsd_dcd_tree.h.

## getDecoderElement()

DecodeTreeElement* DecodeTree::getDecoderElement | ( | const uint8_t | CSID | ) | const

Find a decode tree element associated with a specific CoreSight trace ID. *

## getDecoderStats()

ocsd_err_t DecodeTree::getDecoderStats | ( | const uint8_t | CSID,
|  | ocsd_decode_stats_t ** | p_stats_block
| ) |  |

Get the stats block for the channel indicated. Caller must check p_stats_block->version to esure that the block is filled in a compatible manner.

Parameters

  CSID | : Configured CoreSight trace ID for the decoder.
  p_stats_block | block pointer to set to reference the stats block.

Returns
  ocsd_err_t : Library error code - OCSD_OK if valid block pointer returned, OCSD_ERR_NOTINIT if decoder does not support stats counting.

## getDefaultErrorLogger()

static ocsdDefaultErrorLogger* DecodeTree::getDefaultErrorLogger | ( |  | ) |

inline static

The library default error logger.

Definition at line 89 of file ocsd_dcd_tree.h.

## getFirstElement()

DecodeTreeElement* DecodeTree::getFirstElement | ( | uint8_t & | elemID | ) |

Decode tree iteration. Return the first tree element 0 if no elements avaiable.

Parameters

  &elemID | : CoreSight Trace ID associated with this element

## getFrameDeformatter()

TraceFormatterFrameDecoder* DecodeTree::getFrameDeformatter | ( |  | ) | const

inline

Get the Trace Frame de-mux.

Definition at line 388 of file ocsd_dcd_tree.h.

## getGenTraceElemOutI()

ITrcGenElemIn* DecodeTree::getGenTraceElemOutI | ( |  | ) | const

inline

Return the connected generic element interface.

Definition at line 138 of file ocsd_dcd_tree.h.

## getMemAccMapper()

TrcMemAccMapper* DecodeTree::getMemAccMapper | ( |  | ) | const

inline

Get a pointer to the memory mapper. Allows a client to add memory accessors directly to the mapper.

Returns
  TrcMemAccMapper : Pointer to the mapper.

Definition at line 276 of file ocsd_dcd_tree.h.

## getNextElement()

DecodeTreeElement* DecodeTree::getNextElement | ( | uint8_t & | elemID | ) |

Return the next tree element - or 0 if no futher elements avaiable.

Parameters

  &elemID | : CoreSight Trace ID associated with this element

## getPrinterList()

std::vector<ItemPrinter *>& DecodeTree::getPrinterList | ( |  | ) |

inline

get the list of packet printers for this decode tree

Definition at line 98 of file ocsd_dcd_tree.h.

## hasMemAccMapper()

const bool DecodeTree::hasMemAccMapper | ( |  | ) | const

inline

Return true if a mapper has been set (internal or external

Definition at line 289 of file ocsd_dcd_tree.h.

## logMappedRanges()

void DecodeTree::logMappedRanges | ( |  | ) |

Log the mapped memory ranges to the default message logger.

## removeDecoder()

ocsd_err_t DecodeTree::removeDecoder | ( | const uint8_t | CSID | ) |

Remove a decoder / packet processor attached to an Trace ID output on the frame de-mux.

Once removed another decoder can be created that has a CSConfig using that ID.

Parameters

  CSID | : Trace ID to remove.

Returns
  ocsd_err_t : Library error code or OCSD_OK if successful.

## removeMemAccByAddress()

ocsd_err_t DecodeTree::removeMemAccByAddress | ( | const ocsd_vaddr_t | address,
|  | const ocsd_mem_space_acc_t | mem_space
| ) |  |

Remove the memory accessor from the map, that begins at the given address, for the memory space provided.

Parameters

  address | : Start address of the memory accessor.
  mem_space | : Memory space for the memory accessor.

Returns
  ocsd_err_t : Library error code or OCSD_OK if successful.

## resetDecoderStats()

ocsd_err_t DecodeTree::resetDecoderStats | ( | const uint8_t | CSID | ) |

Reset the stats block for the chosens decode channel. stats block is reset independently of the decoder reset to allow counts across multiple decode runs.

Parameters

  handle | : Handle to decode tree.
  CSID | : Configured CoreSight trace ID for the decoder.

Returns
  ocsd_err_t : Library error code - OCSD_OK if successful.

## setAlternateErrorLogger()

static void DecodeTree::setAlternateErrorLogger | ( | ITraceErrorLog * | p_error_logger | ) |

static

set an alternate error logging interface.

## setExternMemAccMapper()

void DecodeTree::setExternMemAccMapper | ( | TrcMemAccMapper * | pMapper | ) |

Set an external mapper rather than create a mapper in the decode tree. Setting this will also destroy any internal mapper that was previously created.

Parameters

  pMapper | : pointer to the mapper to add.

## setGenTraceElemOutI()

void DecodeTree::setGenTraceElemOutI | ( | ITrcGenElemIn * | i_gen_trace_elem | ) |

Decoded Trace output.

Client trace analysis program attaches a generic trace element interface to receive the output from the trace decode operations.

Parameters

  *i_gen_trace_elem | : Pointer to the interface.

## setIDFilter()

ocsd_err_t DecodeTree::setIDFilter | ( | std::vector< uint8_t > & | ids | ) |

ID filtering - sets the output filter on the trace deformatter.

Only supplied IDs will be decoded.

No effect if no decoder attached for the ID

Parameters

  ids | : Vector of CS Trace IDs

## setInstrDecoder()

void DecodeTree::setInstrDecoder | ( | IInstrDecode * | i_instr_decode | ) |

Set an ARM instruction opcode decoder.

Parameters

  *i_instr_decode | : Pointer to the interface.

## setMemAccessI()

void DecodeTree::setMemAccessI | ( | ITargetMemAccess * | i_mem_access | ) |

Set a target memory access interface - used to access program image memory for instruction trace decode.

Parameters

  *i_mem_access | : Pointer to the interface.

## TraceDataIn()

virtual ocsd_datapath_resp_t DecodeTree::TraceDataIn | ( | const ocsd_datapath_op_t | op,
|  | const ocsd_trc_index_t | index,
|  | const uint32_t | dataBlockSize,
|  | const uint8_t * | pDataBlock,
|  | uint32_t * | numBytesProcessed
| ) |  |

virtual

Trace Data input interface (ITrcDataIn)

Decode tree implements the data in interface : ITrcDataIn . Captured raw trace data is passed into the deformatter and decoders via this method.

Implements ITrcDataIn.

## updateBinFileRegionMemAcc()

ocsd_err_t DecodeTree::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
| ) |  |

Updates/adds to a memory accessor for a memory block supplied as a one or more memory regions in a binary file. Region structures are created that describe the memory start address, the offset within the binary file for that address, and the length of the region. This accessor can be used to point to the code section in a program file for example.

Parameters

  *region_array | : array of valid memory regions in the file.
  num_regions | : number of regions
  mem_space | : Memory space
  &filepath | : Path to the binary data file

Returns
  ocsd_err_t : Library error code or OCSD_OK if successful.

The documentation for this class was generated from the following file:

- /build/libopencsd-nipXOR/libopencsd-1.2.0/decoder/include/common/ocsd_dcd_tree.h