Code Coverage Library

Data Structures
struct	_drcovlib_options_t
struct	_drmodtrack_info_t

Typedefs
typedef struct _drcovlib_options_t	drcovlib_options_t
typedef struct _drmodtrack_info_t	drmodtrack_info_t

Enumerations
enum	drcovlib_status_t {   DRCOVLIB_SUCCESS,   DRCOVLIB_ERROR,   DRCOVLIB_ERROR_INVALID_PARAMETER,   DRCOVLIB_ERROR_INVALID_SETUP,   DRCOVLIB_ERROR_FEATURE_NOT_AVAILABLE,   DRCOVLIB_ERROR_NOT_FOUND,   DRCOVLIB_ERROR_BUF_TOO_SMALL }
enum	drcovlib_flags_t {   DRCOVLIB_DUMP_AS_TEXT = 0x0001,   DRCOVLIB_THREAD_PRIVATE = 0x0002 }

Functions
DR_EXPORT drcovlib_status_t	drcovlib_init (drcovlib_options_t *ops)
DR_EXPORT drcovlib_status_t	drcovlib_exit (void)
DR_EXPORT drcovlib_status_t	drcovlib_logfile (void *drcontext, OUT const char **path)
DR_EXPORT drcovlib_status_t	drcovlib_dump (void *drcontext)
DR_EXPORT drcovlib_status_t	drmodtrack_init (void)
DR_EXPORT drcovlib_status_t	drmodtrack_lookup (void *drcontext, app_pc pc, OUT uint *mod_index, OUT app_pc *mod_base)
DR_EXPORT drcovlib_status_t	drmodtrack_dump (file_t file)
DR_EXPORT drcovlib_status_t	drmodtrack_dump_buf (char *buf, size_t size, OUT size_t *wrote)
DR_EXPORT drcovlib_status_t	drmodtrack_exit (void)
DR_EXPORT drcovlib_status_t	drmodtrack_offline_read (file_t file, const char *map, OUT const char **next_line, OUT void **handle, OUT uint *num_mods)
DR_EXPORT drcovlib_status_t	drmodtrack_offline_lookup (void *handle, uint index, OUT drmodtrack_info_t *info)
DR_EXPORT drcovlib_status_t	drmodtrack_offline_write (void *handle, char *buf, size_t buf_size, OUT size_t *wrote)
DR_EXPORT drcovlib_status_t	drmodtrack_offline_exit (void *handle)
DR_EXPORT drcovlib_status_t	drmodtrack_add_custom_data (void *(*load_cb)(module_data_t *module), int(*print_cb)(void *data, char *dst, size_t max_len), const char *(*parse_cb)(const char *src, OUT void **data), void(*free_cb)(void *data))

Detailed Description

Typedef Documentation

drcovlib_options_t

typedef struct _drcovlib_options_t drcovlib_options_t

Specifies the options when initializing drcovlib.

drmodtrack_info_t

typedef struct _drmodtrack_info_t drmodtrack_info_t

Information for one module as recorded during execution.

Enumeration Type Documentation

drcovlib_flags_t

enum drcovlib_flags_t

Bitmask flags for use in drcovlib_options_t.flags.

Enumerator
DRCOVLIB_DUMP_AS_TEXT	Requests to dump the log file in text format. By default the log file is in binary format. When in text format, the log file is not readable by the post-processing tool Post-Processing.
DRCOVLIB_THREAD_PRIVATE	By default, coverage information is dumped in a single process-wide log file. If DynamoRIO is run with thread-private code caches (i.e., dr_using_all_private_caches() returns true) and this flag is enabled, then per-thread coverage information will be stored and dumped in drcovlib's own thread exit events rather than in drcovlib_exit().

drcovlib_status_t

enum drcovlib_status_t

Success code for each drcovlib operation

Enumerator
DRCOVLIB_SUCCESS	Operation succeeded.
DRCOVLIB_ERROR	Operation failed.
DRCOVLIB_ERROR_INVALID_PARAMETER	Operation failed: invalid parameter
DRCOVLIB_ERROR_INVALID_SETUP	Operation failed: invalid DynamoRIO setup
DRCOVLIB_ERROR_FEATURE_NOT_AVAILABLE	Operation failed: not available
DRCOVLIB_ERROR_NOT_FOUND	Operation failed: query not found.
DRCOVLIB_ERROR_BUF_TOO_SMALL	Operation failed: buffer too small.

Function Documentation

drcovlib_dump()

DR_EXPORT drcovlib_status_t drcovlib_dump

(

void *

drcontext

)

Requests that coverage information be dumped to the log file for this process (or for the thread specified by drcontext, if DRCOVLIB_THREAD_PRIVATE is in effect use). Normally this happens during drcovlib_exit(), unless some unusual termination prevents it. If this routine is called and drcovlib_exit() is also later called (or for DRCOVLIB_THREAD_PRIVATE, drcovlib's own thread exit events are invoked by DynamoRIO), duplicate information will be dumped to the log files. Thus, this routine should only be called when the regular dump will not occur.

Returns

whether successful or an error code on failure.

drcovlib_exit()

DR_EXPORT drcovlib_status_t drcovlib_exit

(

void

)

Dumps the coverage information for this process into its log file and cleans up all resources allocated by the drcovlib extension. If DRCOVLIB_THREAD_PRIVATE is in effect, coverage information is instead dumped in drcovlib's own thread exit events.

Returns

whether successful or an error code on failure.

drcovlib_init()

DR_EXPORT drcovlib_status_t drcovlib_init

(

drcovlib_options_t *

ops

)

Initializes the drcovlib extension. Must be called prior to any of the other routines. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to drcovlib_exit().

Once this routine is called, drcovlib's operation goes into effect and it starts collecting coverage information.

Parameters

[in]

ops

Specifies the optional parameters that control how drcovlib operates. Only the first caller's options are honored.

Returns

whether successful or an error code on failure.

drcovlib_logfile()

DR_EXPORT drcovlib_status_t drcovlib_logfile	(	void *	drcontext,
		OUT const char **	path
	)

Returns the name of the log file for this process (or for the thread specified by drcontext, if DRCOVLIB_THREAD_PRIVATE is in effect).

Parameters

[in]	drcontext	If DRCOVLIB_THREAD_PRIVATE is in effect, specifies which thread's log file name should be returned. Otherwise this must be NULL.
[out]	path	The full path to the requested log file.

Returns

whether successful or an error code on failure.

drmodtrack_add_custom_data()

DR_EXPORT drcovlib_status_t drmodtrack_add_custom_data	(	void *(*)(module_data_t *module)	load_cb,
		int(*)(void *data, char *dst, size_t max_len)	print_cb,
		const char *(*)(const char *src, OUT void **data)	parse_cb,
		void(*)(void *data)	free_cb
	)

Adds custom data stored with each module, serialized to a buffer or file, and read back in. The load_cb, print_cb, and free_cb are used during online operation, while parse_cb and free_cb are used for offline post-processing. The load_cb is called for each new module, and its return value is the data that is stored online. That data is 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. The printed data is read back in with parse_cb, which returns the point in the input string past the custom data, and writes the parsed data to its output parameter, which can subsequently be retrieved from drmodtrack_offline_lookup()'s custom output parameter.

If a module contains non-contiguous segments, load_cb is called only once, and the resulting custom field is shared among all separate entries returned by drmodtrack_offline_lookup().

Only one value for each callback is supported. Calling this routine again with a different value will replace the existing callbacks.

drmodtrack_dump()

DR_EXPORT drcovlib_status_t drmodtrack_dump

(

file_t

file

)

Writes the complete module information to file. The information can be read back in using drmodtrack_offline_read().

drmodtrack_dump_buf()

DR_EXPORT drcovlib_status_t drmodtrack_dump_buf	(	char *	buf,
		size_t	size,
		OUT size_t *	wrote
	)

Writes the complete module information to buf as a null-terminated string. Returns DRCOVLIB_SUCCESS on success and stores the number of bytes written to buf (including the terminating null) in wrote if wrote is not NULL. If the buffer is too small, returns DRCOVLIB_ERROR_BUF_TOO_SMALL.

drmodtrack_exit()

DR_EXPORT drcovlib_status_t drmodtrack_exit

(

void

)

Cleans up the module tracking state.

drmodtrack_init()

DR_EXPORT drcovlib_status_t drmodtrack_init

(

void

)

Initializes drcovlib's module tracking feature. Must be called prior to any of the other online routines. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to drmodtrack_exit().

Returns

whether successful or an error code on failure.

drmodtrack_lookup()

DR_EXPORT drcovlib_status_t drmodtrack_lookup	(	void *	drcontext,
		app_pc	pc,
		OUT uint *	mod_index,
		OUT app_pc *	mod_base
	)

Returns the base address in mod_base and the unique index identifier in mod_index for the module that contains pc. If there is no such module, returns DRCOVLIB_ERROR_NOT_FOUND. For modules that containing multiple non-contiguous mapped segments, each segment has its own unique identifier, and this routine returns the appropriate identifier, but mod_base contains the lowest address of any segment in the module, not the start address of the segment that contains pc.

drmodtrack_offline_exit()

DR_EXPORT drcovlib_status_t drmodtrack_offline_exit

(

void *

handle

)

Cleans up the offline module state for handle.

drmodtrack_offline_lookup()

DR_EXPORT drcovlib_status_t drmodtrack_offline_lookup	(	void *	handle,
		uint	index,
		OUT drmodtrack_info_t *	info
	)

Queries the information that was read earlier by drmodtrack_offline_read() into handle, returning it in info. The caller must initialize the size field of info before calling. The info.path field can be modified, with the modified version later written out via drmodtrack_offline_write(). The path's containing buffer size is limited to MAXIMUM_PATH.

drmodtrack_offline_read()

DR_EXPORT drcovlib_status_t drmodtrack_offline_read	(	file_t	file,
		const char *	map,
		OUT const char **	next_line,
		OUT void **	handle,
		OUT uint *	num_mods
	)

Usable from standalone mode (hence the "offline" name). Reads a file written by drmodtrack_dump(). If file is not INVALID_FILE, reads from file; otherwise, assumes the target file has been mapped into memory at map and reads from there. If next_line is not NULL, this routine reads one character past the final newline of the final module in the list, and returns in *next_line a pointer to that character (this is intended for users who are embedding a module list inside a file with further data following the list in the file). If next_line is NULL, this routine stops reading at the final newline: thus, map need not be NULL-terminated. Although map uses a char type, it cannot be assumed to be a regular string: binary data containing zeroes may be embedded inside it.

Returns an identifier in handle to use with other offline routines, along with the number of modules read in num_mods. Information on each module can be obtained by calling drmodtrack_offline_lookup() and passing integers from 0 to the number of modules minus one as the index.

drmodtrack_offline_write()

DR_EXPORT drcovlib_status_t drmodtrack_offline_write	(	void *	handle,
		char *	buf,
		size_t	buf_size,
		OUT size_t *	wrote
	)

Writes the module information that was read by drmodtrack_offline_read(), and potentially modified by drmodtrack_offline_lookup(), to buf, whose maximum size is specified in size. Returns DRCOVLIB_SUCCESS on success and stores the number of bytes written to buf (including the terminating null) in wrote if wrote is not NULL. If the buffer is too small, returns DRCOVLIB_ERROR_BUF_TOO_SMALL (and does not set wrote).