#include <raw2trace.h>

Public Member Functions
std::string	handle_custom_data (const char (parse_cb)(const char src, DR_PARAM_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, DR_PARAM_OUT app_pc *mapped_address)

virtual std::string	do_conversion ()

Static Public Member Functions
static void	create_essential_header_entries (byte *&buf_ptr, int version, offline_file_type_t file_type, thread_id_t tid, process_id_t pid)

Protected Member Functions
bool	process_offline_entry (raw2trace_thread_data_t tdata, const offline_entry_t in_entry, thread_id_t tid, DR_PARAM_OUT bool end_of_record, DR_PARAM_OUT bool last_bb_handled, DR_PARAM_OUT bool *flush_decode_cache)

virtual void	observe_entry_output (raw2trace_thread_data_t tls, const trace_entry_t entry)

virtual bool	process_marker (raw2trace_thread_data_t tdata, trace_marker_type_t marker_type, uintptr_t marker_val, byte &buf, DR_PARAM_OUT bool *flush_decode_cache)

bool	read_header (raw2trace_thread_data_t tdata, DR_PARAM_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, DR_PARAM_OUT bool end_of_record)

std::string	read_syscall_template_file ()

app_pc	get_first_app_pc_for_syscall_template (int syscall_num)

bool	write_syscall_template (raw2trace_thread_data_t tdata, byte &buf, trace_entry_t *buf_base, int syscall_num)

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)

virtual bool	is_maybe_blocking_syscall (uintptr_t number)

Protected Attributes
void *const	dcontext_

bool	passed_dcontext_ = false

Static Protected Attributes
static const uint	WRITE_BUFFER_SIZE = 260

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

◆ create_essential_header_entries()

static void dynamorio::drmemtrace::raw2trace_t::create_essential_header_entries	(	byte *&	buf_ptr,
		int	version,
		offline_file_type_t	file_type,
		thread_id_t	tid,
		process_id_t	pid
	)

static

Writes the essential header entries to the given buffer. This is useful for other libraries that want to create a trace that works with our tools like the analyzer framework.

◆ 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,
		DR_PARAM_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_first_app_pc_for_syscall_template()

app_pc dynamorio::drmemtrace::raw2trace_t::get_first_app_pc_for_syscall_template ( int syscall_num )

protected

Returns the app pc of the first instruction in the system call template read for syscall_num. Returns nullptr if it could not find it.

◆ 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, DR_PARAM_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.

◆ is_maybe_blocking_syscall()

virtual bool dynamorio::drmemtrace::raw2trace_t::is_maybe_blocking_syscall ( uintptr_t number )

protectedvirtual

Returns whether this system number might block.

◆ 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.

◆ observe_entry_output()

virtual void dynamorio::drmemtrace::raw2trace_t::observe_entry_output	(	raw2trace_thread_data_t *	tls,
		const trace_entry_t *	entry
	)

protectedvirtual

Called for each record in an output buffer prior to writing out the buffer. The entry cannot be modified. A subclass can override this to compute per-shard statistics which can then be used for a variety of tasks including late removal of shards for targeted filtering.

◆ 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_marker()

virtual bool dynamorio::drmemtrace::raw2trace_t::process_marker	(	raw2trace_thread_data_t *	tdata,
		trace_marker_type_t	marker_type,
		uintptr_t	marker_val,
		byte *&	buf,
		DR_PARAM_OUT bool *	flush_decode_cache
	)

protectedvirtual

Performs processing actions for the marker "marker_type" with value "marker_val", including writing out a marker record. Further records can also be written to "buf". Returns whether successful.

◆ process_next_thread_buffer()

bool dynamorio::drmemtrace::raw2trace_t::process_next_thread_buffer	(	raw2trace_thread_data_t *	tdata,
		DR_PARAM_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,
		DR_PARAM_OUT bool *	end_of_record,
		DR_PARAM_OUT bool *	last_bb_handled,
		DR_PARAM_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,
		DR_PARAM_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.

◆ read_syscall_template_file()

std::string dynamorio::drmemtrace::raw2trace_t::read_syscall_template_file ( )

protected

Reads entries in the given system call template file. These will be added to the final trace at the locations of the corresponding system call number markers.

◆ 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.

◆ write_syscall_template()

bool dynamorio::drmemtrace::raw2trace_t::write_syscall_template	(	raw2trace_thread_data_t *	tdata,
		byte *&	buf,
		trace_entry_t *	buf_base,
		int	syscall_num
	)

protected

Writes the system call template to the output trace, if any was provided in the system call template file for the given syscall_num.

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 = 260

staticprotected

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

WRITE_BUFFER_SIZE needs to be large enough to hold one instruction and its memrefs. Some of the AArch64 SVE scatter/gather instructions have a lot of memref entries. For example ld4b loads 4 registers with byte sized elements, so that is (vl_bits / 8) * 4 entries. With a 512-bit vector length that is (512 / 8) * 4 = 256 memref entries.

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ create_essential_header_entries()

◆ do_conversion()

◆ do_module_parsing()

◆ do_module_parsing_and_mapping()

◆ find_mapped_trace_address()

◆ get_first_app_pc_for_syscall_template()

◆ get_next_entry()

◆ get_next_entry_keep_prior()

◆ handle_custom_data()

◆ is_maybe_blocking_syscall()

◆ log()

◆ log_instruction()

◆ modmap_()

◆ modvec_()

◆ observe_entry_output()

◆ on_thread_end()

◆ process_marker()

◆ process_next_thread_buffer()

◆ process_offline_entry()

◆ read_header()

◆ read_syscall_template_file()

◆ set_modmap_()

◆ set_modvec_()

◆ write_syscall_template()

Field Documentation

◆ dcontext_

◆ passed_dcontext_

◆ WRITE_BUFFER_SIZE