trace_converter_t< T > Class Template Reference

#include <raw2trace.h>

Protected Member Functions

 trace_converter_t (void *dcontext)
 ~trace_converter_t ()
std::string process_offline_entry (void *tls, const offline_entry_t *in_entry, thread_id_t tid, OUT bool *end_of_record, OUT bool *last_bb_handled)
std::string read_header (void *tls, OUT trace_header_t *header)
const std::vector< module_t > & modvec_ () const
void set_modvec_ (const std::vector< module_t > *modvec)

Protected Attributes

void *const dcontext_
bool passed_dcontext_ = false

Static Protected Attributes

static const uint WRITE_BUFFER_SIZE = 64

Detailed Description

template<typename T>
class trace_converter_t< T >

trace_converter_t is a reusable component that encapsulates raw trace conversion.

Conversion happens from a data source abstracted by the type parameter T. We make no assumption about how thread buffers are organized. We do assume the internal composition of thread buffers is "as written" by the thread. For example, all thread buffers belonging to different threads may be in a separate files; or buffers may be co-located in one large file, or spread accross multiple, mixed-thread files.

trace_converter_t expects to be instantiated with its type template T which should provide the following APIs. These pass through an opaque pointer which provides per-traced-thread-local data to the converter:

  • const offline_entry_t *get_next_entry(void *tls)

    Point to the next offline entry_t. There is no assumption about the underlying source of the data, and trace_converter_t will not attempt to dereference past the provided pointer.

  • const offline_entry_t *get_next_entry_keep_prior(void *tls)

    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.

  • void unread_last_entry(void *tls)

    Ensure that the next call to get_next_entry() re-reads the last value.

  • trace_entry_t *get_write_buffer(void *tls)

    Return a writable buffer guaranteed to be at least WRITE_BUFFER_SIZE large. get_write_buffer() may reuse the same buffer after write() or write_delayed_branches() is called.

  • bool write(void *tls, const trace_entry_t *start, const trace_entry_t *end)

    Writes the converted traces between start and end, where end is past the last item to write. Both start and end are assumed to be pointers inside a buffer returned by get_write_buffer().

  • std::string write_delayed_branches(void *tls, const trace_entry_t *start, const trace_entry_t *end)

    Similar to write(), but treat the provided traces as delayed branches: if they are the last values in a record, they belong to the next record of the same thread.

  • std::string append_delayed_branch(void *tls)

    Flush the branches sent to write_delayed_branches().

  • std::string on_thread_end(void *tls)

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

  • void log(uint level, const char *fmt, ...)

    Implementers are given the opportunity to implement their own logging. The level parameter represents severity: the lower the level, the higher the severity.

  • void log_instruction(uint level, app_pc decode_pc, app_pc orig_pc);

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

  • void add_to_statistic(void *tls, raw2trace_statistic_t stat, int value)

    Increases the per-thread counter for the statistic identified by stat by value.

  • bool raw2trace_t::instr_summary_exists(void *tls, uint64 modidx, uint64 modoffs, app_pc block_start_pc, app_pc pc) const

    Returns whether an instr_summary_t representation of the instruction at pc inside the block that begins at block_start_pc in the specified module exists.

  • const instr_summary_t *get_instr_summary(void *tls, uint64 modidx, uint64 modoffs, app_pc block_start_pc, int instr_count, int index, INOUT app_pc *pc, app_pc orig)

    Return the instr_summary_t representation of the index-th instruction (at *pc) inside the block that begins at block_start_pc and contains instr_count instructions in the specified module. Updates the value at pc to the PC of the next instruction. It is assumed the app binaries have already been loaded using module_mapper_t, and the values at *pc point within memory mapped by the module mapper. This API provides an opportunity to cache decoded instructions.

  • bool set_instr_summary_flags(void *tls, uint64 modidx, uint64 modoffs, app_pc block_start_pc, int instr_count, int index, app_pc pc, app_pc orig, bool write, int memop_index, bool use_remembered_base, bool remember_base)

    Sets two flags stored in the memref_summary_t inside the instr_summary_t for the index-th instruction (at pc) inside the block that begins at block_start_pc and contains instr_count instructions in the specified module. The flags use_remembered_base and remember_base are set for the source (write==false) or destination (write==true) operand of index memop_index. The flags are OR-ed in: i.e., they are never cleared.

  • void set_prev_instr_rep_string(void *tls, bool value)

    Sets a per-traced-thread cached flag that is read by was_prev_instr_rep_string().

  • bool was_prev_instr_rep_string(void *tls)

    Queries a per-traced-thread cached flag that is set by set_prev_instr_rep_string().

  • int get_version(void *tls)

    Returns the trace file version (an OFFLINE_FILE_VERSION* constant).

  • offline_file_type_t get_file_type(void *tls)

    Returns the trace file type (a combination of OFFLINE_FILE_TYPE* constants).

Constructor & Destructor Documentation

◆ trace_converter_t()

template<typename T >
trace_converter_t< T >::trace_converter_t ( void *  dcontext)

Construct a new trace_converter_t object. If a nullptr dcontext is passed, creates a new DR context va dr_standalone_init().

◆ ~trace_converter_t()

template<typename T >
trace_converter_t< T >::~trace_converter_t ( )

Destroys this trace_converter_t object. If a nullptr dcontext_in was passed to the constructor, calls dr_standalone_exit().

Member Function Documentation

◆ modvec_()

template<typename T >
const std::vector<module_t>& trace_converter_t< T >::modvec_ ( ) const

Get the module map.

◆ process_offline_entry()

template<typename T >
std::string trace_converter_t< T >::process_offline_entry ( void *  tls,
const offline_entry_t *  in_entry,
thread_id_t  tid,
OUT bool *  end_of_record,
OUT bool *  last_bb_handled 

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. set_modvec_() must have been called by the implementation before calling this API.

◆ read_header()

template<typename T >
std::string trace_converter_t< T >::read_header ( void *  tls,
OUT trace_header_t header 

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

◆ set_modvec_()

template<typename T >
void trace_converter_t< T >::set_modvec_ ( const std::vector< module_t > *  modvec)

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

Field Documentation

◆ dcontext_

template<typename T >
void* const trace_converter_t< T >::dcontext_

The pointer to the DR context.

◆ passed_dcontext_

template<typename T >
bool trace_converter_t< T >::passed_dcontext_ = false

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


template<typename T >
const uint trace_converter_t< T >::WRITE_BUFFER_SIZE = 64

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