#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 bool process_marker_additionally (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_tmodmap_ () 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 

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

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.

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.

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.

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)

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)

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)

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)

Returns whether this system number might block.

◆ log()

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

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 

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

◆ modmap_()

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

Get the module mapper.

◆ modvec_()

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

Get the module map.

◆ on_thread_end()

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

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_additionally()

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

Performs any additional actions for the marker "marker_type" with value "marker_val", beyond writing out a marker record. New records can 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 

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 

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 

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

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)

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)

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 

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_

The pointer to the DR context.

◆ passed_dcontext_

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

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


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

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