Dynamic Instrumentation Tool Platform
Data Structures | Macros | Typedefs | Enumerations | Functions
drmemtrace.h File Reference

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
}
 

Functions

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)
 

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]fileThe 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]dirThe 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]argThe 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]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(* 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(* 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(* 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(* 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.

Enumeration Type Documentation

◆ drmemtrace_status_t

enum 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.

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.