drsymcache.h File Reference

Header for Dr. SymCache: Symbol Lookup Cache Extension. More...

#include "drmemory_framework.h"
#include "drmgr.h"

Macros
#define	DRMGR_PRIORITY_NAME_DRSYMCACHE   "drsymcache"
#define	DRMGR_PRIORITY_NAME_DRSYMCACHE_SAVE   "drsymcache_save"

Enumerations
enum	{   DRMGR_PRIORITY_PRESYS_DRSYS = -100,   DRMGR_PRIORITY_POSTSYS_DRSYS = -100,   DRMGR_PRIORITY_POSTSYS_DRSYS_LAST = 10000,   DRMGR_PRIORITY_MODLOAD_DRSYS = -100,   DRMGR_PRIORITY_EXCPT_UMBRA = -100,   DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_READ = -150,   DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE = 150,   DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE = -150 }

Functions
DR_EXPORT drmf_status_t	drsymcache_init (client_id_t client_id, const char *drsymcache_dir, size_t modsize_cache_threshold)
DR_EXPORT drmf_status_t	drsymcache_exit (void)
DR_EXPORT drmf_status_t	drsymcache_is_initialized (OUT bool *initialized)
DR_EXPORT drmf_status_t	drsymcache_module_is_cached (const module_data_t *mod, OUT bool *cached)
DR_EXPORT drmf_status_t	drsymcache_module_has_debug_info (const module_data_t *mod, OUT bool *has_debug)
DR_EXPORT drmf_status_t	drsymcache_module_save_symcache (const module_data_t *mod)
DR_EXPORT drmf_status_t	drsymcache_add (const module_data_t *mod, const char *symbol, size_t offs)
DR_EXPORT drmf_status_t	drsymcache_lookup (const module_data_t *mod, const char *symbol, OUT size_t **offs_array, OUT uint *num_entries, OUT size_t *offs_single)
DR_EXPORT drmf_status_t	drsymcache_free_lookup (size_t *offs, uint num)

Detailed Description

Header for Dr. SymCache: Symbol Lookup Cache Extension.

Macro Definition Documentation

DRMGR_PRIORITY_NAME_DRSYMCACHE

#define DRMGR_PRIORITY_NAME_DRSYMCACHE   "drsymcache"

Name of drsymcache events DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_READ and DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE.

DRMGR_PRIORITY_NAME_DRSYMCACHE_SAVE

#define DRMGR_PRIORITY_NAME_DRSYMCACHE_SAVE   "drsymcache_save"

Name of drsymcache events DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE.

Enumeration Type Documentation

anonymous enum

anonymous enum

Priority of drsymcache events.

Enumerator
DRMGR_PRIORITY_PRESYS_DRSYS	Priority of the drsyscall pre-syscall and post-syscall events that are meant to take place before the corresponding events of a regular user of drsyscall. Dynamic iteration is not allowed until these events have taken place. Users of drsyscall should arrange their pre-syscall and post-syscall event callbacks to be called after the drsyscall event, unless they want to modify the pre-syscall arguments before they're stored or they want to modify the application's context, in which case their event should go beforehand.
DRMGR_PRIORITY_POSTSYS_DRSYS	See the comment for DRMGR_PRIORITY_PRESYS_DRSYS.
DRMGR_PRIORITY_POSTSYS_DRSYS_LAST	Priority of the drsyscall last-chance post-syscall event. This event must take place after any dynamic iteration of system call arguments, which means it must be after the post-syscall event in all users of drsyscall.
DRMGR_PRIORITY_MODLOAD_DRSYS	Priority of the drsyscall module load event. This event must take place before any user of drsyscall in order to populate the tables used by drsys_name_to_syscall().
DRMGR_PRIORITY_EXCPT_UMBRA	Priority of the Umbra signal/exception handling event. This event must take place before any user of drsyscall in order to allocate shadow memory if necessary.
DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_READ	Priority of the drsymcache module load event action that checks for a symbol cache file and reads it in. This event must occur before any drsymcache API usage in module load events of users of drsymcache.
DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE	Priority of the drsymcache module load event action that saves the current symbol cache from memory to disk.
DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE	Priority of the drsymcache module unload event action that saves the current symbol cache from memory to disk and then frees the in-memory cache data structures. This event must occur after any drsymcache API usage in module unload events of users of drsymcache.

Function Documentation

drsymcache_add()

DR_EXPORT drmf_status_t drsymcache_add	(	const module_data_t *	mod,
		const char *	symbol,
		size_t	offs
	)

Adds a new entry for the symbol name symbol to the symbol cache for mod. If an entry already exists and is 0, replaces it; else adds a new value equal to offset for that symbol.

Parameters

[in]	mod	The module whose symcache should be updated.
[in]	symbol	The name of the symbol being added.
[in]	offs	The offset from the module base to add.

Returns

success code. If there is no cache for this module, returns DRMF_ERROR_NOT_FOUND.

drsymcache_exit()

DR_EXPORT drmf_status_t drsymcache_exit

(

void

)

Cleans up drsymcache.

Returns

success code.

drsymcache_free_lookup()

DR_EXPORT drmf_status_t drsymcache_free_lookup	(	size_t *	offs,
		uint	num
	)

Frees the array of offsets allocated by drsymcache_lookup().

Returns

success code.

drsymcache_init()

DR_EXPORT drmf_status_t drsymcache_init	(	client_id_t	client_id,
		const char *	drsymcache_dir,
		size_t	modsize_cache_threshold
	)

Initializes drsymcache. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to drsymcache_exit(), and only the first call's parameters are honored: subsequent calls return DRMF_WARNING_ALREADY_INITIALIZED and ignore the parameters passed in favor of those passed to the original call. Libraries that use drsymcache should typically require that their callers initialize drsymcache, as the location of the cache files is usually a top-level tool property.

Parameters

[in]	client_id	The id of the client using drsymcache, as passed to dr_init().
[in]	drsymcache_dir	The directory in which to store symbol cache files. If this directory does not exist, drsymcache will attempt to create it, and return DRMF_ERROR_INVALID_PARAMETER on failure.
[in]	modsize_cache_threshold	The minimum module size for which symbols should be cached. Normally there's little downside to caching, so passing 0 here is reasonable.

Returns

success code.

drsymcache_is_initialized()

DR_EXPORT drmf_status_t drsymcache_is_initialized

(

OUT bool *

initialized

)

Queries whether drsymcache has been initialized.

Parameters

[out]

initialized

Whether drsymcache is initialized.

Returns

success code.

drsymcache_lookup()

DR_EXPORT drmf_status_t drsymcache_lookup	(	const module_data_t *	mod,
		const char *	symbol,
		OUT size_t **	offs_array,
		OUT uint *	num_entries,
		OUT size_t *	offs_single
	)

Queries the symbol cache for mod. If symbol is not present in the cache, returns DRMF_ERROR_NOT_FOUND. If symbol is present, allocates and returns an array of all entries found. The size of the array is returned in num. The array must be freed by calling drsymcache_free_lookup().

Parameters

[in]	mod	The module being queried.
[in]	symbol	The name of the symbol being queried.
[out]	offs_array	Returns a pointer to an array of offsets from the module base containing the locations of each instance of the symbol. If the symbol is not present in the module, there will only be one entry with offset of 0.
[out]	offs_single	Since many symbols have only one entry, to avoid the overhead of allocating memory the caller must pass in a single slot that offs_array will point to if num_entries is just 1.
[out]	num_entries	The total count of instances of symbol within the module.

Returns

success code.

drsymcache_module_has_debug_info()

DR_EXPORT drmf_status_t drsymcache_module_has_debug_info	(	const module_data_t *	mod,
		OUT bool *	has_debug
	)

Queries whether mod has debug information (any symbol information, even if there is no line number information: i.e., whether the symbol is stripped).

Parameters

[in]	mod	The module being queried.
[out]	has_debug	Whether the module has debug information.

Returns

success code.

drsymcache_module_is_cached()

DR_EXPORT drmf_status_t drsymcache_module_is_cached	(	const module_data_t *	mod,
		OUT bool *	cached
	)

Queries whether mod has a corresponding symbol cache.

Parameters

[in]	mod	The module being queried.
[out]	cached	Whether the module has a symbol cache.

Returns

success code.

drsymcache_module_save_symcache()

DR_EXPORT drmf_status_t drsymcache_module_save_symcache

(

const module_data_t *

mod

)

Proactively writes the symbol cache file corresponding to mod to disk. Symbol cache files are automatically saved at three points, without the user needing to invoke this routine: after a module is loaded (with a late priority DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE), when a module is unloaded (with priority DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE), and when the final drsymcache_exit() is called.

Parameters

[in]

mod

The module to save.

Returns

success code.