|
DynamoRIO
|
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 |
| class | flexible_queue_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 |
| class | replay_file_checker_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 |
Functions | |
| analysis_tool_t * | basic_counts_tool_create (unsigned int verbose=0) |
| analysis_tool_t * | cache_simulator_create (const cache_simulator_knobs_t &knobs) |
| analysis_tool_t * | cache_simulator_create (const std::string &config_file) |
| analysis_tool_t * | cache_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 (DR_PARAM_OUT const char **path) |
| DR_EXPORT drmemtrace_status_t | drmemtrace_get_modlist_path (DR_PARAM_OUT const char **path) |
| DR_EXPORT drmemtrace_status_t | drmemtrace_get_funclist_path (DR_PARAM_OUT const char **path) |
| DR_EXPORT drmemtrace_status_t | drmemtrace_get_encoding_path (DR_PARAM_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, DR_PARAM_OUT uint64 *timestamp) |
| analysis_tool_t * | func_view_tool_create (const std::string &funclist_file_path, bool full_trace, unsigned int verbose=0) |
| analysis_tool_t * | histogram_tool_create (unsigned int line_size=64, unsigned int report_top=10, unsigned int verbose=0) |
| analysis_tool_t * | opcode_mix_tool_create (const std::string &module_file_path, unsigned int verbose=0, const std::string &alt_module_dir="") |
| analysis_tool_t * | reuse_distance_tool_create (const reuse_distance_knobs_t &knobs) |
| analysis_tool_t * | reuse_time_tool_create (unsigned int line_size=64, unsigned int verbose=0) |
| analysis_tool_t * | schedule_stats_tool_create (uint64_t print_every, unsigned int verbose=0) |
| analysis_tool_t * | syscall_mix_tool_create (unsigned int verbose=0) |
| analysis_tool_t * | tlb_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_t * | 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="") |
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] file The 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] dir The 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] arg The exit_func_argpassed 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] file The file identifier returned by open_file_funcor or drmemtrace_replace_file_ops() was not called then from dr_open_file() for the per-thread trace file.[in] data The start address of the buffer. [in] data_size The size of valid trace data in the buffer. [in] alloc_size The 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] fname The filename to open. [in] mode_flags The DR_FILE_* flags for file open. [in] thread_id The 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_id The 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] fname The filename to open. [in] mode_flags The 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] file The file to be read from. [in] buf The buffer to be read to. [in] count The 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] file The file to be written. [in] data The data to be written. [in] count The number of bytes to be written.
- Returns
- the actual number of bytes written.
◆ memref_pid_t
| typedef int64_t dynamorio::drmemtrace::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
| typedef int64_t dynamorio::drmemtrace::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
| typedef struct _trace_entry_t dynamorio::drmemtrace::trace_entry_t |
Enumeration Type Documentation
◆ drmemtrace_status_t
◆ encoding_file_type_t
Bitfields used to describe the type of the encoding file. This is stored as the second uint64_t after the encoding file version.
| Enumerator | |
|---|---|
| ENCODING_FILE_TYPE_DEFAULT | Default encoding file type. |
| ENCODING_FILE_TYPE_SEPARATE_NON_MOD_INSTRS | This encoding file type tells the module_mapper_t that the non-module PC entries in the trace correspond to an individual instr. The modoffs field is interpreted as the cumulative encoding length of all instrs written to the encoding file before the recorded instr. Note that the encoding file itself is still written one mon-module block at a time because it is too inefficient to write one encoding_entry_t for just one non-module instr. If this file type is not set, then the PC entries' modoffs fields are interpreted as the non-mod block's idx. |
◆ func_trace_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.
◆ ir2trace_convert_status_t [2/2]
The type of ir2trace_t::convert() return value.
◆ 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 (both instructions and memory addresses) of syscalls are included. If only kernel instructions are included the file type is OFFLINE_FILE_TYPE_KERNEL_SYSCALL_INSTR_ONLY instead. The included kernel traces are provided by the -syscall_template_file to raw2trace (see OFFLINE_FILE_TYPE_KERNEL_SYSCALL_TRACE_TEMPLATES). |
| 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. |
| OFFLINE_FILE_TYPE_KERNEL_SYSCALL_TRACE_TEMPLATES | Indicates an offline trace that contains trace templates for some system calls. The individual traces are enclosed within a pair of TRACE_MARKER_TYPE_SYSCALL_TRACE_START and TRACE_MARKER_TYPE_SYSCALL_TRACE_END markers which also specify what system call the contained trace belongs to. This file can be used with -syscall_template_file to raw2trace to create an OFFLINE_FILE_TYPE_KERNEL_SYSCALLS trace. See the sample file written by the burst_syscall_inject.cpp test for more details on the expected format for the system call template file. TODO i#6495: Add support for reading a zipfile where each trace template is in a separate component. This will make it easier to manually append, update, or inspect the individual templates, and also allow streaming the component with the required template when needed instead of reading the complete file into memory ahead of time. Note that we may drop support for non-zipfile template files in the future. |
| OFFLINE_FILE_TYPE_KERNEL_SYSCALL_INSTR_ONLY | Kernel instruction traces of syscalls are included. When memory addresses are also included for kernel execution, the file type is OFFLINE_FILE_TYPE_KERNEL_SYSCALLS instead. On x86, the kernel trace is enabled by the -enable_kernel_tracing option that uses Intel® Processor Trace to collect an instruction trace for system call execution. |
| OFFLINE_FILE_TYPE_CORE_SHARDED | Each trace shard represents one core and contains interleaved software threads. |
◆ pt2ir_convert_status_t [1/2]
The type of pt2ir_t::convert() return value.
◆ pt2ir_convert_status_t [2/2]
The type of pt2ir_t::convert() return value.
◆ pt_cpu_vendor_t [1/2]
◆ pt_cpu_vendor_t [2/2]
◆ shard_type_t [1/2]
◆ shard_type_t [2/2]
◆ 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 or -record_syscall. 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) or -record_syscall. |
| 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. This is a pointer-sized value from the conventional return value register. For system calls, this may not be enough to determine whether the call succeeded. See TRACE_MARKER_TYPE_SYSCALL_FAILED. |
| 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.
|
| 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. The value of the marker is set to the syscall number. |
| TRACE_MARKER_TYPE_SYSCALL_TRACE_END | Indicates a point in the trace where a syscall's trace ends. The value of the marker is set to the syscall number. |
| TRACE_MARKER_TYPE_SYSCALL_FAILED | This marker is emitted for system calls whose parameters are traced with -record_syscall. It is emitted immediately after TRACE_MARKER_TYPE_FUNC_RETVAL if prior the system call (whose id is specified by the closest previous TRACE_MARKER_TYPE_FUNC_ID marker entry) failed. Whether it failed is 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 determination. The marker value is the "errno_value" field of dr_syscall_result_info_t. |
| TRACE_MARKER_TYPE_DIRECT_THREAD_SWITCH | This marker is emitted prior to a system call (but after the system call's TRACE_MARKER_TYPE_SYSCALL and TRACE_MARKER_TYPE_MAYBE_BLOCKING_SYSCALL markers) that causes an immediate switch to another thread on the same core (with the current thread entering an unscheduled state), bypassing the kernel scheduler's normal dynamic switch code based on run queues. The marker value holds the thread id of the target thread. This should generally always be after a TRACE_MARKER_TYPE_MAYBE_BLOCKING_SYSCALL marker as such a switch always has a chance of blocking if the target needs to be migrated. |
| TRACE_MARKER_TYPE_CORE_WAIT | This marker is used for core-sharded analyses to indicate that the current core is waiting on another core. This is primarily only useful for analyses studying the scheduling of threads onto cores. A new marker is emitted each time the tool analysis framework requests a new record from the scheduler and is given a wait status. There are no units of time here but each repetition is roughly the time where a regular record could have been read and passed along. |
| TRACE_MARKER_TYPE_CORE_IDLE | This marker is used for core-sharded analyses to indicate that the current core has no available inputs to run (all inputs are on other cores or are blocked waiting for kernel resources). A new marker is emitted each time the tool analysis framework requests a new record from the scheduler and is given an idle status. There are no units of time here but each repetition is roughly the time where a regular record could have been read and passed along. This idle marker indicates that a core actually had no work to do, as opposed to TRACE_MARKER_TYPE_CORE_WAIT which is an artifact of an imposed re-created schedule. |
| TRACE_MARKER_TYPE_CONTEXT_SWITCH_START | Indicates a point in the trace where context switch's kernel trace starts. The value of the marker is set to the switch type enum value from dynamorio::drmemtrace::scheduler_tmpl_t::switch_type_t. |
| TRACE_MARKER_TYPE_CONTEXT_SWITCH_END | Indicates a point in the trace where a context switch's kernel trace ends. The value of the marker is set to the switch type enum value from dynamorio::drmemtrace::scheduler_tmpl_t::switch_type_t. |
| TRACE_MARKER_TYPE_VECTOR_LENGTH | This marker's value is the current thread's vector length in bytes, for architectures with a dynamic vector length. It is currently only used on AArch64. On AArch64 the marker's value contains the SVE vector length. The marker is emitted with the thread header to establish the initial vector length for that thread. In the future it will also be emitted later in the trace if the app changes the vector length at runtime (TODO i#6625). In all cases the vector length value is specific to the current thread. The vector length affects how some SVE instructions are decoded so any tools which decode instructions should clear any cached data and set the vector length used by the decoder using dr_set_sve_vector_length(). |
◆ 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.
|
| 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 | ( | DR_PARAM_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 | ( | DR_PARAM_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 | ( | DR_PARAM_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 | ( | DR_PARAM_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, | ||
| DR_PARAM_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.
◆ schedule_stats_tool_create()
| analysis_tool_t* dynamorio::drmemtrace::schedule_stats_tool_create | ( | uint64_t | print_every, |
| unsigned int | verbose = 0 |
||
| ) |
Creates an analysis tool which counts the number and type of context switches in a core-sharded trace schedule. The tool fails if run in any mode besides core-sharded.
◆ 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()
|
inlinestatic |
Returns whether the type contains an address. This includes both instruction fetches and instruction operands.
◆ type_is_data()
|
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()
|
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()
|
inlinestatic |
Returns whether the type represents the fetch of a branch instruction.
◆ type_is_instr_conditional_branch()
|
inlinestatic |
Returns whether the type represents the fetch of a conditional branch instruction.
◆ type_is_instr_direct_branch()
|
inlinestatic |
Returns whether the type represents the fetch of a direct branch instruction.
◆ type_is_prefetch()
|
inlinestatic |
Returns whether the type represents a prefetch request.
◆ type_is_read()
|
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.
DynamoRIO version 10.90.19838 --- Fri Apr 26 2024 03:14:53