1 //===- xray_interface.h -----------------------------------------*- C++ -*-===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===----------------------------------------------------------------------===// 9 // 10 // This file is a part of XRay, a dynamic runtime instrumentation system. 11 // 12 // APIs for controlling XRay functionality explicitly. 13 //===----------------------------------------------------------------------===// 14 15 #ifndef XRAY_XRAY_INTERFACE_H 16 #define XRAY_XRAY_INTERFACE_H 17 18 #include <cstddef> 19 #include <cstdint> 20 21 extern "C" { 22 23 /// Synchronize this with AsmPrinter::SledKind in LLVM. 24 enum XRayEntryType { 25 ENTRY = 0, 26 EXIT = 1, 27 TAIL = 2, 28 LOG_ARGS_ENTRY = 3, 29 CUSTOM_EVENT = 4, 30 TYPED_EVENT = 5, 31 }; 32 33 /// Provide a function to invoke for when instrumentation points are hit. This 34 /// is a user-visible control surface that overrides the default implementation. 35 /// The function provided should take the following arguments: 36 /// 37 /// - function id: an identifier that indicates the id of a function; this id 38 /// is generated by xray; the mapping between the function id 39 /// and the actual function pointer is available through 40 /// __xray_table. 41 /// - entry type: identifies what kind of instrumentation point was 42 /// encountered (function entry, function exit, etc.). See the 43 /// enum XRayEntryType for more details. 44 /// 45 /// The user handler must handle correctly spurious calls after this handler is 46 /// removed or replaced with another handler, because it would be too costly for 47 /// XRay runtime to avoid spurious calls. 48 /// To prevent circular calling, the handler function itself and all its 49 /// direct&indirect callees must not be instrumented with XRay, which can be 50 /// achieved by marking them all with: __attribute__((xray_never_instrument)) 51 /// 52 /// Returns 1 on success, 0 on error. 53 extern int __xray_set_handler(void (*entry)(int32_t, XRayEntryType)); 54 55 /// This removes whatever the currently provided handler is. Returns 1 on 56 /// success, 0 on error. 57 extern int __xray_remove_handler(); 58 59 /// Use XRay to log the first argument of each (instrumented) function call. 60 /// When this function exits, all threads will have observed the effect and 61 /// start logging their subsequent affected function calls (if patched). 62 /// 63 /// Returns 1 on success, 0 on error. 64 extern int __xray_set_handler_arg1(void (*entry)(int32_t, XRayEntryType, 65 uint64_t)); 66 67 /// Disables the XRay handler used to log first arguments of function calls. 68 /// Returns 1 on success, 0 on error. 69 extern int __xray_remove_handler_arg1(); 70 71 /// Provide a function to invoke when XRay encounters a custom event. 72 extern int __xray_set_customevent_handler(void (*entry)(void *, std::size_t)); 73 74 /// This removes whatever the currently provided custom event handler is. 75 /// Returns 1 on success, 0 on error. 76 extern int __xray_remove_customevent_handler(); 77 78 /// Set a handler for xray typed event logging. The first parameter is a type 79 /// identifier, the second is a payload, and the third is the payload size. 80 extern int __xray_set_typedevent_handler(void (*entry)(uint16_t, const void *, 81 std::size_t)); 82 83 /// Removes the currently set typed event handler. 84 /// Returns 1 on success, 0 on error. 85 extern int __xray_remove_typedevent_handler(); 86 87 extern uint16_t __xray_register_event_type(const char *event_type); 88 89 enum XRayPatchingStatus { 90 NOT_INITIALIZED = 0, 91 SUCCESS = 1, 92 ONGOING = 2, 93 FAILED = 3, 94 }; 95 96 /// This tells XRay to patch the instrumentation points. See XRayPatchingStatus 97 /// for possible result values. 98 extern XRayPatchingStatus __xray_patch(); 99 100 /// Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible 101 /// result values. 102 extern XRayPatchingStatus __xray_unpatch(); 103 104 /// This patches a specific function id. See XRayPatchingStatus for possible 105 /// result values. 106 extern XRayPatchingStatus __xray_patch_function(int32_t FuncId); 107 108 /// This unpatches a specific function id. See XRayPatchingStatus for possible 109 /// result values. 110 extern XRayPatchingStatus __xray_unpatch_function(int32_t FuncId); 111 112 /// This function returns the address of the function provided a valid function 113 /// id. We return 0 if we encounter any error, even if 0 may be a valid function 114 /// address. 115 extern uintptr_t __xray_function_address(int32_t FuncId); 116 117 /// This function returns the maximum valid function id. Returns 0 if we 118 /// encounter errors (when there are no instrumented functions, etc.). 119 extern size_t __xray_max_function_id(); 120 121 /// Initialize the required XRay data structures. This is useful in cases where 122 /// users want to control precisely when the XRay instrumentation data 123 /// structures are initialized, for example when the XRay library is built with 124 /// the XRAY_NO_PREINIT preprocessor definition. 125 /// 126 /// Calling __xray_init() more than once is safe across multiple threads. 127 extern void __xray_init(); 128 129 } // end extern "C" 130 131 #endif // XRAY_XRAY_INTERFACE_H 132
Indexes created Sat Sep 20 22:09:52 GMT 2025