DynamoRIO API
Code Coverage Library

Data Structures

struct  _drcovlib_options_t
 

Typedefs

typedef struct _drcovlib_options_t drcovlib_options_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)
 
DR_EXPORT drcovlib_status_t drmodtrack_exit (void)
 
DR_EXPORT drcovlib_status_t drmodtrack_offline_read (file_t file, const char **map, OUT void **handle, OUT uint *num_mods)
 
DR_EXPORT drcovlib_status_t drmodtrack_offline_lookup (void *handle, uint index, OUT app_pc *mod_base, OUT size_t *mod_size, OUT const char **mod_path)
 
DR_EXPORT drcovlib_status_t drmodtrack_offline_exit (void *handle)
 

Detailed Description

Typedef Documentation

Specifies the options when initializing drcovlib.

Enumeration Type Documentation

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().

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

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.
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.
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]opsSpecifies 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.
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]drcontextIf DRCOVLIB_THREAD_PRIVATE is in effect, specifies which thread's log file name should be returned. Otherwise this must be NULL.
[out]pathThe full path to the requested log file.
Returns
whether successful or an error code on failure.
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().

DR_EXPORT drcovlib_status_t drmodtrack_dump_buf ( char *  buf,
size_t  size 
)

Writes the complete module information string to buf. Returns DRCOVLIB_SUCCESS on success. If the buffer is too small, returns DRCOVLIB_ERROR_BUF_TOO_SMALL.

DR_EXPORT drcovlib_status_t drmodtrack_exit ( void  )

Cleans up the module tracking state.

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

DR_EXPORT drcovlib_status_t drmodtrack_offline_exit ( void *  handle)

Cleans up the offline module state for handle.

DR_EXPORT drcovlib_status_t drmodtrack_offline_lookup ( void *  handle,
uint  index,
OUT app_pc *  mod_base,
OUT size_t *  mod_size,
OUT const char **  mod_path 
)

Queries the information read by drmodtrack_offline_read() into handle Returns the base address in mod_base and the full path in mod_path for the module corresponding to the unique index identifier index.

DR_EXPORT drcovlib_status_t drmodtrack_offline_read ( file_t  file,
const char **  map,
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, returning in *map the end of the module list region. 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.