DynamoRIO
|
Header for customizing the DrMemtrace tracer. More...
Data Structures | |
struct | drmemtrace_replace_file_ops_t |
Macros | |
#define | DRMGR_PRIORITY_NAME_MEMTRACE "memtrace" |
Typedefs | |
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) |
Enumerations | |
enum | drmemtrace_status_t { DRMEMTRACE_SUCCESS, DRMEMTRACE_ERROR, DRMEMTRACE_ERROR_INVALID_PARAMETER, DRMEMTRACE_ERROR_NOT_IMPLEMENTED } |
Detailed Description
Header for customizing the DrMemtrace tracer.
Macro Definition Documentation
◆ DRMGR_PRIORITY_NAME_MEMTRACE
#define DRMGR_PRIORITY_NAME_MEMTRACE "memtrace" |
Name of drmgr instrumentation pass priorities for app2app, analysis, insert, and instru2instru.
Typedef Documentation
◆ drmemtrace_close_file_func_t
typedef void(* 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(* 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(* 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_arg
passed to drmemtrace_buffer_handoff().
◆ drmemtrace_handoff_func_t
typedef bool(* 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_func
or 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(* 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(* 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(* 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(* 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.
Enumeration Type Documentation
◆ drmemtrace_status_t
enum drmemtrace_status_t |
Function Documentation
◆ drmemtrace_buffer_handoff()
DR_EXPORT drmemtrace_status_t 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 transfered. 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 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 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 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 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 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 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 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 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 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 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.