dynamorio::drmemtrace::decode_cache_t< DecodeInfo > Class Template Reference

#include <decode_cache.h>

Inheritance diagram for dynamorio::drmemtrace::decode_cache_t< DecodeInfo >:

Public Member Functions
DecodeInfo *	get_decode_info (app_pc pc)
std::string	add_decode_info (const dynamorio::drmemtrace::_memref_instr_t &memref_instr, DecodeInfo *&cached_decode_info)
virtual std::string	init (offline_file_type_t filetype, const std::string &module_file_path="", const std::string &alt_module_dir="")
void	clear_cache ()

Additional Inherited Members
Protected Member Functions inherited from dynamorio::drmemtrace::decode_cache_base_t
	decode_cache_base_t (unsigned int verbosity)
std::string	init_module_mapper (const std::string &module_file_path, const std::string &alt_module_dir)
std::string	find_mapped_trace_address (app_pc trace_pc, app_pc &decode_pc)
offline_file_type_t	build_arch_file_type ()
Protected Attributes inherited from dynamorio::drmemtrace::decode_cache_base_t
bool	use_module_mapper_ = false
unsigned int	verbosity_ = 0

Detailed Description

template<class DecodeInfo>
class dynamorio::drmemtrace::decode_cache_t< DecodeInfo >

A cache to store decode info for instructions per observed app pc. The template arg DecodeInfo is a class derived from dynamorio::drmemtrace::decode_info_base_t which implements the set_decode_info_derived() function that derives the required decode info from an instr_t object and raw encoding bytes when invoked by dynamorio::drmemtrace::decode_cache_t. This class handles the heavy lifting of determining the address where the instruction raw bytes can be found (which can be inside the instr memref_t, or in the mapped application binaries for legacy traces), actually producing the decoded instr_t, and managing the DecodeInfo cache (which includes invalidating stale DecodeInfo based on the encoding_is_new field in traces with embedded encodings).

In general use, include_decoded_instr_ should be set to true, but may be set to false if the user wants to perform decoding themselves. In this case, the instr_t provided to set_decode_info_derived() will be nullptr, and the dynamorio::drmemtrace::decode_cache_t object merely acts as a cache and provider of the instruction raw bytes.

The decoded instr_t may be made to persist beyond the set_decode_info() calls by constructing the dynamorio::drmemtrace::decode_cache_t object with persist_decoded_instr_ set to true.

include_decoded_instr_ cannot be false if persist_decoded_instr_ is true.

Usage note: after constructing an object, init() must be called.

Member Function Documentation

add_decode_info()

template<class DecodeInfo >

std::string dynamorio::drmemtrace::decode_cache_t< DecodeInfo >::add_decode_info ( const dynamorio::drmemtrace::_memref_instr_t &  memref_instr, DecodeInfo *&  cached_decode_info  )

inline

Adds decode info for the given memref_instr if it is not yet recorded. or if it contains a new encoding.

Uses the embedded encodings in the trace or, if init() was invoked with a module file path, the encodings from the instantiated dynamorio::drmemtrace::module_mapper_t.

If there is a failure either during decoding or creation of the DecodeInfo object, a DecodeInfo that returns is_valid() == false and the relevant error info in get_error_string() will be added to the cache.

Returns a pointer to whatever DecodeInfo is present in the cache in the cached_decode_info reference pointer parameter, or a nullptr if none is cached. This helps avoid a repeated lookup in a subsequent get_decode_info() call.

Returns the error string, or an empty string if there was no error. A valid DecodeInfo is guaranteed to be in the cache if there was no error.

clear_cache()

template<class DecodeInfo >

void dynamorio::drmemtrace::decode_cache_t< DecodeInfo >::clear_cache ( )

inline

Clears all cached decode info entries.

Typically analysis tools like to keep their per-shard data around till all shards are done processing (so they can combine the shards and use the results), but this API optionally allows tools to keep memory consumption in check by discarding the decode cache entries in parallel_shard_exit(), since it's very likely that the decode cache is not needed for result computation.

This does not affect the state of any initialized module mapper, which is still cleaned up during destruction.

get_decode_info()

template<class DecodeInfo >

DecodeInfo* dynamorio::drmemtrace::decode_cache_t< DecodeInfo >::get_decode_info ( app_pc  pc )

inline

Returns a pointer to the DecodeInfo available for the instruction at pc. Returns nullptr if no instruction is known at that pc. Returns the default-constructed DecodeInfo if an instr was seen at that pc but there was a decoding error for the instruction.

Guaranteed to be non-nullptr and valid if the prior add_decode_info() for that pc returned no error.

When analyzing memref_t from a trace, it may be better to just use add_decode_info() instead (as it also returns the added DecodeInfo) if it's possible that the instr at pc may have changed (e.g., JIT code) in which case the cache will need to be updated.

init()

template<class DecodeInfo >

virtual std::string dynamorio::drmemtrace::decode_cache_t< DecodeInfo >::init ( offline_file_type_t  filetype, const std::string &  module_file_path = "", const std::string &  alt_module_dir = ""  )

inlinevirtual

Performs initialization tasks such as verifying whether the given trace indeed has embedded encodings or not, and initializing the dynamorio::drmemtrace::module_mapper_t if the module path is provided.

It is important to note some nuances in how the filetype can be obtained:

• the trace filetype may be obtained using the get_filetype() API on the dynamorio::drmemtrace::memtrace_stream_t. However, instances of dynamorio::drmemtrace::memtrace_stream_t have the filetype available at init time (in the dynamorio::drmemtrace::analysis_tool_t::initialize() or dynamorio::drmemtrace::analysis_tool_t::initialize_stream() functions) only for offline analysis, not for online analysis.
• when using the -skip_instrs or -skip_timestamp analyzer options, all initial header entries are skipped over. Therefore, the analysis tool may not see a TRACE_MARKER_TYPE_FILETYPE at all.

The most reliable way to obtain the filetype (and call this init() API), would be to use dynamorio::drmemtrace::memtrace_stream_t::get_filetype() just before processing the first instruction memref in the dynamorio::drmemtrace::analysis_tool_t::process_memref() or dynamorio::drmemtrace::analysis_tool_t::parallel_shard_memref() APIs.

If the module_file_path parameter is not empty, it instructs the dynamorio::drmemtrace::decode_cache_t object that it should look for the instr encodings in the application binaries using a dynamorio::drmemtrace::module_mapper_t. A dynamorio::drmemtrace::module_mapper_t is instantiated only one time and reused for all objects of dynamorio::drmemtrace::decode_cache_t (of any template type). The user must provide a valid module_file_path if decoding instructions from a trace that does not have embedded instruction encodings in it, as indicated by absence of the OFFLINE_FILE_TYPE_ENCODINGS bit in the TRACE_MARKER_TYPE_FILETYPE marker. The user may provide a module_file_path also if they deliberately need to use the module mapper instead of the embedded encodings. Each instance of dynamorio::drmemtrace::decode_cache_t must be initialized with either an empty module_file_path, or the same one as other instances that also specified a non-empty path (even the ones in other analysis tools).

If the provided module_file_path is empty, the cache object uses the encodings embedded in the trace records.

This also sets the isa_mode in dcontext based on the arch bits in the provided filetype, unless the instance was not asked to include decoded instructions via the include_decoded_instr_ param to the constructor.

---

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

• /home/runner/work/dynamorio/dynamorio/build_release-64/clients/include/drmemtrace/decode_cache.h