DynamoRIO API
dr_annotation.h File Reference

Annotation handler registration routines. More...

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)
 
bool dr_annotation_register_call (const char *annotation_name, void *callee, bool save_fpstate, uint num_args, dr_annotation_calling_convention_t call_type)
 
bool dr_annotation_register_valgrind (dr_valgrind_request_id_t request_id, ptr_uint_t(*annotation_callback)(dr_vg_client_request_t *request))
 
bool dr_annotation_register_return (const char *annotation_name, void *return_value)
 
bool dr_annotation_unregister_call (const char *annotation_name, void *callee)
 
bool dr_annotation_unregister_return (const char *annotation_name)
 
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

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

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

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

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

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

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_nameThe name of the annotation function as it appears in the target app's source code (unmangled).
[in]calleeThe client function to call when an instance of the specified annotation is executed.
[in]save_fpstateIndicates whether to save floating point state before making the clean call to the callee.
[in]num_argsThe number of arguments in the annotation function (must also match the number of arguments in the callee).
[in]call_typeThe calling convention of the annotation function as compiled in the target app (x86 only).
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_nameThe name of the annotation function as it appears in the target app's source code (unmangled).
[in]return_valueThe value to return from every instance of the annotation.
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_idThe Valgrind request id for which to register.
[in]annotation_callbackThe client function to call when an instance of the specified Valgrind client request is executed.
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]valueThe return value (unsigned, pointer-sized) that will be received in the target app.
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_nameThe annotation function for which to unregister.
[in]calleeThe callee to unregister.
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_nameThe annotation function for which to unregister.
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_idThe request id for which to unregister (DR_VG__*).
[in]annotation_callbackThe callback function to unregister.