]>
git.proxmox.com Git - rustc.git/blob - src/libcompiler_builtins/compiler-rt/include/xray/xray_interface.h
1 //===- xray_interface.h -----------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file is a part of XRay, a dynamic runtime instrumentation system.
12 // APIs for controlling XRay functionality explicitly.
13 //===----------------------------------------------------------------------===//
15 #ifndef XRAY_XRAY_INTERFACE_H
16 #define XRAY_XRAY_INTERFACE_H
23 /// Synchronize this with AsmPrinter::SledKind in LLVM.
32 /// Provide a function to invoke for when instrumentation points are hit. This
33 /// is a user-visible control surface that overrides the default implementation.
34 /// The function provided should take the following arguments:
36 /// - function id: an identifier that indicates the id of a function; this id
37 /// is generated by xray; the mapping between the function id
38 /// and the actual function pointer is available through
40 /// - entry type: identifies what kind of instrumentation point was
41 /// encountered (function entry, function exit, etc.). See the
42 /// enum XRayEntryType for more details.
44 /// The user handler must handle correctly spurious calls after this handler is
45 /// removed or replaced with another handler, because it would be too costly for
46 /// XRay runtime to avoid spurious calls.
47 /// To prevent circular calling, the handler function itself and all its
48 /// direct&indirect callees must not be instrumented with XRay, which can be
49 /// achieved by marking them all with: __attribute__((xray_never_instrument))
51 /// Returns 1 on success, 0 on error.
52 extern int __xray_set_handler(void (*entry
)(int32_t, XRayEntryType
));
54 /// This removes whatever the currently provided handler is. Returns 1 on
55 /// success, 0 on error.
56 extern int __xray_remove_handler();
58 /// Use XRay to log the first argument of each (instrumented) function call.
59 /// When this function exits, all threads will have observed the effect and
60 /// start logging their subsequent affected function calls (if patched).
62 /// Returns 1 on success, 0 on error.
63 extern int __xray_set_handler_arg1(void (*entry
)(int32_t, XRayEntryType
,
66 /// Disables the XRay handler used to log first arguments of function calls.
67 /// Returns 1 on success, 0 on error.
68 extern int __xray_remove_handler_arg1();
70 /// Provide a function to invoke when XRay encounters a custom event.
71 extern int __xray_set_customevent_handler(void (*entry
)(void*, std::size_t));
73 /// This removes whatever the currently provided custom event handler is.
74 /// Returns 1 on success, 0 on error.
75 extern int __xray_remove_customevent_handler();
77 enum XRayPatchingStatus
{
84 /// This tells XRay to patch the instrumentation points. See XRayPatchingStatus
85 /// for possible result values.
86 extern XRayPatchingStatus
__xray_patch();
88 /// Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible
90 extern XRayPatchingStatus
__xray_unpatch();
92 /// This patches a specific function id. See XRayPatchingStatus for possible
94 extern XRayPatchingStatus
__xray_patch_function(int32_t FuncId
);
96 /// This unpatches a specific function id. See XRayPatchingStatus for possible
98 extern XRayPatchingStatus
__xray_unpatch_function(int32_t FuncId
);
100 /// This function returns the address of the function provided a valid function
101 /// id. We return 0 if we encounter any error, even if 0 may be a valid function
103 extern uintptr_t __xray_function_address(int32_t FuncId
);
105 /// This function returns the maximum valid function id. Returns 0 if we
106 /// encounter errors (when there are no instrumented functions, etc.).
107 extern size_t __xray_max_function_id();
109 /// Initialize the required XRay data structures. This is useful in cases where
110 /// users want to control precisely when the XRay instrumentation data
111 /// structures are initialized, for example when the XRay library is built with
112 /// the XRAY_NO_PREINIT preprocessor definition.
114 /// Calling __xray_init() more than once is safe across multiple threads.
115 extern void __xray_init();
119 #endif // XRAY_XRAY_INTERFACE_H