DynamoRIO API
Protected Member Functions | Protected Attributes | Static Protected Attributes
trace_converter_t< T > Class Template Reference

#include <raw2trace.h>

Protected Member Functions

 trace_converter_t (void *dcontext_in)
 
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_in)
 

Protected Attributes

void *const dcontext
 

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.

  • 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(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 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.

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

    Return the instr_summary_t representation of the instruction at *pc, updating 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.

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

Constructor & Destructor Documentation

◆ trace_converter_t()

template<typename T>
trace_converter_t< T >::trace_converter_t ( void *  dcontext_in)
inlineprotected

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

Member Function Documentation

◆ modvec()

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

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

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

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_in)
inlineprotected

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
protected

The pointer to the DR context.

◆ WRITE_BUFFER_SIZE

template<typename T>
const uint trace_converter_t< 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: