xray_interface.h File Reference

#include <cstddef>
#include <cstdint>

Include dependency graph for xray_interface.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	XRayEntryType {   ENTRY = 0 , EXIT = 1 , TAIL = 2 , LOG_ARGS_ENTRY = 3 ,   CUSTOM_EVENT = 4 , TYPED_EVENT = 5 }
	Synchronize this with AsmPrinter::SledKind in LLVM. More...
enum	XRayPatchingStatus { NOT_INITIALIZED = 0 , SUCCESS = 1 , ONGOING = 2 , FAILED = 3 }

Functions
int	__xray_set_handler (void(*entry)(int32_t, XRayEntryType))
	Provide a function to invoke for when instrumentation points are hit.
int	__xray_remove_handler ()
	This removes whatever the currently provided handler is.
int	__xray_set_handler_arg1 (void(*entry)(int32_t, XRayEntryType, uint64_t))
	Use XRay to log the first argument of each (instrumented) function call.
int	__xray_remove_handler_arg1 ()
	Disables the XRay handler used to log first arguments of function calls.
int	__xray_set_customevent_handler (void(*entry)(void *, std::size_t))
	Provide a function to invoke when XRay encounters a custom event.
int	__xray_remove_customevent_handler ()
	This removes whatever the currently provided custom event handler is.
int	__xray_set_typedevent_handler (void(*entry)(uint16_t, const void *, std::size_t))
	Set a handler for xray typed event logging.
int	__xray_remove_typedevent_handler ()
	Removes the currently set typed event handler.
uint16_t	__xray_register_event_type (const char *event_type)
XRayPatchingStatus	__xray_patch ()
	This tells XRay to patch the instrumentation points.
XRayPatchingStatus	__xray_unpatch ()
	Reverses the effect of __xray_patch().
XRayPatchingStatus	__xray_patch_function (int32_t FuncId)
	This patches a specific function id.
XRayPatchingStatus	__xray_unpatch_function (int32_t FuncId)
	This unpatches a specific function id.
uintptr_t	__xray_function_address (int32_t FuncId)
	This function returns the address of the function provided a valid function id.
size_t	__xray_max_function_id ()
	This function returns the maximum valid function id.
void	__xray_init ()
	Initialize the required XRay data structures.

Enumeration Type Documentation

XRayEntryType

enum XRayEntryType

Synchronize this with AsmPrinter::SledKind in LLVM.

Enumerator
ENTRY
EXIT
TAIL
LOG_ARGS_ENTRY
CUSTOM_EVENT
TYPED_EVENT

Definition at line 23 of file xray_interface.h.

XRayPatchingStatus

enum XRayPatchingStatus

Enumerator
NOT_INITIALIZED
SUCCESS
ONGOING
FAILED

Definition at line 88 of file xray_interface.h.

Function Documentation

__xray_function_address()

uintptr_t __xray_function_address ( int32_t  FuncId )

extern

This function returns the address of the function provided a valid function id.

We return 0 if we encounter any error, even if 0 may be a valid function address.

__xray_init()

void __xray_init ( )

extern

Initialize the required XRay data structures.

This is useful in cases where users want to control precisely when the XRay instrumentation data structures are initialized, for example when the XRay library is built with the XRAY_NO_PREINIT preprocessor definition.

Calling __xray_init() more than once is safe across multiple threads.

__xray_max_function_id()

size_t __xray_max_function_id ( )

extern

This function returns the maximum valid function id.

Returns 0 if we encounter errors (when there are no instrumented functions, etc.).

__xray_patch()

XRayPatchingStatus __xray_patch ( )

extern

This tells XRay to patch the instrumentation points.

See XRayPatchingStatus for possible result values.

__xray_patch_function()

XRayPatchingStatus __xray_patch_function ( int32_t  FuncId )

extern

This patches a specific function id.

See XRayPatchingStatus for possible result values.

__xray_register_event_type()

uint16_t __xray_register_event_type ( const char *  event_type )

extern

__xray_remove_customevent_handler()

int __xray_remove_customevent_handler ( )

extern

This removes whatever the currently provided custom event handler is.

Returns 1 on success, 0 on error.

__xray_remove_handler()

int __xray_remove_handler ( )

extern

This removes whatever the currently provided handler is.

Returns 1 on success, 0 on error.

__xray_remove_handler_arg1()

int __xray_remove_handler_arg1 ( )

extern

Disables the XRay handler used to log first arguments of function calls.

Returns 1 on success, 0 on error.

__xray_remove_typedevent_handler()

int __xray_remove_typedevent_handler ( )

extern

Removes the currently set typed event handler.

Returns 1 on success, 0 on error.

__xray_set_customevent_handler()

int __xray_set_customevent_handler ( void(*)(void *, std::size_t)  entry )

extern

Provide a function to invoke when XRay encounters a custom event.

__xray_set_handler()

int __xray_set_handler ( void(*)(int32_t, XRayEntryType)  entry )

extern

Provide a function to invoke for when instrumentation points are hit.

This is a user-visible control surface that overrides the default implementation. The function provided should take the following arguments:

• function id: an identifier that indicates the id of a function; this id is generated by xray; the mapping between the function id and the actual function pointer is available through __xray_table.
• entry type: identifies what kind of instrumentation point was encountered (function entry, function exit, etc.). See the enum XRayEntryType for more details.

The user handler must handle correctly spurious calls after this handler is removed or replaced with another handler, because it would be too costly for XRay runtime to avoid spurious calls. To prevent circular calling, the handler function itself and all its direct&indirect callees must not be instrumented with XRay, which can be achieved by marking them all with: __attribute__((xray_never_instrument))

Returns 1 on success, 0 on error.

__xray_set_handler_arg1()

int __xray_set_handler_arg1 ( void(*)(int32_t, XRayEntryType, uint64_t)  entry )

extern

Use XRay to log the first argument of each (instrumented) function call.

When this function exits, all threads will have observed the effect and start logging their subsequent affected function calls (if patched).

Returns 1 on success, 0 on error.

__xray_set_typedevent_handler()

int __xray_set_typedevent_handler ( void(*)(uint16_t, const void *, std::size_t)  entry )

extern

Set a handler for xray typed event logging.

The first parameter is a type identifier, the second is a payload, and the third is the payload size.

__xray_unpatch()

XRayPatchingStatus __xray_unpatch ( )

extern

Reverses the effect of __xray_patch().

See XRayPatchingStatus for possible result values.

__xray_unpatch_function()

XRayPatchingStatus __xray_unpatch_function ( int32_t  FuncId )

extern

This unpatches a specific function id.

See XRayPatchingStatus for possible result values.