#include <raw2trace_shared.h>

Inheritance diagram for dynamorio::drmemtrace::module_mapper_t:

Public Member Functions
std::string	get_last_error (void) const

virtual const std::vector< module_t > &	get_loaded_modules ()

app_pc	find_mapped_trace_address (app_pc trace_address)

app_pc	find_mapped_trace_bounds (app_pc trace_address, DR_PARAM_OUT app_pc module_start, DR_PARAM_OUT size_t module_size)

virtual	~module_mapper_t ()

drcovlib_status_t	write_module_data (char buf, size_t buf_size, int(print_cb)(void data, char dst, size_t max_len), DR_PARAM_OUT size_t *wrote)

Static Public Member Functions
static std::unique_ptr< module_mapper_t >	create (const char module_map, const char (parse_cb)(const char src, DR_PARAM_OUT void *data)=nullptr, std::string(process_cb)(drmodtrack_info_t info, void data, void user_data)=nullptr, void process_cb_user_data=nullptr, void(free_cb)(void data)=nullptr, uint verbosity=0, const std::string &alt_module_dir="", file_t encoding_file=INVALID_FILE)

Detailed Description

module_mapper_t maps and unloads application modules, as well as non-module instruction encodings (for raw traces, or if not present in the final trace). Using it assumes a dr_context has already been setup. This class is not thread-safe.

Constructor & Destructor Documentation

◆ ~module_mapper_t()

virtual dynamorio::drmemtrace::module_mapper_t::~module_mapper_t ( )

virtual

Unload modules loaded with read_and_map_modules(), freeing associated resources.

Member Function Documentation

◆ create()

static std::unique_ptr<module_mapper_t> dynamorio::drmemtrace::module_mapper_t::create	(	const char *	module_map,
		const char ()(const char src, DR_PARAM_OUT void *data)	parse_cb = `nullptr`,
		std::string()(drmodtrack_info_t info, void data, void user_data)	process_cb = `nullptr`,
		void *	process_cb_user_data = `nullptr`,
		void()(void data)	free_cb = `nullptr`,
		uint	verbosity = `0`,
		const std::string &	alt_module_dir = `""`,
		file_t	encoding_file = `INVALID_FILE`
	)

inlinestatic

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(). 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 afterwards 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.

The callbacks will only be called during object construction.

Additionally parses the non-module instruction encodings file if 'encoding_file' is not nullptr.

On success, calls the process_cb function for every module in the list. On failure, get_last_error() is non-empty, and indicates the cause.

◆ find_mapped_trace_address()

app_pc dynamorio::drmemtrace::module_mapper_t::find_mapped_trace_address ( app_pc trace_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. After a call to get_loaded_modules(), this routine may 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. This interface only supports code inside modules; generated code is expected to have instruction encodings in the trace itself. Returns the mapped address. Check get_last_error_() if an error occurred.

◆ find_mapped_trace_bounds()

app_pc dynamorio::drmemtrace::module_mapper_t::find_mapped_trace_bounds	(	app_pc	trace_address,
		DR_PARAM_OUT app_pc *	module_start,
		DR_PARAM_OUT size_t *	module_size
	)

This is identical to find_mapped_trace_address() but it also returns the bounds of the containing region, allowing the caller to perform its own mapping for any address that is also within those bounds.

◆ get_last_error()

std::string dynamorio::drmemtrace::module_mapper_t::get_last_error ( void ) const

inline

All APIs on this type, including constructor, may fail. get_last_error() returns the last error message. The object should be considered unusable if !get_last_error().empty().

◆ get_loaded_modules()

virtual const std::vector<module_t>& dynamorio::drmemtrace::module_mapper_t::get_loaded_modules ( )

inlinevirtual

module_t vector corresponding to the application modules. Lazily loads and caches modules. If the object is invalid, returns an empty vector. The user may check get_last_error() to ensure no error has occurred, or get the applicable error message.

◆ write_module_data()

drcovlib_status_t dynamorio::drmemtrace::module_mapper_t::write_module_data	(	char *	buf,
		size_t	buf_size,
		int()(void data, char *dst, size_t max_len)	print_cb,
		DR_PARAM_OUT size_t *	wrote
	)

Writes out the module list to buf, whose capacity is buf_size. The written data includes any modifications made by the process_cb passed to create(). Any custom data returned by the parse_cb passed to create() is passed to print_cb here for serialization. The print_cb must return the number of characters printed or -1 on error.

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

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

Public Member Functions

Static Public Member Functions