dynamorio::drmemtrace::raw2trace_t Class Reference

#include <raw2trace.h>

Public Member Functions
std::string	handle_custom_data (const char *(*parse_cb)(const char *src, OUT void **data), std::string(*process_cb)(drmodtrack_info_t *info, void *data, void *user_data), void *process_cb_user_data, void(*free_cb)(void *data))
std::string	do_module_parsing ()
std::string	do_module_parsing_and_mapping ()
std::string	find_mapped_trace_address (app_pc trace_address, OUT app_pc *mapped_address)
virtual std::string	do_conversion ()

Protected Member Functions
bool	process_offline_entry (raw2trace_thread_data_t *tdata, const offline_entry_t *in_entry, thread_id_t tid, OUT bool *end_of_record, OUT bool *last_bb_handled, OUT bool *flush_decode_cache)
bool	read_header (raw2trace_thread_data_t *tdata, OUT trace_header_t *header)
virtual const offline_entry_t *	get_next_entry (raw2trace_thread_data_t *tdata)
virtual const offline_entry_t *	get_next_entry_keep_prior (raw2trace_thread_data_t *tdata)
virtual bool	on_thread_end (raw2trace_thread_data_t *tdata)
virtual void	log (uint level, const char *fmt,...)
virtual void	log_instruction (uint level, app_pc decode_pc, app_pc orig_pc)
bool	process_next_thread_buffer (raw2trace_thread_data_t *tdata, OUT bool *end_of_record)
const std::vector< module_t > &	modvec_ () const
void	set_modvec_ (const std::vector< module_t > *modvec)
const module_mapper_t &	modmap_ () const
void	set_modmap_ (const module_mapper_t *modmap)

Protected Attributes
void *const	dcontext_
bool	passed_dcontext_ = false

Static Protected Attributes
static const uint	WRITE_BUFFER_SIZE = 64

Detailed Description

The raw2trace class converts the raw offline trace format to the format expected by analysis tools. It requires access to the binary files for the libraries and executable that were present during tracing.

Member Function Documentation

do_conversion()

virtual std::string dynamorio::drmemtrace::raw2trace_t::do_conversion ( )

virtual

Performs the conversion from raw data to finished trace files. Returns a non-empty error message on failure.

do_module_parsing()

std::string dynamorio::drmemtrace::raw2trace_t::do_module_parsing

(

)

Performs the first step of do_conversion() without further action: parses and iterates over the list of modules. This is provided to give the user a method for iterating modules in the presence of the custom field used by drmemtrace that prevents direct use of drmodtrack_offline_read(). On success, calls the process_cb function passed to handle_custom_data() for every module in the list, and returns an empty string at the end. Returns a non-empty error message on failure.

Deprecated:

dynamorio::drmemtrace::module_mapper_t should be used instead.

do_module_parsing_and_mapping()

std::string dynamorio::drmemtrace::raw2trace_t::do_module_parsing_and_mapping

(

)

This interface is meant to be used with a final trace rather than a raw trace, using the module log file saved from the raw2trace conversion. This routine first calls do_module_parsing() and then maps each module into the current address space, allowing the user to augment the instruction information in the trace with additional information by decoding the instruction bytes. The routine find_mapped_trace_address() should be used to convert from memref_t.instr.addr to the corresponding mapped address in the current process. Returns a non-empty error message on failure.

Deprecated:

dynamorio::drmemtrace::module_mapper_t::get_loaded_modules() should be used instead.

find_mapped_trace_address()

std::string dynamorio::drmemtrace::raw2trace_t::find_mapped_trace_address	(	app_pc	trace_address,
		OUT app_pc *	mapped_address
	)

This interface is meant to be used with a final trace rather than a raw trace, using the module log file saved from the raw2trace conversion. When do_module_parsing_and_mapping() has been called, this routine can be used to convert an instruction program counter in a trace into an address in the current process where the instruction bytes for that instruction are mapped, allowing decoding for obtaining further information than is stored in the trace. Returns a non-empty error message on failure.

Deprecated:

dynamorio::drmemtrace::module_mapper_t::find_mapped_trace_address() should be used instead.

get_next_entry()

virtual const offline_entry_t* dynamorio::drmemtrace::raw2trace_t::get_next_entry ( raw2trace_thread_data_t *  tdata )

protectedvirtual

Point to the next offline entry_t. Will not attempt to dereference past the returned pointer.

get_next_entry_keep_prior()

virtual const offline_entry_t* dynamorio::drmemtrace::raw2trace_t::get_next_entry_keep_prior ( raw2trace_thread_data_t *  tdata )

protectedvirtual

Records the currently stored last entry in order to remember two entries at once (for handling split two-entry markers) and then reads and returns a pointer to the next entry. A subsequent call to unread_last_entry() will put back both entries. Returns an emptry string on success or an error description on an error.

handle_custom_data()

std::string dynamorio::drmemtrace::raw2trace_t::handle_custom_data	(	const char *(*)(const char *src, OUT void **data)	parse_cb,
		std::string(*)(drmodtrack_info_t *info, void *data, void *user_data)	process_cb,
		void *	process_cb_user_data,
		void(*)(void *data)	free_cb
	)

Adds handling for custom data fields that were stored with each module via drmemtrace_custom_module_data() during trace generation. When do_conversion() or do_module_parsing() is subsequently called, its parsing of the module data will invoke parse_cb, which should advance the module data pointer passed in src and return it as its return value (or nullptr on error), returning the resulting parsed data in data. The data pointer will later be passed to both process_cb, which can update the module path inside info (and return a non-empty string on error), and free_cb, which can perform cleanup.

A custom callback value process_cb_user_data can be passed to process_cb. The same is not provided for the other callbacks as they end up using the drmodtrack_add_custom_data() framework where there is no support for custom callback parameters.

Returns a non-empty error message on failure.

log()

virtual void dynamorio::drmemtrace::raw2trace_t::log ( uint  level, const char *  fmt,   ...  )

protectedvirtual

The level parameter represents severity: the lower the level, the higher the severity.

log_instruction()

virtual void dynamorio::drmemtrace::raw2trace_t::log_instruction ( uint  level, app_pc  decode_pc, app_pc  orig_pc  )

protectedvirtual

Similar to log() but this disassembles the given PC.

modmap_()

const module_mapper_t& dynamorio::drmemtrace::raw2trace_t::modmap_ ( ) const

inlineprotected

Get the module mapper.

modvec_()

const std::vector<module_t>& dynamorio::drmemtrace::raw2trace_t::modvec_ ( ) const

inlineprotected

Get the module map.

on_thread_end()

virtual bool dynamorio::drmemtrace::raw2trace_t::on_thread_end ( raw2trace_thread_data_t *  tdata )

protectedvirtual

Callback notifying the currently-processed thread has exited. Subclasses are expected to track record metadata themselves. APIs for extracting that metadata are exposed.

process_next_thread_buffer()

bool dynamorio::drmemtrace::raw2trace_t::process_next_thread_buffer ( raw2trace_thread_data_t *  tdata, OUT bool *  end_of_record  )

protected

Processes a raw buffer which must be the next buffer in the desired (typically timestamp-sorted) order for its traced thread. For concurrent buffer processing, all buffers from any one traced thread must be processed by the same worker thread, both for correct ordering and correct synchronization.

process_offline_entry()

bool dynamorio::drmemtrace::raw2trace_t::process_offline_entry ( raw2trace_thread_data_t *  tdata, const offline_entry_t *  in_entry, thread_id_t  tid, OUT bool *  end_of_record, OUT bool *  last_bb_handled, OUT bool *  flush_decode_cache  )

protected

Convert starting from in_entry, and reading more entries as required. Sets end_of_record to true if processing hit the end of a record. read_and_map_modules() must have been called by the implementation before calling this API.

read_header()

bool dynamorio::drmemtrace::raw2trace_t::read_header ( raw2trace_thread_data_t *  tdata, OUT trace_header_t *  header  )

protected

Read the header of a thread, by calling get_next_entry() successively to populate the header values. The timestamp field is populated only for legacy traces.

set_modmap_()

void dynamorio::drmemtrace::raw2trace_t::set_modmap_ ( const module_mapper_t *  modmap )

inlineprotected

Set the module mapper. Must be called before process_offline_entry() is called.

set_modvec_()

void dynamorio::drmemtrace::raw2trace_t::set_modvec_ ( const std::vector< module_t > *  modvec )

inlineprotected

Set the module map. Must be called before process_offline_entry() is called.

Field Documentation

dcontext_

void* const dynamorio::drmemtrace::raw2trace_t::dcontext_

protected

The pointer to the DR context.

passed_dcontext_

bool dynamorio::drmemtrace::raw2trace_t::passed_dcontext_ = false

protected

Whether a non-nullptr dcontext was passed to the constructor.

WRITE_BUFFER_SIZE

const uint dynamorio::drmemtrace::raw2trace_t::WRITE_BUFFER_SIZE = 64

staticprotected

The trace_entry_t buffer returned by get_write_buffer() is assumed to be at least WRITE_BUFFER_SIZE large.

---

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

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