drmemtrace.h File Reference

Header for customizing the DrMemtrace tracer. More...

Macros
#define	DRMGR_PRIORITY_NAME_MEMTRACE   "memtrace"
#define	DRMEMTRACE_MODULE_LIST_FILENAME   "modules.log"

Typedefs
typedef file_t(*	drmemtrace_open_file_func_t) (const char *fname, uint mode_flag)
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_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_custom_module_data (void *(*load_cb)(module_data_t *module), 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

DRMEMTRACE_MODULE_LIST_FILENAME

#define DRMEMTRACE_MODULE_LIST_FILENAME   "modules.log"

The name of the file in -offline mode where module data is written. Its creation can be customized using drmemtrace_custom_module_data() and then modified before passing to raw2trace via drmodtrack_add_custom_data() and drmodtrack_offline_write().

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_func_t

typedef file_t(* drmemtrace_open_file_func_t) (const char *fname, uint mode_flag)

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.

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

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)	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 new module, 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.

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

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.