OpenCSD - CoreSight Trace Decode Library  1.3.3
List of all members
DecodeTree Class Reference

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

#include <ocsd_dcd_tree.h>

Inheritance diagram for DecodeTree:
Inheritance graph
[legend]
Collaboration diagram for DecodeTree:
Collaboration graph
[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...
 
ITrcGenElemIngetGenTraceElemOutI () 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)
 
DecodeTreeElementgetDecoderElement (const uint8_t CSID) const
 
DecodeTreeElementgetFirstElement (uint8_t &elemID)
 
DecodeTreeElementgetNextElement (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)
 
TrcMemAccMappergetMemAccMapper () 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
TraceFormatterFrameDecodergetFrameDeformatter () 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 DecodeTreeCreateDecodeTree (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 ocsdDefaultErrorLoggergetDefaultErrorLogger ()
 The library default error logger. More...
 
static ITraceErrorLoggetCurrentErrorLogI ()
 
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 ( )
inlinestatic

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_blockblock 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 ( )
inlinestatic

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: