DynamoRIO
dynamorio::drmemtrace Namespace Reference

Data Structures

struct  _memref_data_t
 
struct  _memref_flush_t
 
struct  _memref_instr_t
 
struct  _memref_marker_t
 
union  _memref_t
 
struct  _memref_thread_exit_t
 
struct  _trace_entry_t
 
class  analysis_tool_tmpl_t
 
class  analyzer_tmpl_t
 
class  bitset_hash_table_t
 
struct  cache_simulator_knobs_t
 
class  default_memtrace_stream_t
 
struct  drmemtrace_replace_file_ops_t
 
struct  instr_summary_t
 
class  ir2trace_t
 
class  memtrace_stream_t
 
class  module_mapper_t
 
struct  pt2ir_config_t
 
class  pt2ir_t
 
struct  pt_config_t
 
struct  pt_cpu_t
 
struct  pt_iscache_autoclean_t
 
struct  pt_sb_config_t
 
class  raw2trace_t
 
class  reader_t
 
class  record_file_reader_t
 
class  record_reader_t
 
struct  reuse_distance_knobs_t
 
class  scheduler_tmpl_t
 
class  speculator_tmpl_t
 
class  test_module_mapper_t
 
struct  tlb_simulator_knobs_t
 
struct  trace_header_t
 
struct  trace_metadata_reader_t
 
struct  trace_metadata_writer_t
 

Typedefs

typedef analysis_tool_tmpl_t< memref_tanalysis_tool_t
 
typedef analysis_tool_tmpl_t< trace_entry_trecord_analysis_tool_t
 
typedef analyzer_tmpl_t< memref_t, reader_tanalyzer_t
 
typedef analyzer_tmpl_t< trace_entry_t, dynamorio::drmemtrace::record_reader_trecord_analyzer_t
 
typedef file_t(* drmemtrace_open_file_func_t) (const char *fname, uint mode_flags)
 
typedef file_t(* drmemtrace_open_file_ex_func_t) (const char *fname, uint mode_flags, thread_id_t thread_id, int64 window_id)
 
typedef ssize_t(* drmemtrace_read_file_func_t) (file_t file, void *buf, size_t count)
 
typedef ssize_t(* drmemtrace_write_file_func_t) (file_t file, const void *data, size_t count)
 
typedef void(* drmemtrace_close_file_func_t) (file_t file)
 
typedef bool(* drmemtrace_create_dir_func_t) (const char *dir)
 
typedef bool(* drmemtrace_handoff_func_t) (file_t file, void *data, size_t data_size, size_t alloc_size)
 
typedef void(* drmemtrace_exit_func_t) (void *arg)
 
typedef int64_t memref_pid_t
 
typedef int64_t memref_tid_t
 
typedef union dynamorio::drmemtrace::_memref_t memref_t
 
typedef scheduler_tmpl_t< memref_t, reader_tscheduler_t
 
typedef scheduler_tmpl_t< trace_entry_t, dynamorio::drmemtrace::record_reader_trecord_scheduler_t
 
typedef speculator_tmpl_t< memref_tspeculator_t
 
typedef speculator_tmpl_t< trace_entry_trecord_speculator_t
 
typedef uintptr_t addr_t
 
typedef struct _trace_entry_t trace_entry_t
 

Enumerations

enum  shard_type_t {
  SHARD_BY_THREAD,
  SHARD_BY_DEFAULT = SHARD_BY_THREAD,
  SHARD_BY_CORE,
  SHARD_BY_THREAD,
  SHARD_BY_DEFAULT = SHARD_BY_THREAD,
  SHARD_BY_CORE
}
 
enum  drmemtrace_status_t {
  DRMEMTRACE_SUCCESS,
  DRMEMTRACE_ERROR,
  DRMEMTRACE_ERROR_INVALID_PARAMETER,
  DRMEMTRACE_ERROR_NOT_IMPLEMENTED
}
 
enum  ir2trace_convert_status_t {
  IR2TRACE_CONV_SUCCESS = 0,
  IR2TRACE_CONV_ERROR_INVALID_PARAMETER,
  IR2TRACE_CONV_SUCCESS = 0,
  IR2TRACE_CONV_ERROR_INVALID_PARAMETER
}
 
enum  pt2ir_convert_status_t {
  PT2IR_CONV_SUCCESS = 0,
  PT2IR_CONV_ERROR_INVALID_INPUT,
  PT2IR_CONV_ERROR_NOT_INITIALIZED,
  PT2IR_CONV_ERROR_RAW_TRACE_TOO_LARGE,
  PT2IR_CONV_ERROR_SYNC_PACKET,
  PT2IR_CONV_ERROR_HANDLE_SIDEBAND_EVENT,
  PT2IR_CONV_ERROR_GET_PENDING_EVENT,
  PT2IR_CONV_ERROR_SET_IMAGE,
  PT2IR_CONV_ERROR_DECODE_NEXT_INSTR,
  PT2IR_CONV_ERROR_DR_IR_CONVERT,
  PT2IR_CONV_SUCCESS = 0,
  PT2IR_CONV_ERROR_INVALID_INPUT,
  PT2IR_CONV_ERROR_NOT_INITIALIZED,
  PT2IR_CONV_ERROR_RAW_TRACE_TOO_LARGE,
  PT2IR_CONV_ERROR_SYNC_PACKET,
  PT2IR_CONV_ERROR_HANDLE_SIDEBAND_EVENT,
  PT2IR_CONV_ERROR_GET_PENDING_EVENT,
  PT2IR_CONV_ERROR_SET_IMAGE,
  PT2IR_CONV_ERROR_DECODE_NEXT_INSTR,
  PT2IR_CONV_ERROR_DR_IR_CONVERT
}
 
enum  pt_cpu_vendor_t {
  CPU_VENDOR_UNKNOWN = 0,
  CPU_VENDOR_INTEL,
  CPU_VENDOR_UNKNOWN = 0,
  CPU_VENDOR_INTEL
}
 
enum  trace_version_t {
  TRACE_ENTRY_VERSION_NO_KERNEL_PC = 2,
  TRACE_ENTRY_VERSION_KERNEL_PC = 3,
  TRACE_ENTRY_VERSION_ENCODINGS = 4,
  TRACE_ENTRY_VERSION_BRANCH_INFO = 5,
  TRACE_ENTRY_VERSION_FREQUENT_TIMESTAMPS = 6,
  TRACE_ENTRY_VERSION = TRACE_ENTRY_VERSION_FREQUENT_TIMESTAMPS
}
 
enum  trace_type_t {
  TRACE_TYPE_READ,
  TRACE_TYPE_WRITE,
  TRACE_TYPE_PREFETCH,
  TRACE_TYPE_PREFETCHT0,
  TRACE_TYPE_PREFETCH_READ_L1,
  TRACE_TYPE_PREFETCHT1,
  TRACE_TYPE_PREFETCH_READ_L2,
  TRACE_TYPE_PREFETCHT2,
  TRACE_TYPE_PREFETCH_READ_L3,
  TRACE_TYPE_PREFETCHNTA,
  TRACE_TYPE_PREFETCH_READ,
  TRACE_TYPE_PREFETCH_WRITE,
  TRACE_TYPE_PREFETCH_INSTR,
  TRACE_TYPE_INSTR,
  TRACE_TYPE_INSTR_DIRECT_JUMP,
  TRACE_TYPE_INSTR_INDIRECT_JUMP,
  TRACE_TYPE_INSTR_CONDITIONAL_JUMP,
  TRACE_TYPE_INSTR_DIRECT_CALL,
  TRACE_TYPE_INSTR_INDIRECT_CALL,
  TRACE_TYPE_INSTR_RETURN ,
  TRACE_TYPE_INSTR_FLUSH ,
  TRACE_TYPE_DATA_FLUSH ,
  TRACE_TYPE_THREAD_EXIT ,
  TRACE_TYPE_FOOTER,
  TRACE_TYPE_HARDWARE_PREFETCH,
  TRACE_TYPE_MARKER,
  TRACE_TYPE_INSTR_NO_FETCH ,
  TRACE_TYPE_INSTR_SYSENTER,
  TRACE_TYPE_PREFETCH_READ_L1_NT,
  TRACE_TYPE_PREFETCH_READ_L2_NT,
  TRACE_TYPE_PREFETCH_READ_L3_NT,
  TRACE_TYPE_PREFETCH_INSTR_L1,
  TRACE_TYPE_PREFETCH_INSTR_L1_NT,
  TRACE_TYPE_PREFETCH_INSTR_L2,
  TRACE_TYPE_PREFETCH_INSTR_L2_NT,
  TRACE_TYPE_PREFETCH_INSTR_L3,
  TRACE_TYPE_PREFETCH_INSTR_L3_NT,
  TRACE_TYPE_PREFETCH_WRITE_L1,
  TRACE_TYPE_PREFETCH_WRITE_L1_NT,
  TRACE_TYPE_PREFETCH_WRITE_L2,
  TRACE_TYPE_PREFETCH_WRITE_L2_NT,
  TRACE_TYPE_PREFETCH_WRITE_L3,
  TRACE_TYPE_PREFETCH_WRITE_L3_NT ,
  TRACE_TYPE_INSTR_TAKEN_JUMP,
  TRACE_TYPE_INSTR_UNTAKEN_JUMP,
  TRACE_TYPE_INVALID
}
 
enum  trace_marker_type_t {
  TRACE_MARKER_TYPE_KERNEL_EVENT,
  TRACE_MARKER_TYPE_KERNEL_XFER,
  TRACE_MARKER_TYPE_TIMESTAMP,
  TRACE_MARKER_TYPE_CPU_ID,
  TRACE_MARKER_TYPE_FUNC_ID,
  TRACE_MARKER_TYPE_FUNC_RETADDR,
  TRACE_MARKER_TYPE_FUNC_ARG,
  TRACE_MARKER_TYPE_FUNC_RETVAL ,
  TRACE_MARKER_TYPE_FILETYPE,
  TRACE_MARKER_TYPE_CACHE_LINE_SIZE,
  TRACE_MARKER_TYPE_INSTRUCTION_COUNT,
  TRACE_MARKER_TYPE_VERSION,
  TRACE_MARKER_TYPE_RSEQ_ABORT,
  TRACE_MARKER_TYPE_WINDOW_ID,
  TRACE_MARKER_TYPE_PHYSICAL_ADDRESS,
  TRACE_MARKER_TYPE_PHYSICAL_ADDRESS_NOT_AVAILABLE,
  TRACE_MARKER_TYPE_VIRTUAL_ADDRESS,
  TRACE_MARKER_TYPE_PAGE_SIZE,
  TRACE_MARKER_TYPE_SYSCALL_IDX,
  TRACE_MARKER_TYPE_CHUNK_INSTR_COUNT,
  TRACE_MARKER_TYPE_CHUNK_FOOTER,
  TRACE_MARKER_TYPE_RECORD_ORDINAL,
  TRACE_MARKER_TYPE_FILTER_ENDPOINT,
  TRACE_MARKER_TYPE_RSEQ_ENTRY,
  TRACE_MARKER_TYPE_SYSCALL,
  TRACE_MARKER_TYPE_MAYBE_BLOCKING_SYSCALL,
  TRACE_MARKER_TYPE_SYSCALL_TRACE_START,
  TRACE_MARKER_TYPE_SYSCALL_TRACE_END
}
 
enum  func_trace_t : uint64_t { func_trace_t::TRACE_FUNC_ID_SYSCALL_BASE = 0x100000000ULL }
 
enum  offline_file_type_t { ,
  OFFLINE_FILE_TYPE_FILTERED = 0x01 ,
  OFFLINE_FILE_TYPE_INSTRUCTION_ONLY = 0x04,
  OFFLINE_FILE_TYPE_ARCH_AARCH64 = 0x08,
  OFFLINE_FILE_TYPE_ARCH_ARM32 = 0x10,
  OFFLINE_FILE_TYPE_ARCH_X86_32 = 0x20,
  OFFLINE_FILE_TYPE_ARCH_X86_64 = 0x40,
  OFFLINE_FILE_TYPE_ARCH_ALL,
  OFFLINE_FILE_TYPE_IFILTERED = 0x80,
  OFFLINE_FILE_TYPE_DFILTERED = 0x100,
  OFFLINE_FILE_TYPE_ENCODINGS = 0x200,
  OFFLINE_FILE_TYPE_SYSCALL_NUMBERS = 0x400,
  OFFLINE_FILE_TYPE_BLOCKING_SYSCALLS = 0x800,
  OFFLINE_FILE_TYPE_KERNEL_SYSCALLS = 0x1000,
  OFFLINE_FILE_TYPE_BIMODAL_FILTERED_WARMUP = 0x2000
}
 
enum  ir2trace_convert_status_t {
  IR2TRACE_CONV_SUCCESS = 0,
  IR2TRACE_CONV_ERROR_INVALID_PARAMETER,
  IR2TRACE_CONV_SUCCESS = 0,
  IR2TRACE_CONV_ERROR_INVALID_PARAMETER
}
 
enum  pt2ir_convert_status_t {
  PT2IR_CONV_SUCCESS = 0,
  PT2IR_CONV_ERROR_INVALID_INPUT,
  PT2IR_CONV_ERROR_NOT_INITIALIZED,
  PT2IR_CONV_ERROR_RAW_TRACE_TOO_LARGE,
  PT2IR_CONV_ERROR_SYNC_PACKET,
  PT2IR_CONV_ERROR_HANDLE_SIDEBAND_EVENT,
  PT2IR_CONV_ERROR_GET_PENDING_EVENT,
  PT2IR_CONV_ERROR_SET_IMAGE,
  PT2IR_CONV_ERROR_DECODE_NEXT_INSTR,
  PT2IR_CONV_ERROR_DR_IR_CONVERT,
  PT2IR_CONV_SUCCESS = 0,
  PT2IR_CONV_ERROR_INVALID_INPUT,
  PT2IR_CONV_ERROR_NOT_INITIALIZED,
  PT2IR_CONV_ERROR_RAW_TRACE_TOO_LARGE,
  PT2IR_CONV_ERROR_SYNC_PACKET,
  PT2IR_CONV_ERROR_HANDLE_SIDEBAND_EVENT,
  PT2IR_CONV_ERROR_GET_PENDING_EVENT,
  PT2IR_CONV_ERROR_SET_IMAGE,
  PT2IR_CONV_ERROR_DECODE_NEXT_INSTR,
  PT2IR_CONV_ERROR_DR_IR_CONVERT
}
 
enum  pt_cpu_vendor_t {
  CPU_VENDOR_UNKNOWN = 0,
  CPU_VENDOR_INTEL,
  CPU_VENDOR_UNKNOWN = 0,
  CPU_VENDOR_INTEL
}
 
enum  shard_type_t {
  SHARD_BY_THREAD,
  SHARD_BY_DEFAULT = SHARD_BY_THREAD,
  SHARD_BY_CORE,
  SHARD_BY_THREAD,
  SHARD_BY_DEFAULT = SHARD_BY_THREAD,
  SHARD_BY_CORE
}
 

Functions

analysis_tool_tbasic_counts_tool_create (unsigned int verbose=0)
 
analysis_tool_tcache_simulator_create (const cache_simulator_knobs_t &knobs)
 
analysis_tool_tcache_simulator_create (const std::string &config_file)
 
analysis_tool_tcache_miss_analyzer_create (const cache_simulator_knobs_t &knobs, unsigned int miss_count_threshold, double miss_frac_threshold, double confidence_threshold)
 
DR_EXPORT void drmemtrace_client_main (client_id_t id, int argc, const char *argv[])
 
DR_EXPORT drmemtrace_status_t drmemtrace_replace_file_ops (drmemtrace_open_file_func_t open_file_func, drmemtrace_read_file_func_t read_file_func, drmemtrace_write_file_func_t write_file_func, drmemtrace_close_file_func_t close_file_func, drmemtrace_create_dir_func_t create_dir_func)
 
DR_EXPORT drmemtrace_status_t drmemtrace_buffer_handoff (drmemtrace_handoff_func_t handoff_func, drmemtrace_exit_func_t exit_func, void *exit_func_arg)
 
DR_EXPORT drmemtrace_status_t drmemtrace_replace_file_ops_ex (drmemtrace_replace_file_ops_t *ops)
 
DR_EXPORT drmemtrace_status_t drmemtrace_get_output_path (OUT const char **path)
 
DR_EXPORT drmemtrace_status_t drmemtrace_get_modlist_path (OUT const char **path)
 
DR_EXPORT drmemtrace_status_t drmemtrace_get_funclist_path (OUT const char **path)
 
DR_EXPORT drmemtrace_status_t drmemtrace_get_encoding_path (OUT const char **path)
 
DR_EXPORT drmemtrace_status_t drmemtrace_custom_module_data (void *(*load_cb)(module_data_t *module, int seg_idx), int(*print_cb)(void *data, char *dst, size_t max_len), void(*free_cb)(void *data))
 
drmemtrace_status_t drmemtrace_filter_threads (bool(*should_trace_thread_cb)(thread_id_t tid, void *user_data), void *user_value)
 
DR_EXPORT drmemtrace_status_t drmemtrace_get_timestamp_from_offline_trace (const void *trace, size_t trace_size, OUT uint64 *timestamp)
 
analysis_tool_tfunc_view_tool_create (const std::string &funclist_file_path, bool full_trace, unsigned int verbose=0)
 
analysis_tool_thistogram_tool_create (unsigned int line_size=64, unsigned int report_top=10, unsigned int verbose=0)
 
analysis_tool_topcode_mix_tool_create (const std::string &module_file_path, unsigned int verbose=0, const std::string &alt_module_dir="")
 
analysis_tool_treuse_distance_tool_create (const reuse_distance_knobs_t &knobs)
 
analysis_tool_treuse_time_tool_create (unsigned int line_size=64, unsigned int verbose=0)
 
analysis_tool_tsyscall_mix_tool_create (unsigned int verbose=0)
 
analysis_tool_ttlb_simulator_create (const tlb_simulator_knobs_t &knobs)
 
static bool type_is_instr (const trace_type_t type)
 
static bool type_is_instr_branch (const trace_type_t type)
 
static bool type_is_instr_direct_branch (const trace_type_t type)
 
static bool type_is_instr_conditional_branch (const trace_type_t type)
 
static bool type_is_prefetch (const trace_type_t type)
 
static bool type_has_address (const trace_type_t type)
 
static bool type_is_data (const trace_type_t type)
 
static bool type_is_read (const trace_type_t type)
 
analysis_tool_tview_tool_create (const std::string &module_file_path, uint64_t skip_refs, uint64_t sim_refs, const std::string &syntax, unsigned int verbose=0, const std::string &alt_module_dir="")
 

Detailed Description

< General DynamoRIO namespace.

Typedef Documentation

◆ addr_t

typedef uintptr_t dynamorio::drmemtrace::addr_t

< DrMemtrace tracing + simulation infrastructure namespace. The type of a memory address.

◆ analysis_tool_t

◆ analyzer_t

◆ drmemtrace_close_file_func_t

typedef void(* dynamorio::drmemtrace::drmemtrace_close_file_func_t) (file_t file)

Function for file close. The example behavior is described in dr_close_file();

Parameters
[in]fileThe file to be closed.

◆ drmemtrace_create_dir_func_t

typedef bool(* dynamorio::drmemtrace::drmemtrace_create_dir_func_t) (const char *dir)

Function for directory creation. The example behavior is described in dr_create_dir();

Parameters
[in]dirThe directory name for creation.
Returns
whether successful.

◆ drmemtrace_exit_func_t

typedef void(* dynamorio::drmemtrace::drmemtrace_exit_func_t) (void *arg)

Function for process exit. This is called during the tracer shutdown, giving a control point where DR memory may be accessed, which is not possible when acting after dr_app_stop_and_cleanup().

Parameters
[in]argThe exit_func_arg passed to drmemtrace_buffer_handoff().

◆ drmemtrace_handoff_func_t

typedef bool(* dynamorio::drmemtrace::drmemtrace_handoff_func_t) (file_t file, void *data, size_t data_size, size_t alloc_size)

Function for buffer handoff. Rather than writing a buffer to a file when it is full, instead this handoff function gives ownership to the callee. The tracer allocates a new buffer and uses it for further tracing. The callee is responsible for writing out the buffer and for freeing it by calling dr_raw_mem_free().

Parameters
[in]fileThe file identifier returned by open_file_func or or drmemtrace_replace_file_ops() was not called then from dr_open_file() for the per-thread trace file.
[in]dataThe start address of the buffer.
[in]data_sizeThe size of valid trace data in the buffer.
[in]alloc_sizeThe allocated size of the buffer.
Returns
whether successful. Failure is considered unrecoverable.

◆ drmemtrace_open_file_ex_func_t

typedef file_t(* dynamorio::drmemtrace::drmemtrace_open_file_ex_func_t) (const char *fname, uint mode_flags, thread_id_t thread_id, int64 window_id)

Function for extended file open. The file access mode is set by the mode_flags argument which is drawn from the DR_FILE_* defines ORed together. Returns INVALID_FILE if unsuccessful. The example behavior is described in dr_open_file();

Parameters
[in]fnameThe filename to open.
[in]mode_flagsThe DR_FILE_* flags for file open.
[in]thread_idThe application thread id targeted by this file. For special files (drmemtrace_get_modlist_path(), drmemtrace_get_funclist_path(), drmemtrace_get_encoding_path(), or PT files), this will be 0.
[in]window_idThe tracing window id for this file. For special files (drmemtrace_get_modlist_path(), drmemtrace_get_funclist_path(), drmemtrace_get_encoding_path(), or PT files), this will be -1.
Returns
the opened file id.

◆ drmemtrace_open_file_func_t

typedef file_t(* dynamorio::drmemtrace::drmemtrace_open_file_func_t) (const char *fname, uint mode_flags)

Function for file open. The file access mode is set by the mode_flags argument which is drawn from the DR_FILE_* defines ORed together. Returns INVALID_FILE if unsuccessful. The example behavior is described in dr_open_file();

Parameters
[in]fnameThe filename to open.
[in]mode_flagsThe DR_FILE_* flags for file open.
Returns
the opened file id.
Note
For additional parameters with the thread and window identifiers, use drmemtrace_open_file_ex_func_t and drmemtrace_replace_file_ops_ex().

◆ drmemtrace_read_file_func_t

typedef ssize_t(* dynamorio::drmemtrace::drmemtrace_read_file_func_t) (file_t file, void *buf, size_t count)

Function for file read. Reads up to count bytes from file file into buf. Returns the actual number read. The example behavior is described in dr_read_file();

Parameters
[in]fileThe file to be read from.
[in]bufThe buffer to be read to.
[in]countThe number of bytes to be read.
Returns
the actual number of bytes read.

◆ drmemtrace_write_file_func_t

typedef ssize_t(* dynamorio::drmemtrace::drmemtrace_write_file_func_t) (file_t file, const void *data, size_t count)

Function for file write. Writes count bytes from data to file file. Returns the actual number written. The example behavior is described in dr_write_file();

Parameters
[in]fileThe file to be written.
[in]dataThe data to be written.
[in]countThe number of bytes to be written.
Returns
the actual number of bytes written.

◆ memref_pid_t

< DrMemtrace tracing + simulation infrastructure namespace. Process id type.

◆ memref_t

Each trace entry is one of the structures in this union. Each entry identifies the originating process and thread. Although the pc of each data reference is provided, the trace also guarantees that an instruction entry immediately precedes the data references that it is responsible for, with no intervening trace entries (unless it is a trace filtered with an online first-level cache). Offline traces further guarantee that an instruction entry for a branch instruction is always followed by an instruction entry for the branch's target (with any memory references for the branch in between of course) without a thread switch intervening, to make it simpler to identify branch targets (again, unless the trace is filtered by an online first-level cache). Online traces do not currently guarantee this.

◆ memref_tid_t

Thread id type.

◆ record_analysis_tool_t

◆ record_analyzer_t

◆ record_scheduler_t

◆ record_speculator_t

◆ scheduler_t

◆ speculator_t

◆ trace_entry_t

Enumeration Type Documentation

◆ drmemtrace_status_t

Status return values from drmemtrace functions.

Enumerator
DRMEMTRACE_SUCCESS 

Operation succeeded.

DRMEMTRACE_ERROR 

Operation failed.

DRMEMTRACE_ERROR_INVALID_PARAMETER 

Operation failed: invalid parameter.

DRMEMTRACE_ERROR_NOT_IMPLEMENTED 

Operation failed: not implemented.

◆ func_trace_t

enum dynamorio::drmemtrace::func_trace_t : uint64_t
strong

Constants related to function or system call parameter tracing.

Enumerator
TRACE_FUNC_ID_SYSCALL_BASE 

When system call parameter and return values are provided, they use the function tracing markers TRACE_MARKER_TYPE_FUNC_ID, TRACE_MARKER_TYPE_FUNC_ARG, and TRACE_MARKER_TYPE_FUNC_RETVAL. The identifier used for TRACE_MARKER_TYPE_FUNC_ID is equal to this base value plus the 32-bit system call number for 64-bit marker values or this base value plus the lower 16 bits of the system call number for 32-bit marker values.

◆ ir2trace_convert_status_t [1/2]

The type of ir2trace_t::convert() return value.

Enumerator
IR2TRACE_CONV_SUCCESS 

The conversion process succeeded.

IR2TRACE_CONV_ERROR_INVALID_PARAMETER 

The conversion process failed: invalid parameter.

IR2TRACE_CONV_SUCCESS 

The conversion process succeeded.

IR2TRACE_CONV_ERROR_INVALID_PARAMETER 

The conversion process failed: invalid parameter.

◆ ir2trace_convert_status_t [2/2]

The type of ir2trace_t::convert() return value.

Enumerator
IR2TRACE_CONV_SUCCESS 

The conversion process succeeded.

IR2TRACE_CONV_ERROR_INVALID_PARAMETER 

The conversion process failed: invalid parameter.

IR2TRACE_CONV_SUCCESS 

The conversion process succeeded.

IR2TRACE_CONV_ERROR_INVALID_PARAMETER 

The conversion process failed: invalid parameter.

◆ offline_file_type_t

Bitfields used to describe the high-level characteristics of both an offline final trace and a raw not-yet-postprocessed trace, as well as (despite the OFFLINE_ prefix) an online trace. In a final trace these are stored in a marker of type TRACE_MARKER_TYPE_FILETYPE.

Enumerator
OFFLINE_FILE_TYPE_FILTERED 

DEPRECATED: Addresses filtered online. Newer trace files use OFFLINE_FILE_TYPE_IFILTERED and OFFLINE_FILE_TYPE_DFILTERED.

OFFLINE_FILE_TYPE_INSTRUCTION_ONLY 

Trace has no data references.

OFFLINE_FILE_TYPE_ARCH_AARCH64 

Recorded on AArch64.

OFFLINE_FILE_TYPE_ARCH_ARM32 

Recorded on ARM (32-bit).

OFFLINE_FILE_TYPE_ARCH_X86_32 

Recorded on x86 (32-bit).

OFFLINE_FILE_TYPE_ARCH_X86_64 

Recorded on x86 (64-bit).

OFFLINE_FILE_TYPE_ARCH_ALL 

All possible architecture types.

OFFLINE_FILE_TYPE_IFILTERED 

Instruction addresses filtered online. Note: this file type may transition to non-filtered. If so, the transition is indicated by the dynamorio::drmemtrace::TRACE_MARKER_TYPE_FILTER_ENDPOINT marker and the OFFLINE_FILE_TYPE_BIMODAL_FILTERED_WARMUP file type. Each window (which is indicated by the dynamorio::drmemtrace::TRACE_MARKER_TYPE_WINDOW_ID marker) starts out filtered. This applies to dynamorio::drmemtrace::OFFLINE_FILE_TYPE_DFILTERED also. Note that threads that were created after the transition will also have this marker - right at the beginning.

OFFLINE_FILE_TYPE_DFILTERED 

Data addresses filtered online.

OFFLINE_FILE_TYPE_ENCODINGS 

Instruction encodings are included.

OFFLINE_FILE_TYPE_SYSCALL_NUMBERS 

System call number markers (TRACE_MARKER_TYPE_SYSCALL) are included.

OFFLINE_FILE_TYPE_BLOCKING_SYSCALLS 

Kernel scheduling information is included: TRACE_MARKER_TYPE_MAYBE_BLOCKING_SYSCALL markers and system call parameters and return values for kernel locks (SYS_futex on Linux) using the function tracing markers TRACE_MARKER_TYPE_FUNC_ID, TRACE_MARKER_TYPE_FUNC_ARG, and TRACE_MARKER_TYPE_FUNC_RETVAL with an identifier equal to func_trace_t::TRACE_FUNC_ID_SYSCALL_BASE plus the system call number (or its bottom 16 bits for 32-bit marker values). These identifiers are not stored in the function list file (drmemtrace_get_funclist_path()).

The TRACE_MARKER_TYPE_FUNC_RETVAL for system calls is either 0 (failure) or 1 (success).

OFFLINE_FILE_TYPE_KERNEL_SYSCALLS 

Kernel traces of syscalls are included. The included kernel traces are in the IntelĀ® Processor Trace format.

OFFLINE_FILE_TYPE_BIMODAL_FILTERED_WARMUP 

Partially filtered trace. The initial part up to the TRACE_MARKER_TYPE_FILTER_ENDPOINT marker is filtered, and the later part is not. Look for other filtering-related file types (OFFLINE_FILE_TYPE_IFILTERED and OFFLINE_FILE_TYPE_DFILTERED) to determine how the initial part was filtered. The initial part can be used by a simulator for warmup.

◆ pt2ir_convert_status_t [1/2]

The type of pt2ir_t::convert() return value.

Enumerator
PT2IR_CONV_SUCCESS 

The conversion process is successful.

PT2IR_CONV_ERROR_INVALID_INPUT 

The conversion process fail to initiate for invalid input.

PT2IR_CONV_ERROR_NOT_INITIALIZED 

The conversion process failed to initiate because the instance was not initialized.

PT2IR_CONV_ERROR_RAW_TRACE_TOO_LARGE 

The conversion process failed to initiate because it attempted to copy a large amount of PT data into the raw buffer that was too small to accommodate it.

PT2IR_CONV_ERROR_SYNC_PACKET 

The conversion process ends with a failure to sync to the PSB packet.

PT2IR_CONV_ERROR_HANDLE_SIDEBAND_EVENT 

The conversion process ends with a failure to handle a perf event.

PT2IR_CONV_ERROR_GET_PENDING_EVENT 

The conversion process ends with a failure to get the pending event.

PT2IR_CONV_ERROR_SET_IMAGE 

The conversion process ends with a failure to set the new image.

PT2IR_CONV_ERROR_DECODE_NEXT_INSTR 

The conversion process ends with a failure to decode the next instruction.

PT2IR_CONV_ERROR_DR_IR_CONVERT 

The conversion process ends with a failure to convert the libipt's IR to Dynamorio's IR.

PT2IR_CONV_SUCCESS 

The conversion process is successful.

PT2IR_CONV_ERROR_INVALID_INPUT 

The conversion process fail to initiate for invalid input.

PT2IR_CONV_ERROR_NOT_INITIALIZED 

The conversion process failed to initiate because the instance was not initialized.

PT2IR_CONV_ERROR_RAW_TRACE_TOO_LARGE 

The conversion process failed to initiate because it attempted to copy a large amount of PT data into the raw buffer that was too small to accommodate it.

PT2IR_CONV_ERROR_SYNC_PACKET 

The conversion process ends with a failure to sync to the PSB packet.

PT2IR_CONV_ERROR_HANDLE_SIDEBAND_EVENT 

The conversion process ends with a failure to handle a perf event.

PT2IR_CONV_ERROR_GET_PENDING_EVENT 

The conversion process ends with a failure to get the pending event.

PT2IR_CONV_ERROR_SET_IMAGE 

The conversion process ends with a failure to set the new image.

PT2IR_CONV_ERROR_DECODE_NEXT_INSTR 

The conversion process ends with a failure to decode the next instruction.

PT2IR_CONV_ERROR_DR_IR_CONVERT 

The conversion process ends with a failure to convert the libipt's IR to Dynamorio's IR.

◆ pt2ir_convert_status_t [2/2]

The type of pt2ir_t::convert() return value.

Enumerator
PT2IR_CONV_SUCCESS 

The conversion process is successful.

PT2IR_CONV_ERROR_INVALID_INPUT 

The conversion process fail to initiate for invalid input.

PT2IR_CONV_ERROR_NOT_INITIALIZED 

The conversion process failed to initiate because the instance was not initialized.

PT2IR_CONV_ERROR_RAW_TRACE_TOO_LARGE 

The conversion process failed to initiate because it attempted to copy a large amount of PT data into the raw buffer that was too small to accommodate it.

PT2IR_CONV_ERROR_SYNC_PACKET 

The conversion process ends with a failure to sync to the PSB packet.

PT2IR_CONV_ERROR_HANDLE_SIDEBAND_EVENT 

The conversion process ends with a failure to handle a perf event.

PT2IR_CONV_ERROR_GET_PENDING_EVENT 

The conversion process ends with a failure to get the pending event.

PT2IR_CONV_ERROR_SET_IMAGE 

The conversion process ends with a failure to set the new image.

PT2IR_CONV_ERROR_DECODE_NEXT_INSTR 

The conversion process ends with a failure to decode the next instruction.

PT2IR_CONV_ERROR_DR_IR_CONVERT 

The conversion process ends with a failure to convert the libipt's IR to Dynamorio's IR.

PT2IR_CONV_SUCCESS 

The conversion process is successful.

PT2IR_CONV_ERROR_INVALID_INPUT 

The conversion process fail to initiate for invalid input.

PT2IR_CONV_ERROR_NOT_INITIALIZED 

The conversion process failed to initiate because the instance was not initialized.

PT2IR_CONV_ERROR_RAW_TRACE_TOO_LARGE 

The conversion process failed to initiate because it attempted to copy a large amount of PT data into the raw buffer that was too small to accommodate it.

PT2IR_CONV_ERROR_SYNC_PACKET 

The conversion process ends with a failure to sync to the PSB packet.

PT2IR_CONV_ERROR_HANDLE_SIDEBAND_EVENT 

The conversion process ends with a failure to handle a perf event.

PT2IR_CONV_ERROR_GET_PENDING_EVENT 

The conversion process ends with a failure to get the pending event.

PT2IR_CONV_ERROR_SET_IMAGE 

The conversion process ends with a failure to set the new image.

PT2IR_CONV_ERROR_DECODE_NEXT_INSTR 

The conversion process ends with a failure to decode the next instruction.

PT2IR_CONV_ERROR_DR_IR_CONVERT 

The conversion process ends with a failure to convert the libipt's IR to Dynamorio's IR.

◆ pt_cpu_vendor_t [1/2]

The types of the CPU vendor.

Enumerator
CPU_VENDOR_UNKNOWN 

The CPU vendor is unknown.

CPU_VENDOR_INTEL 

The CPU vendor is Intel.

CPU_VENDOR_UNKNOWN 

The CPU vendor is unknown.

CPU_VENDOR_INTEL 

The CPU vendor is Intel.

◆ pt_cpu_vendor_t [2/2]

The types of the CPU vendor.

Enumerator
CPU_VENDOR_UNKNOWN 

The CPU vendor is unknown.

CPU_VENDOR_INTEL 

The CPU vendor is Intel.

CPU_VENDOR_UNKNOWN 

The CPU vendor is unknown.

CPU_VENDOR_INTEL 

The CPU vendor is Intel.

◆ shard_type_t [1/2]

Identifies the type of shard.

Enumerator
SHARD_BY_THREAD 

Sharded by software thread.

SHARD_BY_DEFAULT 

Default shard type.

SHARD_BY_CORE 

Sharded by hardware core.

SHARD_BY_THREAD 

Sharded by software thread.

SHARD_BY_DEFAULT 

Default shard type.

SHARD_BY_CORE 

Sharded by hardware core.

◆ shard_type_t [2/2]

Identifies the type of shard.

Enumerator
SHARD_BY_THREAD 

Sharded by software thread.

SHARD_BY_DEFAULT 

Default shard type.

SHARD_BY_CORE 

Sharded by hardware core.

SHARD_BY_THREAD 

Sharded by software thread.

SHARD_BY_DEFAULT 

Default shard type.

SHARD_BY_CORE 

Sharded by hardware core.

◆ trace_marker_type_t

The sub-type for TRACE_TYPE_MARKER.

Enumerator
TRACE_MARKER_TYPE_KERNEL_EVENT 

The subsequent instruction is the start of a handler for a kernel-initiated event: a signal handler or restartable sequence abort handler on UNIX, or an APC, exception, or callback dispatcher on Windows. The value of this marker contains the program counter at the kernel interruption point. If the interruption point is just after a branch, this value is the target of that branch. (For trace version TRACE_ENTRY_VERSION_NO_KERNEL_PC or below, the value is the module offset rather than the absolute program counter.) The value is 0 for some types where this information is not available, namely Windows callbacks. A restartable sequence abort handler is further identified by a prior marker of type TRACE_MARKER_TYPE_RSEQ_ABORT.

TRACE_MARKER_TYPE_KERNEL_XFER 

The subsequent instruction is the target of a system call that changes the context: a signal return on UNIX, or a callback return or NtContinue or NtSetContextThread on Windows.

TRACE_MARKER_TYPE_TIMESTAMP 

The marker value contains a timestamp for this point in the trace, in units of microseconds since Jan 1, 1601 (the UTC time). For 32-bit, the value is truncated to 32 bits.

TRACE_MARKER_TYPE_CPU_ID 

The marker value contains the cpu identifier of the cpu this thread was running on at this point in the trace. A value of (uintptr_t)-1 indicates that the cpu could not be determined. This value contains what the operating system set up. For Linux, the bottom 12 bits hold the cpu identifier and the upper bits hold the socket/node number.

TRACE_MARKER_TYPE_FUNC_ID 

The marker value contains the function id for functions traced by the user via the -record_function (and -record_heap_value if -record_heap is specified) option. The mapping from this numeric ID to a library-qualified symbolic name is recorded during tracing in a file "funclist.log" whose format is described by the drmemtrace_get_funclist_path() function's documentation.

This marker is also used to record parameter values for certain system calls such as for OFFLINE_FILE_TYPE_BLOCKING_SYSCALLS. These use large identifiers equal to func_trace_t::TRACE_FUNC_ID_SYSCALL_BASE plus the system call number (for 32-bit marker values just the bottom 16 bits of the system call number are added to the base). These identifiers are not stored in the function list file (drmemtrace_get_funclist_path()). The system call number used is the value passed to DynamoRIO's dr_register_pre_syscall_event() which is normalized to match SYS_ constants (see the dr_register_pre_syscall_event() documentation regarding MacOS).

TRACE_MARKER_TYPE_FUNC_RETADDR 

The marker value contains the return address of the just-entered function, whose id is specified by the closest previous TRACE_MARKER_TYPE_FUNC_ID marker entry.

TRACE_MARKER_TYPE_FUNC_ARG 

The marker value contains one argument value of the just-entered function, whose id is specified by the closest previous TRACE_MARKER_TYPE_FUNC_ID marker entry. The number of such entries for one function invocation is equal to the specified argument in -record_function (or pre-defined functions in -record_heap_value if -record_heap is specified).

TRACE_MARKER_TYPE_FUNC_RETVAL 

The marker value contains the return value of the just-entered function, whose id is specified by the closest previous TRACE_MARKER_TYPE_FUNC_ID marker entry

The marker value for system calls (see func_trace_t::TRACE_FUNC_ID_SYSCALL_BASE) is either 0 (failure) or 1 (success), as obtained from dr_syscall_get_result_ex() via the "succeeded" field of dr_syscall_result_info_t. See the corresponding documentation for caveats about the accuracy of this value.

TRACE_MARKER_TYPE_FILETYPE 

The marker value contains the OFFLINE_FILE_TYPE_* bitfields of type offline_file_type_t identifying the architecture and other key high-level attributes of the trace.

TRACE_MARKER_TYPE_CACHE_LINE_SIZE 

The marker value contains the traced processor's cache line size in bytes.

TRACE_MARKER_TYPE_INSTRUCTION_COUNT 

The marker value contains the count of dynamic instruction executions in this software thread since the start of the trace. This marker type is only present in online-cache-filtered traces and is placed at thread exit.

TRACE_MARKER_TYPE_VERSION 

The marker value contains the version of the trace format: a value of type trace_version_t. The marker is present in the first few entries of a trace file.

TRACE_MARKER_TYPE_RSEQ_ABORT 

Serves to further identify TRACE_MARKER_TYPE_KERNEL_EVENT as a restartable sequence abort handler. This will always be immediately followed by TRACE_MARKER_TYPE_KERNEL_EVENT. The marker value for a signal that interrupted the instrumented execution is the precise interrupted PC, but for all other cases the value holds the continuation program counter, which is the restartable sequence abort handler. (The precise interrupted point inside the sequence is not provided by the kernel.)

TRACE_MARKER_TYPE_WINDOW_ID 

Identifies in the marker value the ordinal of a window during a multi-window tracing run (see the options -trace_for_instrs and -retrace_every_instrs). When a marker with an ordinal value different from the last-seen marker appears, a time gap may exist immediately before this new marker.

TRACE_MARKER_TYPE_PHYSICAL_ADDRESS 

The marker value contains the physical address corresponding to the subsequent TRACE_MARKER_TYPE_VIRTUAL_ADDRESS's virtual address. A pair of such markers will appear somewhere prior to a regular instruction fetch or data load or store whose page's physical address has not yet been reported, or when a physical mapping change is detected. If translation failed, a TRACE_MARKER_TYPE_PHYSICAL_ADDRESS_NOT_AVAILABLE will be present instead, without a corresponding TRACE_MARKER_TYPE_VIRTUAL_ADDRESS.

TRACE_MARKER_TYPE_PHYSICAL_ADDRESS_NOT_AVAILABLE 

Indicates a failure to obtain the physical address corresponding to the virtual address contained in the marker value.

TRACE_MARKER_TYPE_VIRTUAL_ADDRESS 

The marker value contains the virtual address corresponding to the prior TRACE_MARKER_TYPE_PHYSICAL_ADDRESS's physical address. A pair of such markers will appear somewhere prior to a regular instruction fetch or data load or store whose page's physical address has not yet been reported, or when a physical mapping change is detected. If translation failed, a TRACE_MARKER_TYPE_PHYSICAL_ADDRESS_NOT_AVAILABLE will be present instead, without a corresponding TRACE_MARKER_TYPE_VIRTUAL_ADDRESS.

TRACE_MARKER_TYPE_PAGE_SIZE 

The marker value contains the traced process's page size in bytes.

TRACE_MARKER_TYPE_SYSCALL_IDX 

This marker is emitted prior to each system call when -enable_kernel_tracing is specified. The marker value contains a unique identifier for the system call within a specific thread.

Note
This marker serves solely to indicate when to decode the syscall's PT trace and will not be included in the final complete trace. Instead, we utilize TRACE_MARKER_TYPE_SYSCALL_TRACE_START and TRACE_MARKER_TYPE_SYSCALL_TRACE_END to signify the beginning and end of a syscall's PT trace in the final trace.
TRACE_MARKER_TYPE_CHUNK_INSTR_COUNT 

This top-level marker identifies the instruction count in each chunk of the output file. This is the granularity of a fast seek.

TRACE_MARKER_TYPE_CHUNK_FOOTER 

Marks the end of a chunk. The final chunk does not have such a marker but instead relies on the TRACE_TYPE_FOOTER entry.

TRACE_MARKER_TYPE_RECORD_ORDINAL 

Indicates the record ordinal for this point in the trace. This is used to identify the visible record ordinal when skipping over chunks, and is not exposed to analysis tools.

TRACE_MARKER_TYPE_FILTER_ENDPOINT 

Indicates the point in the trace where filtering ended. It is accompanied by dynamorio::drmemtrace::OFFLINE_FILE_TYPE_BIMODAL_FILTERED_WARMUP in the file type. This is added by the record_filter tool and also by the drmemtrace tracer (with -L0_filter_until_instrs) to annotate when the warmup part of the trace ended.

TRACE_MARKER_TYPE_RSEQ_ENTRY 

Indicates the start of an "rseq" (Linux restartable sequence) region. The marker value holds the end PC of the region (this is the PC after the committing store).

TRACE_MARKER_TYPE_SYSCALL 

This marker is emitted prior to each system call invocation, after the instruction fetch entry for the system call gateway instruction from user mode. The marker value contains the system call number. If these markers are present, the file type OFFLINE_FILE_TYPE_SYSCALL_NUMBERS is set.

TRACE_MARKER_TYPE_MAYBE_BLOCKING_SYSCALL 

This marker is emitted prior to a system call which is known to block under some circumstances. Whether it blocks may depend on the values of parameters or the state of options set in prior system calls. Additionally, it is not guaranteed that every system call that might block is identified in the initial implementation, and it may be limited only to certain operating systems (Linux only for now).

If these markers are present, the file type OFFLINE_FILE_TYPE_BLOCKING_SYSCALLS is set. The marker value is 0.

TRACE_MARKER_TYPE_SYSCALL_TRACE_START 

Indicates a point in the trace where a syscall's kernel trace starts.

TRACE_MARKER_TYPE_SYSCALL_TRACE_END 

Indicates a point in the trace where a syscall's trace end.

◆ trace_type_t

The type of a trace entry in a memref_t structure.

Enumerator
TRACE_TYPE_READ 

A data load.

TRACE_TYPE_WRITE 

A data store.

TRACE_TYPE_PREFETCH 

A general prefetch.

TRACE_TYPE_PREFETCHT0 

An x86 prefetch to all levels of the cache.

TRACE_TYPE_PREFETCH_READ_L1 

Load prefetch to L1 cache.

TRACE_TYPE_PREFETCHT1 

An x86 prefetch to level 2 cache and higher.

TRACE_TYPE_PREFETCH_READ_L2 

Load prefetch to L2 cache.

TRACE_TYPE_PREFETCHT2 

An x86 prefetch to level 3 cache and higher.

TRACE_TYPE_PREFETCH_READ_L3 

Load prefetch to L3 cache.

TRACE_TYPE_PREFETCHNTA 

An x86 non-temporal prefetch.

TRACE_TYPE_PREFETCH_READ 

An ARM load prefetch.

TRACE_TYPE_PREFETCH_WRITE 

An ARM store prefetch.

TRACE_TYPE_PREFETCH_INSTR 

An ARM insruction prefetch.

TRACE_TYPE_INSTR 

A non-branch instruction.

TRACE_TYPE_INSTR_DIRECT_JUMP 

A direct unconditional jump instruction.

TRACE_TYPE_INSTR_INDIRECT_JUMP 

An indirect jump instruction.

TRACE_TYPE_INSTR_CONDITIONAL_JUMP 

A direct conditional jump instruction.

Deprecated:
For offline non-i-filtered traces, this is deprecated and is only present in versions below TRACE_ENTRY_VERSION_BRANCH_INFO. Newer version used TRACE_TYPE_INSTR_TAKEN_JUMP and TRACE_TYPE_INSTR_UNTAKEN_JUMP instead.
TRACE_TYPE_INSTR_DIRECT_CALL 

A direct call instruction.

TRACE_TYPE_INSTR_INDIRECT_CALL 

An indirect call instruction.

TRACE_TYPE_INSTR_RETURN 

A return instruction.

TRACE_TYPE_INSTR_FLUSH 

An instruction cache flush.

TRACE_TYPE_DATA_FLUSH 

A data cache flush.

TRACE_TYPE_THREAD_EXIT 

A thread exit.

TRACE_TYPE_FOOTER 

The final entry in an offline file or a pipe. Not exposed to tools.

TRACE_TYPE_HARDWARE_PREFETCH 

A hardware-issued prefetch (generated after tracing by a cache simulator).

TRACE_TYPE_MARKER 

A marker containing metadata about this point in the trace. It includes a marker sub-type trace_marker_type_t and a value.

TRACE_TYPE_INSTR_NO_FETCH 

For core simulators, a trace includes instructions that do not incur instruction cache fetches, such as on each subsequent iteration of a rep string loop on x86.

TRACE_TYPE_INSTR_SYSENTER 

We separate out the x86 sysenter instruction as it has a hardcoded return point that shows up as a discontinuity in the user mode program counter execution sequence.

TRACE_TYPE_PREFETCH_READ_L1_NT 

Non-temporal load prefetch to L1 cache.

TRACE_TYPE_PREFETCH_READ_L2_NT 

Non-temporal load prefetch to L2 cache.

TRACE_TYPE_PREFETCH_READ_L3_NT 

Non-temporal load prefetch to L3 cache.

TRACE_TYPE_PREFETCH_INSTR_L1 

Instr prefetch to L1 cache.

TRACE_TYPE_PREFETCH_INSTR_L1_NT 

Non-temporal instr prefetch to L1 cache.

TRACE_TYPE_PREFETCH_INSTR_L2 

Instr prefetch to L2 cache.

TRACE_TYPE_PREFETCH_INSTR_L2_NT 

Non-temporal instr prefetch to L2 cache.

TRACE_TYPE_PREFETCH_INSTR_L3 

Instr prefetch to L3 cache.

TRACE_TYPE_PREFETCH_INSTR_L3_NT 

Non-temporal instr prefetch to L3 cache.

TRACE_TYPE_PREFETCH_WRITE_L1 

Store prefetch to L1 cache.

TRACE_TYPE_PREFETCH_WRITE_L1_NT 

Non-temporal store prefetch to L1 cache.

TRACE_TYPE_PREFETCH_WRITE_L2 

Store prefetch to L2 cache.

TRACE_TYPE_PREFETCH_WRITE_L2_NT 

Non-temporal store prefetch to L2 cache.

TRACE_TYPE_PREFETCH_WRITE_L3 

Store prefetch to L3 cache.

TRACE_TYPE_PREFETCH_WRITE_L3_NT 

Non-temporal store prefetch to L3 cache.

TRACE_TYPE_INSTR_TAKEN_JUMP 

A direct conditional jump instruction which was taken. This is only used in offline non-i-filtered traces.

TRACE_TYPE_INSTR_UNTAKEN_JUMP 

A direct conditional jump instruction which was not taken. This is only used in offline non-i-filtered traces.

TRACE_TYPE_INVALID 

An invalid record, meant for use as a sentinel value.

◆ trace_version_t

The version number of the trace format. This is presented to analysis tools as a marker of type TRACE_MARKER_TYPE_VERSION.

Enumerator
TRACE_ENTRY_VERSION_NO_KERNEL_PC 

A prior version where TRACE_MARKER_TYPE_KERNEL_EVENT provided the module offset (and nothing for restartable sequence aborts) rather than the absolute PC of the interruption point provided today.

TRACE_ENTRY_VERSION_KERNEL_PC 

TRACE_MARKER_TYPE_KERNEL_EVENT records provide the absolute PC of the interruption point.

TRACE_ENTRY_VERSION_ENCODINGS 

The trace supports embedded instruction encodings, but they are only present if OFFLINE_FILE_TYPE_ENCODINGS is set.

TRACE_ENTRY_VERSION_BRANCH_INFO 

The trace includes branch taken and target information up front. This means that conditional branches use either TRACE_TYPE_INSTR_TAKEN_JUMP or TRACE_TYPE_INSTR_UNTAKEN_JUMP and that the target of indirect branches is in a new field "indirect_branch_target" in memref_t. This only applies to offline traces whose instructions are not filtered; online traces, and i-filtered offline traces, even at this version, do not contain this information.

TRACE_ENTRY_VERSION_FREQUENT_TIMESTAMPS 

The trace contains additional timestamps to identify and distinguish application instruction execution, application syscall invocation, and trace i/o. The pre-syscall and post-syscall timestamps are as expected. Prior versions have the post-syscall timestamp actually containing the pre-syscall time.

TRACE_ENTRY_VERSION 

The latest version of the trace format.

Function Documentation

◆ basic_counts_tool_create()

analysis_tool_t* dynamorio::drmemtrace::basic_counts_tool_create ( unsigned int  verbose = 0)

Creates an analysis tool which counts the number of instructions, loads, stores, prefetch, threads, and markers in the trace.

◆ cache_miss_analyzer_create()

analysis_tool_t* dynamorio::drmemtrace::cache_miss_analyzer_create ( const cache_simulator_knobs_t knobs,
unsigned int  miss_count_threshold,
double  miss_frac_threshold,
double  confidence_threshold 
)

Creates an instance of a cache miss analyzer.

◆ cache_simulator_create() [1/2]

analysis_tool_t* dynamorio::drmemtrace::cache_simulator_create ( const cache_simulator_knobs_t knobs)

Creates an instance of a cache simulator with a 2-level hierarchy.

◆ cache_simulator_create() [2/2]

analysis_tool_t* dynamorio::drmemtrace::cache_simulator_create ( const std::string &  config_file)

Creates an instance of a cache simulator using a cache hierarchy defined in a configuration file.

◆ drmemtrace_buffer_handoff()

DR_EXPORT drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_buffer_handoff ( drmemtrace_handoff_func_t  handoff_func,
drmemtrace_exit_func_t  exit_func,
void *  exit_func_arg 
)

Registers a function to replace the default file write operation for offline tracing and requests that buffer ownership be transferred. The regular file open and close routines (or their replacements from drmemtrace_replace_file_ops()) will be called, but instead of writing to the files (or calling the write_file_func), the provided handoff_func will be called instead. The callee is responsible for writing out the buffer and for freeing it by calling dr_raw_mem_free(). The amount of legitimate data is in data_size and the total allocated size of the buffer is in alloc_size. Any space in between is available for use by the callee. The return value of handoff_cb indicates whether successful or not: failure will be treated as fatal and unrecoverable.

The module list data, written to the first file opened, is not subject to this ownership transfer and uses the write_file_func.

Because DR memory will be freed in dr_app_stop_and_cleanup(), an exit callback is provided for a control point to process and free the buffers. When dr_app_stop_and_cleanup() is used, exit_func will be called (and passed exit_func_arg) after the other application threads are already native.

Note
The caller is responsible for the transparency and isolation of using these functions, which will be called in the middle of arbitrary application code.

◆ drmemtrace_client_main()

DR_EXPORT void dynamorio::drmemtrace::drmemtrace_client_main ( client_id_t  id,
int  argc,
const char *  argv[] 
)

To support statically linking multiple clients on UNIX, dr_client_main() inside drmemtrace is a weak symbol which just calls the real initializer drmemtrace_client_main(). An enclosing application can override dr_client_main() and invoke drmemtrace_client_main() explicitly at a time of its choosing.

◆ drmemtrace_custom_module_data()

DR_EXPORT drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_custom_module_data ( void *(*)(module_data_t *module, int seg_idx)  load_cb,
int(*)(void *data, char *dst, size_t max_len)  print_cb,
void(*)(void *data)  free_cb 
)

Adds custom data stored with each module in the module list produced for offline trace post-processing. The load_cb is called for each segment of each new module (with seg_idx indicating the segment number, starting at 0), and its return value is the data that is stored. That data is later printed to a string with print_cb, which should return the number of characters printed or -1 on error. The data is freed with free_cb. Each is called separately for each segment of each module.

On the post-processing side, the user should create a custom post-processor by linking with raw2trace and calling raw2trace_t::handle_custom_data() to provide parsing and processing routines for the custom data.

◆ drmemtrace_filter_threads()

drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_filter_threads ( bool(*)(thread_id_t tid, void *user_data)  should_trace_thread_cb,
void *  user_value 
)

Activates thread filtering. The should_trace_thread_cb will be called once for each new thread, with user_value passed in for user_data. If it returns false, that thread will not be traced at all; if it returns true, that thread will be traced normally. Returns whether the filter was successfully installed.

Note
This feature is currently only supported for x86. This routine should be called during initialization, before any instrumentation is added. To filter out the calling thread (the initial application thread) this should be called prior to DR initialization (via the start/stop API). Only a single call to this routine is supported.

◆ drmemtrace_get_encoding_path()

DR_EXPORT drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_get_encoding_path ( OUT const char **  path)

Retrieves the full path to the file in -offline mode where non-module instruction encoding data is written. The basename of the file is DRMEMTRACE_ENCODING_FILENAME. It contains binary data read by the raw2trace tool.

◆ drmemtrace_get_funclist_path()

DR_EXPORT drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_get_funclist_path ( OUT const char **  path)

Retrieves the full path to the file in -offline mode where function tracing information is written. The basename of the file is DRMEMTRACE_FUNCTION_LIST_FILENAME. Each "library!symbol" function that was traced occupies one line of the file, with comma-separated values preceding it: its numeric identifier used in trace entries; the number of its arguments that are recorded; its address in hexadecimal format; and optional flags such as "noret". For example:

4,1,0x7fff2348ac,libc!malloc 5,1,0x7fff267d52,noret,libc!free

There can be multiple symbols mapping to the same address and thus to the sam identifier; each will have its own line in the file.

◆ drmemtrace_get_modlist_path()

DR_EXPORT drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_get_modlist_path ( OUT const char **  path)

Retrieves the full path to the file in -offline mode where module data is written. The basename of the file is DRMEMTRACE_MODULE_LIST_FILENAME. Its creation can be customized using drmemtrace_custom_module_data() with corresponding post-processing with raw2trace_t::handle_custom_data().

◆ drmemtrace_get_output_path()

DR_EXPORT drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_get_output_path ( OUT const char **  path)

Retrieves the full path to the output directory in -offline mode where data is being written.

◆ drmemtrace_get_timestamp_from_offline_trace()

DR_EXPORT drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_get_timestamp_from_offline_trace ( const void *  trace,
size_t  trace_size,
OUT uint64 *  timestamp 
)

Fetch the timestamp from a raw trace bundle. The API checks if the bundle is a thread start or not, and fetches the timestamp from the appropriate location. Returns DRMEMTRACE_ERROR_INVALID_PARAMETER if the pointer parameters are null or if the trace is too short.

◆ drmemtrace_replace_file_ops()

DR_EXPORT drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_replace_file_ops ( drmemtrace_open_file_func_t  open_file_func,
drmemtrace_read_file_func_t  read_file_func,
drmemtrace_write_file_func_t  write_file_func,
drmemtrace_close_file_func_t  close_file_func,
drmemtrace_create_dir_func_t  create_dir_func 
)

Registers functions to replace the default file operations for offline tracing. If tracing windows are used and separate files per window are not meant to be supported by "open_file_func", it is up to the user to set -no_split_windows.

Note
The caller is responsible for the transparency and isolation of using those functions, which will be called in the middle of arbitrary application code.
For additional file open parameters with the thread and window identifiers, use drmemtrace_replace_file_ops_ex().

◆ drmemtrace_replace_file_ops_ex()

DR_EXPORT drmemtrace_status_t dynamorio::drmemtrace::drmemtrace_replace_file_ops_ex ( drmemtrace_replace_file_ops_t ops)

Combines drmemtrace_replace_file_ops() and drmemtrace_buffer_handoff() and provides a file open function which takes two extra parameters.

◆ func_view_tool_create()

analysis_tool_t* dynamorio::drmemtrace::func_view_tool_create ( const std::string &  funclist_file_path,
bool  full_trace,
unsigned int  verbose = 0 
)

Creates an analysis tool which prints out statistics on function calls and returns for functions enabled by the -record_heap or -record_function options when tracing. If 'full_trace' is true, every call is printed with its arguments and return value. Otherwise, only a summary is shown.

◆ histogram_tool_create()

analysis_tool_t* dynamorio::drmemtrace::histogram_tool_create ( unsigned int  line_size = 64,
unsigned int  report_top = 10,
unsigned int  verbose = 0 
)

Creates an analysis tool which computes the most-referenced cache lines. The options are currently documented in Simulator Parameters.

◆ opcode_mix_tool_create()

analysis_tool_t* dynamorio::drmemtrace::opcode_mix_tool_create ( const std::string &  module_file_path,
unsigned int  verbose = 0,
const std::string &  alt_module_dir = "" 
)

Creates an analysis tool which counts the number of instances of each opcode in the trace. This tool needs access to the modules.log and original libraries and binaries from the traced execution. It does not support online analysis. An alternate search path for the libraries in the modules.log can be specified in "alt_module_path".

◆ reuse_distance_tool_create()

analysis_tool_t* dynamorio::drmemtrace::reuse_distance_tool_create ( const reuse_distance_knobs_t knobs)

Creates an analysis tool which computes reuse distance.

◆ reuse_time_tool_create()

analysis_tool_t* dynamorio::drmemtrace::reuse_time_tool_create ( unsigned int  line_size = 64,
unsigned int  verbose = 0 
)

Creates an analysis tool which computes reuse time (i.e., reuse distance without regard to uniqueness). The options are currently documented in Simulator Parameters.

◆ syscall_mix_tool_create()

analysis_tool_t* dynamorio::drmemtrace::syscall_mix_tool_create ( unsigned int  verbose = 0)

Creates an analysis tool which counts the number of instances of each system call in the trace.

◆ tlb_simulator_create()

analysis_tool_t* dynamorio::drmemtrace::tlb_simulator_create ( const tlb_simulator_knobs_t knobs)

Creates an instance of a TLB simulator.

◆ type_has_address()

static bool dynamorio::drmemtrace::type_has_address ( const trace_type_t  type)
inlinestatic

Returns whether the type contains an address. This includes both instruction fetches and instruction operands.

◆ type_is_data()

static bool dynamorio::drmemtrace::type_is_data ( const trace_type_t  type)
inlinestatic

Returns whether the type represents an address operand of an instruction. This is a subset of type_has_address() as type_has_address() includes instruction fetches.

◆ type_is_instr()

static bool dynamorio::drmemtrace::type_is_instr ( const trace_type_t  type)
inlinestatic

Returns whether the type represents an instruction fetch. Deliberately excludes TRACE_TYPE_INSTR_NO_FETCH and TRACE_TYPE_INSTR_BUNDLE.

◆ type_is_instr_branch()

static bool dynamorio::drmemtrace::type_is_instr_branch ( const trace_type_t  type)
inlinestatic

Returns whether the type represents the fetch of a branch instruction.

◆ type_is_instr_conditional_branch()

static bool dynamorio::drmemtrace::type_is_instr_conditional_branch ( const trace_type_t  type)
inlinestatic

Returns whether the type represents the fetch of a conditional branch instruction.

◆ type_is_instr_direct_branch()

static bool dynamorio::drmemtrace::type_is_instr_direct_branch ( const trace_type_t  type)
inlinestatic

Returns whether the type represents the fetch of a direct branch instruction.

◆ type_is_prefetch()

static bool dynamorio::drmemtrace::type_is_prefetch ( const trace_type_t  type)
inlinestatic

Returns whether the type represents a prefetch request.

◆ type_is_read()

static bool dynamorio::drmemtrace::type_is_read ( const trace_type_t  type)
inlinestatic

Returns whether the type represents a memory read access.

◆ view_tool_create()

analysis_tool_t* dynamorio::drmemtrace::view_tool_create ( const std::string &  module_file_path,
uint64_t  skip_refs,
uint64_t  sim_refs,
const std::string &  syntax,
unsigned int  verbose = 0,
const std::string &  alt_module_dir = "" 
)

Creates an analysis tool which prints out the disassembled instructions from the binary in the order they are present in the trace. This tool needs access to the modules.log and original libraries and binaries from the traced execution. It does not support online analysis.