dr_annotation.h File Reference

Annotation handler registration routines. More...

#include "dr_tools.h"

Data Structures
struct	_dr_vg_client_request_t

Typedefs
typedef enum _dr_valgrind_request_id_t	dr_valgrind_request_id_t
typedef struct _dr_vg_client_request_t	dr_vg_client_request_t
typedef enum _dr_annotation_calling_convention_t	dr_annotation_calling_convention_t

Enumerations
enum	_dr_valgrind_request_id_t {   DR_VG_ID__RUNNING_ON_VALGRIND,   DR_VG_ID__DO_LEAK_CHECK,   DR_VG_ID__MAKE_MEM_DEFINED_IF_ADDRESSABLE,   DR_VG_ID__DISCARD_TRANSLATIONS,   DR_VG_ID__LAST }
enum	{ DR_VG_NUM_ARGS = 5 }
enum	_dr_annotation_calling_convention_t {   DR_ANNOTATION_CALL_TYPE_FASTCALL,   DR_ANNOTATION_CALL_TYPE_VARARG = DR_ANNOTATION_CALL_TYPE_FASTCALL,   DR_ANNOTATION_CALL_TYPE_LAST }

Functions
static void	dr_annotation_set_return_value (reg_t value)
DR_API bool	dr_annotation_register_call (const char *annotation_name, void *callee, bool save_fpstate, uint num_args, dr_annotation_calling_convention_t call_type)
DR_API bool	dr_annotation_register_valgrind (dr_valgrind_request_id_t request_id, ptr_uint_t(*annotation_callback)(dr_vg_client_request_t *request))
DR_API bool	dr_annotation_register_return (const char *annotation_name, void *return_value)
DR_API bool	dr_annotation_pass_pc (const char *annotation_name)
DR_API bool	dr_annotation_unregister_call (const char *annotation_name, void *callee)
DR_API bool	dr_annotation_unregister_return (const char *annotation_name)
DR_API bool	dr_annotation_unregister_valgrind (dr_valgrind_request_id_t request_id, ptr_uint_t(*annotation_callback)(dr_vg_client_request_t *request))

Detailed Description

Annotation handler registration routines.

Typedef Documentation

dr_annotation_calling_convention_t

typedef enum _dr_annotation_calling_convention_t dr_annotation_calling_convention_t

Defines the calling conventions that are supported for annotation functions (as they appear in the target app).

dr_valgrind_request_id_t

typedef enum _dr_valgrind_request_id_t dr_valgrind_request_id_t

Synonyms for the Valgrind client request IDs (sequential from 0 for convenience).

dr_vg_client_request_t

typedef struct _dr_vg_client_request_t dr_vg_client_request_t

Defines the Valgrind client request object, which is constructed by each instance of a Valgrind annotation in the target app. An instance is passed to Valgrind annotation callback functions to make the arguments available. Some arguments may be undefined for some Valgrind client requests; see the Valgrind documentation for each specific Valgrind client request for details about the arguments.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
DR_VG_NUM_ARGS	Defines the maximum number of arguments that can be passed to a Valgrind annotation, and accordingly specifies the length of the array vg_client_request_t.args.

_dr_annotation_calling_convention_t

enum _dr_annotation_calling_convention_t

Defines the calling conventions that are supported for annotation functions (as they appear in the target app).

Enumerator
DR_ANNOTATION_CALL_TYPE_FASTCALL	calling convention "fastcall"
DR_ANNOTATION_CALL_TYPE_VARARG	The calling convention for vararg functions on x64, which must be "fastcall".
DR_ANNOTATION_CALL_TYPE_LAST	Sentinel value for iterator convenience

_dr_valgrind_request_id_t

enum _dr_valgrind_request_id_t

Synonyms for the Valgrind client request IDs (sequential from 0 for convenience).

Enumerator
DR_VG_ID__RUNNING_ON_VALGRIND	Return true if running in DynamoRIO with Valgrind annotation support. No args.
DR_VG_ID__DO_LEAK_CHECK	Request an immediate memory scan to look for leaks. Not currently implemented in core DR.
DR_VG_ID__MAKE_MEM_DEFINED_IF_ADDRESSABLE	Indicate that the specified range of addresses should be considered defined if it is addressable. Not currently implemented in core DR.
DR_VG_ID__DISCARD_TRANSLATIONS	Request that DynamoRIO discard all fragments in the code cache that were translated from the specified range of addresses. The request takes 2 args, start and length. It is implemented in core DR with JIT optimization enabled, though clients may implement additional functionality.
DR_VG_ID__LAST	Sentinel value for iterator convenience.

Function Documentation

dr_annotation_pass_pc()

DR_API bool dr_annotation_pass_pc

(

const char *

annotation_name

)

Can only be called on an annotation already registered with dr_annotation_register_call(). When the annotation is encountered, the PC of the annotation interruption point will be available in DR scratch slot SPILL_SLOT_2, which can be read with dr_read_saved_reg().

Parameters

[in]

annotation_name

The name of the annotation function as it appears in the target app's source code (unmangled).

dr_annotation_register_call()

DR_API bool dr_annotation_register_call	(	const char *	annotation_name,
		void *	callee,
		bool	save_fpstate,
		uint	num_args,
		dr_annotation_calling_convention_t	call_type
	)

Register a handler for a DR annotation. When the annotation is encountered, it will be replaced with a clean call to the specified callee, which must have the specified number of arguments. Returns true on successful registration.

Parameters

[in]	annotation_name	The name of the annotation function as it appears in the target app's source code (unmangled).
[in]	callee	The client function to call when an instance of the specified annotation is executed.
[in]	save_fpstate	Indicates whether to save floating point state before making the clean call to the callee.
[in]	num_args	The number of arguments in the annotation function (must also match the number of arguments in the callee).
[in]	call_type	The calling convention of the annotation function as compiled in the target app (x86 only).

dr_annotation_register_return()

DR_API bool dr_annotation_register_return	(	const char *	annotation_name,
		void *	return_value
	)

Register a return value substitution for a DR annotation. When the annotation is encountered, it will be replaced with the specified return value. This function returns true on successful registration.

Parameters

[in]	annotation_name	The name of the annotation function as it appears in the target app's source code (unmangled).
[in]	return_value	The value to return from every instance of the annotation.

dr_annotation_register_valgrind()

DR_API bool dr_annotation_register_valgrind	(	dr_valgrind_request_id_t	request_id,
		ptr_uint_t(*)(dr_vg_client_request_t *request)	annotation_callback
	)

Register a callback for a Valgrind client request id. When the request is encountered, the specified callback will be invoked by an internal routing function. Returns true on successful registration.

Parameters

[in]	request_id	The Valgrind request id for which to register.
[in]	annotation_callback	The client function to call when an instance of the specified Valgrind client request is executed.

dr_annotation_set_return_value()

static void dr_annotation_set_return_value ( reg_t  value )

inlinestatic

Facilitates returning a value from an annotation invocation in the target app. This function should be used within the annotation clean call, and the specified value will be received in the target app by the annotation caller. This function may be invoked multiple times, in which case only the last value will take effect.

Parameters

[in]

value

The return value (unsigned, pointer-sized) that will be received in the target app.

dr_annotation_unregister_call()

DR_API bool dr_annotation_unregister_call	(	const char *	annotation_name,
		void *	callee
	)

Unregister the specified handler from a DR annotation. Instances of the annotation that have already been substituted with a clean call to the registered callee will remain in the code cache, but any newly encountered instances of the annotation will no longer be substituted with this callee. This function does nothing in the case that the specified callee was never registered for this annotation (or has already been unregistered). Returns true if the registration was successfully unregistered.

Parameters

[in]	annotation_name	The annotation function for which to unregister.
[in]	callee	The callee to unregister.

dr_annotation_unregister_return()

DR_API bool dr_annotation_unregister_return

(

const char *

annotation_name

)

Unregister the (universal) return value from a DR annotation. Instances of the annotation that have already been substituted with the return value will remain in the code cache, but any newly encountered instances of the annotation will no longer be substituted. This function does nothing in the case that no return value is currently registered for the specified annotation (or has already been unregistered). Note that if another client has registered a return value, this function will remove that other client's registration. Returns true if the registration was successfully unregistered.

Parameters

[in]

annotation_name

The annotation function for which to unregister.

dr_annotation_unregister_valgrind()

DR_API bool dr_annotation_unregister_valgrind	(	dr_valgrind_request_id_t	request_id,
		ptr_uint_t(*)(dr_vg_client_request_t *request)	annotation_callback
	)

Unregister the specified callback from a Valgrind client request. The registered callback will not be invoked in association with this client request again (though if the same callback function is also registered for other Valgrind client requests, it will still be invoked in association with those client requests). This function does nothing in the case that no handler was ever registered for this callback function. Returns true if the registration was found and successfully unregistered.

Parameters

[in]	request_id	The request id for which to unregister (DR_VG__*).
[in]	annotation_callback	The callback function to unregister.